MCPサーバーボイラープレート

カスタムMCPサーバーを構築するための再利用可能なベースラインとして設計された、最小限かつ十分に文書化されたMCP（Model Context Protocol）サーバーの実装です。

MCPとは？

Model Context Protocol (MCP) は、AIアシスタントが外部サーバーと対話できるようにする標準化されたプロトコルです。MCPサーバーは以下を提供できます：

• ツール: AIがアクションを実行するために呼び出せる関数

• リソース: AIが読み取れる静的または動的なデータ

• プロンプト: 一貫したAI対話のための再利用可能なプロンプトテンプレート

Related MCP server: MCP Mingdao

特徴

このボイラープレートは以下を提供します：

• 最小限の構造: 簡単に拡張できるクリーンなベースライン

• 詳細なドキュメント: インラインコメントと個別のドキュメントファイル

• アーキテクチャ図: コンポーネントの相互作用を示すMermaid図

• スケーリングガイド: サーバーを成長させるためのベストプラクティス

• 型ヒント: より良いIDEサポートのための完全な型アノテーション

• Async/await: 並行操作のためのノンブロッキングI/O

再利用可能なプロンプトテンプレート

プロンプトは、プレースホルダーを使用して構造化されたプロンプトを定義できる再利用可能なテンプレートです。これらにより以下が可能になります：

• 一貫性: さまざまなAI対話間での標準化されたプロンプト形式

• パラメータ化: 引数を通じた動的なコンテンツ挿入

• 再利用性: 一度定義すれば、異なる入力で複数回使用可能

• 型安全性: 検証付きの定義済み引数スキーマ

プロンプトテンプレートは以下で構成されます：

• 名前: プロンプトの一意の識別子

• 説明: プロンプトの機能

• 引数: プロンプト使用時に埋め込むことができるオプションのパラメータ

使用例：

• 設定可能な重大度レベルを持つコードレビューテンプレート

• カスタマイズ可能なトーンを持つドキュメント生成

• 変数フォーカス領域を持つ分析プロンプト

• 異なる出力形式を持つレポート生成

プロジェクト構造

windsurf-project-3/
├── mcp_server.py          # Main server implementation with extensive comments
├── pyproject.toml         # Project configuration for uv
├── ARCHITECTURE.md        # Architecture documentation with Mermaid diagrams
├── SCALING_GUIDE.md       # Scaling patterns and best practices
├── README.md              # This file
├── tools/                 # Placeholder for tool modules (create as needed)
├── resources/             # Placeholder for resource modules (create as needed)
├── prompts/               # Placeholder for prompt modules (create as needed)
└── utils/                 # Placeholder for utility modules (create as needed)

インストール

このプロジェクトでは、高速なPythonパッケージ管理のためにuvを使用しています。

1. Python 3.10以上をインストール

2. uvをインストール（まだインストールされていない場合）：

curl -LsSf https://astral.sh/uv/install.sh | sh

3. 依存関係をインストール：

uv sync

クイックスタート

1. 最初のツールを追加する

mcp_server.pyを編集し、list_tools()関数にツールを追加します：

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="echo",
            description="Echo back the input text",
            inputSchema={
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Text to echo"}
                },
                "required": ["text"]
            }
        )
    ]

2. ツールハンドラーを実装する

call_tool()関数にツールのロジックを追加します：

@app.call_tool()
async def call_tool(name: str, arguments: Any) -> str:
    if name == "echo":
        text = arguments.get("text", "")
        return f"Echo: {text}"
    raise ValueError(f"Unknown tool: {name}")

3. プロンプトを追加する（オプション）

list_prompts()関数にプロンプトを追加します：

@app.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [
        Prompt(
            name="example_prompt",
            description="An example prompt template",
            arguments=[
                PromptArgument(
                    name="topic",
                    description="The topic to write about",
                    required=True
                )
            ]
        )
    ]

次に、get_prompt()でハンドラーを実装します：

@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str] | None) -> str:
    if name == "example_prompt":
        topic = arguments.get("topic") if arguments else None
        if not topic:
            raise ValueError("Argument 'topic' is required")
        return f"Write a detailed explanation about {topic}."
    raise ValueError(f"Unknown prompt: {name}")

