Python MCP Server Kit

안전하고 타입이 지정된, 테스트 가능한 Model Context Protocol 서버를 위한 백엔드 전용 스타터입니다. 공식 Python SDK v2를 통해 MCP 2026-07-28 프로토콜을 대상으로 하며, 배포에는 상태 비저장(stateless) Streamable HTTP를 사용합니다.

기능

• 타입이 지정된 도구 및 구조화된 Pydantic 출력

• 범용 계산기 및 결정적(deterministic) 카탈로그 예제

• MCP 도구, 리소스, 프롬프트

• Bearer 토큰 경계 및 도구별 스코프

• 요청 크기, 호스트, 프로세스 내(in-process) 비율 제한

• Correlation ID 및 구조화된 요청 로그

• 공개 상태(health) 및 준비(readiness) 프로브

• 단위 테스트 및 HTTP 통합 테스트

• 프로덕션 스타일의 비루트(non-root) Docker 이미지

• 린트, 포맷팅, 타입 검사, 테스트, 이미지 빌드, 시크릿, 워크플로우를 위한 CI

Related MCP server: MCP TypeScript SDK

아키텍처

HTTP request
  -> SecurityMiddleware (host, size, auth, rate limit, request ID)
  -> MCP Streamable HTTP transport
  -> typed tool/resource/prompt
  -> scope check
  -> deterministic domain function

프로토콜 등록은 src/mcp_server_kit/server.py에 있으며, 재사용 가능한 도메인 로직은 별도 모듈에 유지됩니다. TokenStore는 완전한 인가 서버가 아니라 의도적으로 교체 가능한 배포 경계입니다.

빠른 시작

Python 3.11 이상이 필요합니다.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\scripts\dev.ps1

MCP 엔드포인트는 http://127.0.0.1:8000/mcp입니다. 상태(health) 및 준비(readiness) 프로브는 /health와 /ready에서 확인할 수 있습니다. 로컬 전용 데모 토큰은 다음과 같습니다.

• demo-reader — catalog:read

• demo-operator — catalog:read, calculator:use

npx -y @modelcontextprotocol/inspector로 MCP Inspector를 실행하고 Authorization: Bearer demo-operator 헤더를 설정하세요. 자격 증명이 필요 없는 클라이언트 구성은 examples/client.json에서 제공됩니다. 로컬에서는 MCP_CLIENT_TOKEN을 주입하세요.

명령어

.\scripts\dev.ps1    # development server with reload
.\scripts\check.ps1  # lint, format check, mypy, and tests
docker compose up --build

구성

.env는 절대 커밋하지 마세요. 인터넷에 노출되는 배포 전에 보안 및 배포를 참조하고, 레지스트리를 확장할 때는 도구 추가를 참조하세요.

배포 참고 사항

MCP_ENVIRONMENT=production, MCP_AUTH_MODE=bearer, 시크릿으로 관리되는 MCP_BEARER_TOKENS 값, 그리고 정확한 공개 호스트 허용 목록을 설정하세요. TLS는 신뢰할 수 있는 리버스 프록시에서 종료하세요. 사용자 위임이나 토큰 수명 주기 관리가 필요하면 스타터 토큰 저장소를 자체 OAuth 2.1 리소스 서버 검증기로 교체하세요.

라이선스

MIT