Python MCP Server Kit

バックエンド専用の、セキュアで型付けされ、テスト可能なModel Context Protocolサーバー向けスターターです。公式Python SDK v2を介してMCP 2026-07-28 プロトコルを対象とし、デプロイにはステートレスなStreamable HTTPを使用します。

機能

• 構造化されたPydantic出力を持つ型付きツール

• 汎用計算機と決定論的カタログの例

• MCPツール、リソース、プロンプト

• ベアラートークンの境界とツール単位のスコープ

• リクエストサイズ、ホスト、インプロセスのレート制限

• 相関IDと構造化リクエストログ

• 公開のヘルスプローブとレディネスプローブ

• ユニットテストとHTTP統合テスト

• 本番向け非root Dockerイメージ

• lint、フォーマット、型チェック、テスト、イメージビルド、シークレット、ワークフロー向け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 と /ready で利用できます。ローカル専用のデモトークンは次のとおりです:

• demo-reader — catalog:read

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

MCP Inspector を npx -y @modelcontextprotocol/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