3. サーバーを実行する

uv run python mcp_server.py

4. MCPクライアントを設定する

MCPクライアントの設定に以下を追加します：

{
  "mcpServers": {
    "your-server-name": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp_server.py"]
    }
  }
}

ドキュメント

• ARCHITECTURE.md: 以下を示すMermaid図を含む詳細なアーキテクチャドキュメント：

  • Pythonモジュールとその目的

  • コンポーネントの相互作用

  • リクエストフロー（ツール呼び出し、リソース読み取り）

  • 使用されている設計パターン

• SCALING_GUIDE.md: サーバーをスケーリングするためのベストプラクティス：

  • モジュール化パターン

  • 状態管理戦略

  • エラー処理パターン

  • ロギングと監視

  • 設定管理

  • テスト戦略

  • パフォーマンス最適化

  • セキュリティ上の考慮事項

コード構造

メインのサーバーファイル（mcp_server.py）は以下のセクションに整理されています：

1. サーバーの初期化: MCPサーバーインスタンスの作成

2. ツールの登録: 利用可能なツールの定義

3. ツールハンドラー: ツール実行ロジックの実装

4. リソースの登録: 利用可能なリソースの定義

5. リソースハンドラー: リソース読み取りロジックの実装

6. エントリーポイント: stdio通信によるサーバーの起動

各セクションには、各コンポーネントの目的と使用法を説明する詳細なインラインコメントが含まれています。

拡張ポイント

ツールの追加

1. list_tools()でスキーマとともにツールを定義する

2. call_tool()でハンドラーを実装する

3. 大規模なプロジェクトの場合は、tools/ディレクトリの別モジュールに移動する

プロンプトの追加

1. list_prompts()で引数とともにプロンプトを定義する

2. get_prompt()でハンドラーを実装する

3. 大規模なプロジェクトの場合は、prompts/ディレクトリの別モジュールに移動する

リソースの追加

1. list_resources()でメタデータとともにリソースを定義する

2. read_resource()でハンドラーを実装する

3. 大規模なプロジェクトの場合は、resources/ディレクトリの別モジュールに移動する

ユーティリティの追加

共有コードをutils/ディレクトリに抽出します：

• 検証関数

• ロギングヘルパー

• 設定管理

• エラー処理ユーティリティ

ベースラインとしての使用

このボイラープレートは、コピーして新しいプロジェクト用に修正するように設計されています：

1. プロジェクトディレクトリ全体をコピーする

2. pyproject.tomlでプロジェクト名を変更する

3. mcp_server.pyでサーバー名を更新する

4. ツール、リソース、プロンプトを追加する

5. 必要に応じてドキュメントをカスタマイズする

使用されているPythonモジュール

• mcp.server.Server: メインのMCPサーバークラス

• mcp.types.Tool: ツール型定義

• mcp.types.Resource: リソース型定義

• mcp.types.Prompt: プロンプト型定義

• mcp.types.PromptArgument: プロンプト引数型定義

• mcp.server.stdio: Stdio通信ストリーム

• asyncio: 並行操作のためのAsync/await

• typing: コードの明確化のための型ヒント

各モの詳細な説明についてはARCHITECTURE.mdを参照してください。

開発

テストの実行

# Run with pytest (add tests first)
uv run pytest

コードスタイル

このプロジェクトはPythonの型ヒントを使用し、PEP 8規則に従っています。以下を検討してください：

• リンティングのためのruff

• 型チェックのためのmypy

依存関係の追加

uv add <package-name>

トラブルシューティング

• インポートエラー: uv syncを実行して依存関係をインストールしてください

• サーバーが応答しない: MCPクライアントの設定を確認してください

• 型エラー: Python 3.10以上がインストールされていることを確認してください

• uvコマンドが見つからない: https://github.com/astral-sh/uv からuvをインストールしてください

リソース

• MCP仕様

• MCP Python SDK

• uvドキュメント

ライセンス

このボイラープレートは、教育および開発目的のために現状のまま提供されています。プロジェクトで自由に使用および修正してください。