OpenStack MCP Server v0.1.0 (현대화 버전)

완전히 현대화된 OpenStack Model Context Protocol 서버
nest-asyncio + pydantic-settings 2.0+ 적용으로 안정성과 사용성 대폭 향상

Claude Desktop과 연동하여 OpenStack을 자연어로 제어할 수 있는 현대적이고 안정적인 MCP 서버입니다.

새로운 기능들 (v0.1.0)

안정성 향상

• [Fix] nest-asyncio 적용: 이벤트 루프 충돌 문제 완전 해결
• [Tool] 향상된 오류 처리: 상세한 진단 및 복구 안내
• [Check] 스마트 진단: 자동 문제 감지 및 해결책 제시

현대적 설정 관리

• [Config] pydantic-settings 2.0+: 타입 안전성과 자동 검증
• [Secure] 보안 강화: 민감 정보 자동 마스킹
• [Structure] 정리된 구조: 환경변수 우선순위 체계

향상된 사용자 경험

• [Chat] 자연어 인터페이스: 더욱 직관적인 대화형 제어
• [Mock] Mock 모드: OpenStack 없이도 완전한 기능 테스트
• [Monitor] 실시간 상태 모니터링: 건강 상태 및 성능 지표

빠른 시작 (2분)

Mock 모드 (OpenStack 없이 즉시 테스트)

# 1. 의존성 설치
poetry install

# 2. Mock 모드로 바로 실행
poetry run python src/main.py --mock-mode

# 3. 성공 메시지 확인
# [OK] OpenStack 연결 성공! (Mock 모드)
# [Start] MCP 서버 시작 중...

실제 OpenStack 연결

# 1. 환경변수 설정 (가장 간단)
export MCP__MOCK_MODE=false
export OPENSTACK__AUTH_URL=http://your-openstack:5000/v3
export OPENSTACK__USERNAME=admin
export OPENSTACK__PASSWORD=your_password

# 2. 서버 실행
poetry run python src/main.py

설치 및 설정

사전 요구사항

• Python: 3.10 이상
• Poetry: 최신 버전
• Claude Desktop: 최신 버전
• OpenStack: DevStack, All-in-One, 또는 프로덕션 환경 (Mock 모드에서는 불필요)

의존성 설치

# 프로젝트 클론
git clone <repository-url>
cd ktc-openstack-mcp

# 새로운 의존성 설치 (중요!)
poetry install --sync

# 설치 확인 테스트
python test_mcp_simple.py

설정 방법

환경변수 또는 .env 파일을 사용하여 설정을 관리합니다. 두 방식은 함께 사용할 수 있으며, 환경변수가 항상 우선됩니다.

방법 1: .env 파일 (권장)

가장 일반적인 방법입니다. 제공된 예제 파일을 복사하여 시작하세요.

# 1. .env.example 파일을 .env로 복사
cp .env.example .env

# 2. .env 파일 수정
nano .env

.env 파일에서 필요한 설정을 수정합니다. 최소한 OPENSTACK_ 관련 변수들은 실제 환경에 맞게 변경해야 합니다.

# .env

# Mock 모드 비활성화 (실제 OpenStack 사용 시)
MCP_MOCK_MODE=false

# OpenStack 연결 정보
OPENSTACK_AUTH_URL=http://your-openstack-ip:5000/v3
OPENSTACK_USERNAME=your_username
OPENSTACK_PASSWORD=your_password
OPENSTACK_PROJECT_NAME=your_project_name

방법 2: 환경변수 직접 설정

쉘에서 직접 환경변수를 설정하여 서버를 실행할 수도 있습니다. 이 방식은 .env 파일의 설정을 덮어씁니다.

# 실제 OpenStack 연결 예시
export MCP_MOCK_MODE=false
export OPENSTACK_AUTH_URL="http://192.168.1.100:5000/v3"
export OPENSTACK_USERNAME="admin"
export OPENSTACK_PASSWORD="secure_password_123"

poetry run python src/main.py

Claude Desktop 연동

설정 파일 위치

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

설정 파일 업데이트

{
  "mcpServers": {
    "openstack-mcp": {
      "command": "poetry",
      "args": ["run", "python", "src/main.py", "--mock-mode"],
      "cwd": "C:\\절대경로\\to\\ktc-openstack-mcp",
      "env": {
        "PYTHONPATH": "C:\\절대경로\\to\\ktc-openstack-mcp",
        "PYTHONUNBUFFERED": "1",
        "MCP__MOCK_MODE": "true",
        "MCP__LOG_LEVEL": "INFO"
      }
    }
  }
}

[Tip]: claude_desktop_config.example.json 파일 참조

연결 테스트

1. Claude Desktop 완전 종료 후 재시작
2. 연결 상태 확인 (하단 녹색 표시)
3. 첫 테스트: "OpenStack 서버 목록을 보여주세요"

사용 방법

기본 조회

"OpenStack 서버 목록을 보여주세요"
"이미지 목록을 10개만 보여주세요"
"연결 상태를 확인해주세요"
"플레이버 목록을 보여주세요"

고급 검색

"실행 중인 서버만 5개 보여주세요"
"Ubuntu 이미지를 찾아주세요"
"web이라는 이름이 들어간 서버를 검색해주세요"
"공개 이미지만 조회해주세요"

서버 관리

"새 서버를 만들어주세요. 이름은 web-01, Ubuntu 22.04 이미지로 m1.medium 플레이버로"
"web-server-01을 재시작해주세요"
"test-server를 중지시켜주세요"
"old-server를 삭제해주세요 (confirm=true 필요)"

진단 및 모니터링

"시스템 상태를 진단해주세요"
"연결 문제를 분석해주세요"
"서버 현황을 요약해주세요"
"서비스 상태를 확인해주세요"

