Python MCP Server Template

Name: Python MCP Server Template
Author: djaboxx

ローカル

github.com/djaboxx開発ツール079 週間前に更新

リポジトリ

Python MCP Server Template について

VS Code 向け MCP サーバーを構築する Python テンプレートです。設定、ライフサイクル、ツール、エラー処理の実装パターンを求める開発者向けです。

主な機能

01Pydantic による設定検証
02非同期サーバーのライフサイクルと終了処理
03デコレーターによるツール登録
04構造化エラーとログ記録

活用シーン

01サービス用 Python MCP サーバーの骨組み作成
02環境変数によるシークレットと設定の追加
03型ヒントと統一したエラー応答を備えるツールの実装

MCP 対応

MCP クライアント（VS Code を含む）にツールを公開する Python MCP サーバーのひな型を提供します。特定サービス向けのツール実装は含みません。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

インストール方法は未掲載です

このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。

リポジトリ

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Python MCP サーバーテンプレート

Python を使用して VS Code の Model Context Protocol（MCP）サーバーを作成するためのテンプレートリポジトリです。このテンプレートは、本番環境の MCP サーバーで確立されたパターンとベストプラクティスに準拠しています。

目的

このテンプレートは、次の機能を備えた MCP サーバーを構築するための基盤を提供します。

VS Code の AI 機能と連携します
本番環境の MCP サーバーで確立されたパターンに準拠します
構成、ログ記録、エラーケースを一貫して処理します
非同期 Python と MCP ツールのベストプラクティスを活用します

アーキテクチャ

このテンプレートは、本番環境の MCP サーバーで見られる次の主要なアーキテクチャパターンに準拠しています。

サービス構成
- 構成の検証に Pydantic モデルを使用します
- 環境変数に基づく構成を使用します
- サーバーのライフスパン中にサービスクライアントを初期化します
サーバーのライフサイクル
- サーバーのライフスパンに非同期コンテキストマネージャーを使用します
- 起動とシャットダウンを適切に処理します
- finally ブロックでリソースをクリーンアップします
ツールの実装
- デコレーターに基づくツール登録を使用します
- エラー処理とログ記録を一貫して行います
- 構造化された応答形式を使用します
開発パターン
- 全体を通して型ヒントを使用します
- 設定可能なレベルで詳細なログを記録します
- サービス状態の検証チェックを行います

プロジェクト構成

本番環境のパターンに基づく標準的な MCP サーバー構成です。

.
├── src/                     # Python source code
│   ├── server.py           # Main MCP server implementation
│   ├── services/           # Service client implementations
│   │   └── client.py       # Your service client code
│   ├── models.py           # Data models and schemas
│   ├── config.py           # Configuration models
│   └── utils/              # Utility functions
├── docs/                   # Documentation
│   └── mcp-server-guide.md # Server implementation guide
├── tests/                  # Test files
├── requirements.txt        # Python dependencies
└── README.md              # Project documentation

コードの構成

このテンプレートは、本番環境の MCP サーバーで採用されている次の規約に準拠しています。

サーバーのエントリーポイント（src/server.py）：

# Configuration models
class ServiceConfig(BaseModel):
    api_key: str
    # ...

# Server lifespan
@asynccontextmanager
async def server_lifespan(server: FastMCP):
    try:
        # Initialize services
        yield
    finally:
        # Cleanup

# FastMCP instance
mcp = FastMCP(
    name="Your Server",
    instructions="Your server description",
    lifespan=server_lifespan
)

# Tools
@mcp.tool()
async def your_tool(ctx: Context):
    # Tool implementation

サービスクライアント（src/services/）：
- サービス固有のクライアントを実装します
- 認証と再試行を処理します
- 接続状態を管理します
モデル（src/models.py）：
- データ検証用の Pydantic モデルを定義します
- ツールの入力と出力を構成します
- サービス固有の型を定義します

実装ガイド

構成：
- サービスのニーズに合わせて構成モデルを追加します
- シークレットには環境変数を使用します
- 必須フィールドの検証を追加します
サービスクライアント：
- services/ にサービスクライアントを実装します
- 接続と再試行の処理を追加します
- 適切なクリーンアップを実装します

ツール：

@mcp.tool() デコレーターを使用します
型ヒントと docstring を含めます
次のエラー処理パターンに従います。

@mcp.tool()
async def your_tool(ctx: Context) -> Dict[str, Any]:
    try:
        # Implementation
        return {"status": "success", "result": result}
    except Exception as e:
        await ctx.error(f"Error: {e}")
        return {"status": "error", "message": str(e)}

エラー処理：
- 構造化されたエラー応答を使用します
- コンテキストを含めてエラーをログに記録します
- ユーザーにわかりやすいメッセージを返します

