Python MCP Server Project

MCP サーバープロジェクト

AI エージェントによるツール実行向けの HTTP エンドポイントを提供する、安全な Model Context Protocol（MCP）サーバーです。Python 3.12 以降、Starlette、FastMCP で構築されています。

クイックスタート

# Clone and setup
git clone https://github.com/sdirishguy/mcp_server_project.git
cd mcp_server_project
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Run server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Test
curl http://localhost:8000/health

Docker

docker-compose up -d
curl http://localhost:8000/health

設定

必須の環境変数：

JWT_SECRET="your-secret-key-32-chars-minimum"    # Required for production
ADMIN_USERNAME="admin"                            # Default admin user
ADMIN_PASSWORD="secure-password"                  # Change from default

任意の設定：

SERVER_PORT=8000
MCP_BASE_WORKING_DIR="./shared_host_folder"
ENVIRONMENT="development"                         # development|staging|production
ALLOW_ARBITRARY_SHELL_COMMANDS="false"           # Security: disabled by default
CORS_ORIGINS="http://localhost:3000,https://yourdomain.com"

# API Keys for LLM tools
OPENAI_API_KEY="sk-..."
GEMINI_API_KEY="..."

認証

トークンを取得します：

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

トークンを使用します：

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/protected

利用可能なツール

ツール	説明
file_system_create_directory	ディレクトリを作成します（サンドボックス化）
file_system_write_file	テキストファイルを書き込みます
file_system_read_file	テキストファイルを読み込みます
file_system_list_directory	ディレクトリの内容を一覧表示します
execute_shell_command	シェルコマンドを実行します（フィルタリングあり）
llm_generate_code_openai	OpenAI API を使用してコードを生成します
llm_generate_code_gemini	Gemini API を使用してコードを生成します

API エンドポイント

• GET /health - ヘルスチェック
• GET /metrics - Prometheus メトリクス
• POST /api/auth/login - 認証
• POST /mcp/mcp.json/ - MCP JSON-RPC（認証が必要）
• POST /api/adapters/{type} - データアダプターを作成
• GET /docs - 対話型 API ドキュメント

セキュリティ機能

• 設定可能なプロバイダーによる JWT ベースの認証
• ファイル操作におけるパストラバーサルの防止
• シェルコマンドのフィルタリングとサンドボックス化
• 認証エンドポイントのレート制限
• セキュリティヘッダー（HSTS、CSP など）
• CORS の設定
• すべての操作に対する監査ログ記録

開発

テストを実行します：

pytest -q  # 53 passing, 21 skipped (FastMCP lifespan issue)

テスト

テストを実行します：pytest -q（53 件が成功、FastMCP のライフスパン統合により 21 件をスキップ）

スキップされたテストには適切な ASGI ライフスパン管理が必要ですが、TestClient はデフォルトではこれを提供しません。本番サーバーは正常に動作します。

リンティング：

pre-commit install
pre-commit run --all-files

本番環境へのデプロイ

1. 強力な JWT_SECRET を設定します（32 文字以上）
2. デフォルトの ADMIN_PASSWORD を変更します
3. ENVIRONMENT=production を設定します
4. 適切な CORS_ORIGINS を設定します
5. ロードバランサーで HTTPS を終端します
6. /health と /metrics エンドポイントを監視します

詳細なチェックリストについては、PRODUCTION_READINESS_REPORT.md を参照してください。

アーキテクチャ

• FastMCP：Model Context Protocol によるツール実行
• Starlette：ミドルウェアを備えた非同期 Web フレームワーク
• Pydantic：設定管理と検証
• Prometheus：メトリクス収集
• JWT：ステートレス認証
• 監査ログ記録：構造化イベントのログ記録

ライセンス

MIT