문제 해결

"Already running asyncio" 오류

[OK] 해결됨! nest-asyncio 패치로 완전 해결

# 이제 다음이 안전하게 작동합니다:
poetry run python src/main.py --mock-mode

연결 진단

# 1. 통합 테스트 실행
python test_mcp_simple.py

# 2. 설정 검증
poetry run python -c "
from src.config.settings import get_settings
settings = get_settings()
print('Mock 모드:', settings.mcp.mock_mode)
print('OpenStack URL:', settings.openstack.auth_url)
"

# 3. 수동 연결 테스트
poetry run python src/main.py --mock-mode --debug

의존성 문제

# 완전 재설치
poetry lock --no-update
poetry install --sync

# 캐시 정리
poetry cache clear . --all

Claude Desktop 연결 실패

1. 절대 경로 사용 - 상대 경로 금지
2. 경로 구분자 확인 - Windows: \\, Unix: /
3. 권한 확인 - Poetry 실행 권한
4. 로그 확인 - Claude Desktop 개발자 도구 (Ctrl+Shift+I)

현대화된 프로젝트 구조

ktc-openstack-mcp/
├── [Project] 프로젝트 루트
│   ├── .env                       # 환경변수 (git에서 제외)
│   ├── .env.example              # 환경변수 템플릿
│   ├── pyproject.toml            # 현대적 의존성 관리
│   └── test_mcp_simple.py        # 통합 테스트
│
├── [Source] src/ (소스 코드)
│   ├── main.py                   # [Fix] 현대화된 진입점
│   ├── config/
│   │   └── settings.py           # [Config] pydantic-settings 기반
│   ├── core/
│   │   ├── mcp_server.py         # [Init] nest-asyncio 적용
│   │   ├── openstack_client.py   # [API] 향상된 API 클라이언트
│   │   ├── mock_client.py        # [Mock] 완전한 Mock 구현
│   │   ├── exceptions.py         # [Tool] 구조화된 예외 처리
│   │   └── utils.py              # [Fix] 유틸리티 함수
│   └── tools/ & resources/       # [Tool] MCP 도구 및 리소스
│
└── [Docs] 문서 및 설정
    ├── claude_desktop_config.example.json
    ├── usage_examples.md
    └── README.md (이 파일)

테스트 및 개발

통합 테스트

# 전체 시스템 테스트
python test_mcp_simple.py

# 성공 출력 예시:
# [OK] 패키지 Import 테스트 통과
# [OK] 설정 시스템 테스트 통과
# [OK] 서버 생성 테스트 통과
# [OK] Asyncio 호환성 테스트 통과
# [OK] Mock 기능 테스트 통과
# [Success] 모든 테스트 통과!

개발 도구

# 코드 포맷팅
poetry run black src/

# 타입 체크
poetry run mypy src/

# 테스트 실행
poetry run pytest

명령줄 옵션

# Mock 모드
poetry run python src/main.py --mock-mode

# 디버그 모드
poetry run python src/main.py --mock-mode --debug

# 로그 레벨 설정
poetry run python src/main.py --log-level DEBUG

# 도움말
poetry run python src/main.py --help

기술 스택

핵심 기술

• MCP: Model Context Protocol
• FastMCP: 현대적 MCP 서버 프레임워크
• nest-asyncio: 이벤트 루프 충돌 해결
• pydantic-settings: 타입 안전 설정 관리

지원 기술

• Poetry: 현대적 의존성 관리
• Python 3.10+: 최신 언어 기능
• OpenStack SDK: 공식 API 클라이언트
• JSON Schema: 자동 검증

로드맵

[OK] Phase 1: 현대화 (완료)

• nest-asyncio 적용
• pydantic-settings 도입
• 프로젝트 구조 현대화
• 완전한 Mock 모드

[In Progress] Phase 2: 확장 기능 (진행 중)

• 고급 서버 관리 (스냅샷, 백업)
• 네트워크 및 볼륨 관리
• 실시간 모니터링
• 알림 시스템

[Plan] Phase 3: 엔터프라이즈 (계획)

• 멀티 클러스터 지원
• RBAC (역할 기반 접근 제어)
• 감사 로그
• 대시보드 연동

기여하기

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

개발 가이드라인

• 타입 힌트 필수 사용
• pydantic 모델 활용
• asyncio 안전성 고려
• 테스트 작성 필수

라이센스

이 프로젝트는 MIT 라이센스하에 배포됩니다.

지원 및 커뮤니티

문제 해결

• Issues - 버그 리포트 및 기능 요청
• Discussions - 질문 및 아이디어 공유

참고 자료

• OpenStack API 문서
• Model Context Protocol
• pydantic-settings 가이드

감사의 말

• Anthropic - Model Context Protocol 개발
• OpenStack - 클라우드 인프라 플랫폼
• FastMCP - MCP 서버 프레임워크
• Pydantic - 타입 안전 데이터 검증

---

마지막 체크리스트

설치 후 확인사항

1. 의존성 설치: poetry install --sync [OK]
2. 테스트 실행: python test_mcp_simple.py [OK]
3. Mock 모드: poetry run python src/main.py --mock-mode [OK]
4. Claude Desktop 설정 [OK]
5. 첫 번째 대화: "OpenStack 서버 목록을 보여주세요" [OK]

성공 지표

• 이벤트 루프 충돌 없음 [OK]
• 타입 안전 설정 관리 [OK]
• Mock 모드 완전 작동 [OK]
• 자연어 명령 인식 [OK]

---

Happy Cloud Computing with Modern OpenStack MCP Server!

"OpenStack을 이제 Claude와 대화하듯 제어하세요!"