はじめに

このテンプレートから新しいリポジトリを作成します。

git clone https://github.com/username/template-mcp-server.git your-server
cd your-server

開発環境をセットアップします。

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

src/server.py のサーバー名と説明を更新します
サービスの構成とクライアントを追加します

VS Code の構成

このサーバーを VS Code の MCP 機能で使用するには、次の構成を VS Code の settings.json に追加します。

"mcp": {
  "inputs": [
    {
      "type": "promptString",
      "id": "service-api-key",
      "description": "Service API Key",
      "password": true
    }
  ],
  "servers": {
    "template-mcp": {
      "type": "stdio",
      "command": "${userHome}/git/template-mcp-server/venv/bin/python",
      "args": [
        "${userHome}/git/template-mcp-server/src/server.py"
      ],
      "env": {
        "SERVICE_API_KEY": "${input:service-api-key}",
        "SERVICE_ENDPOINT": "https://api.example.com",
        "SERVICE_TIMEOUT": "30",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

構成オプション

環境変数：
- SERVICE_API_KEY：サービスの API キー（必須）
- SERVICE_ENDPOINT：サービスのエンドポイント URL（デフォルト：https://api.example.com）
- SERVICE_TIMEOUT：リクエストのタイムアウト（秒）（デフォルト：30）
- LOG_LEVEL：ログレベル（デフォルト：INFO）

テスト

本番環境の MCP サーバーのパターンに従います。

手動テスト：

# Run the server directly
python src/server.py

# Test with different log levels
LOG_LEVEL=DEBUG python src/server.py

統合テスト：

# Start server with test configuration
SERVICE_API_KEY=test-key python src/server.py

開発のヒント：
- VS Code の Python デバッガーを使用して、ツールの実行をステップ実行します
- サービスクライアントにブレークポイントを設定して、統合の問題をデバッグします
- 開発中は DEBUG ログレベルを使用して、詳細な出力を確認します

よくあるパターン

本番環境の MCP サーバーを分析すると、従うべき重要なパターンは次のとおりです。

サービスクライアントの状態：
- サーバーのライフスパンで初期化する
- グローバル変数に保存する
- 使用前に初期化されていることを確認する
- finally ブロックでクリーンアップする
エラー処理：
- コンテキストとともにエラーをログに記録する
- 構造化されたエラーレスポンスを返す
- ユーザーへのフィードバックには ctx.error() を使用する
- ステータスとメッセージの両方を含める
設定：
- Pydantic モデルを使用する
- 適切なデフォルト値を設定する
- 起動時に検証する
- 環境変数による上書きをサポートする
ツールの実装：
- Args セクションを含む明確な docstring
- すべてのパラメーターに型ヒントを付ける
- 構造化されたレスポンス
- 一貫したエラー形式

リソース

VS Code の設定

このサーバーを VS Code の MCP（Model Context Protocol）機能で使用するには、次の設定を VS Code の settings.json に追加します。

"mcp": {
  "inputs": [
    {
      "type": "promptString",
      "id": "service-api-key",
      "description": "Service API Key",
      "password": true
    }
  ],
  "servers": {
    "template-mcp": {
      "type": "stdio",
      "command": "${userHome}/git/template-mcp-server/venv/bin/python",
      "args": [
        "${userHome}/git/template-mcp-server/src/server.py"
      ],
      "env": {
        "SERVICE_API_KEY": "${input:service-api-key}",
        "SERVICE_ENDPOINT": "https://api.example.com",
        "SERVICE_TIMEOUT": "30",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

設定オプション

環境変数：
- SERVICE_API_KEY：サービスの API キー（必須）
- SERVICE_ENDPOINT：サービスのエンドポイント URL（デフォルト：https://api.example.com）
- SERVICE_TIMEOUT：リクエストのタイムアウト（秒）（デフォルト：30）
- LOG_LEVEL：ログレベル（デフォルト：INFO）

前提条件

サーバーを使用する前に、以下を行ってください。

プロジェクトディレクトリに Python 仮想環境を設定します。

python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt

VS Code を設定します。
- stdio 設定を含む .vscode/mcp.json を作成する
- VS Code で Python インタープリターを設定する
- コマンドの実行には統合ターミナルを使用する
- VS Code の Python デバッガーで MCP サーバーをデバッグする
MCP サーバーをテストします。
- VS Code に組み込まれた MCP サーバーのテスト機能を使用する
- ブレークポイントと VS Code のデバッグコンソールでデバッグする
- 出力パネルで stdio 通信を監視する

コントリビューション

リポジトリをフォークする
フィーチャーブランチを作成する
プルリクエストを送信する

ライセンス

[選択したライセンス]

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。