MCP Server Cookie Cutter Template

MCP サーバー Cookie Cutter テンプレート

新しい MCP（Model Context Protocol）サーバーを作成するための Cookie Cutter テンプレートです。このテンプレートでは、複数のトランスポート（stdio と streamable HTTP）に対応し、高度なロギング、自動デコレーター、Web ベースの管理 UI を備えた、すぐに使用できる MCP サーバーを生成できます。

特長

• 公式 MCP SDK 1.28+：公式の mcp Python SDK をベースに構築されています（<2.0 に固定）
• 複数トランスポート対応：stdio と streamable HTTP を単一の実装で利用でき、サーバーレス環境向けのステートレスモード／JSON レスポンスモードもオプションで利用できます
• 3 種類すべての MCP プリミティブ：ツール、リソース（静的およびテンプレート）、プロンプト
• 構造化出力：型付きの Pydantic ツール戻り値と、自動生成される出力スキーマ
• ツールメタデータ：人が読みやすいタイトルと動作アノテーション（読み取り専用、破壊的、冪等、オープンワールドのヒント）
• 自動デコレーター：例外処理、ロギング、型変換、並列化
• 統合ロギングシステム：相関 ID と拡張可能な出力先を備えた SQLite ベースのロギング
• Web 管理 UI：設定、ログ、ドキュメントに対応した Streamlit ベースのインターフェース
• ツールの例：ベストプラクティスを取り入れたすぐに使えるツールの例（エリシテーション、進捗、通知のデモを含む）
• MCP Inspector との完全な互換性：簡単にテストおよびデバッグできます
• 適切な絶対インポート：一貫したクリーンなパッケージ構成
• DevFlow との統合：JIRA ワークフローコマンドを内蔵（plan-work、implement、security-review、complete）
• 包括的なドキュメント：README、開発ガイド、セットアッププロンプトのテンプレート

前提条件

1. Python 3.11 以降

   python --version  # Should be 3.11 or higher
   

2. uv（高速な Python パッケージインストーラー）

   # Install uv if you don't have it
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Cookie Cutter

   uv pip install cookiecutter
   

新しい MCP サーバーの作成

GitHub から直接、またはこのテンプレートのローカルコピーから、新しい MCP サーバーを作成できます。

オプション 1：GitHub から直接作成

cookiecutter gh:codingthefuturewithai/mcp-cookie-cutter

オプション 2：ローカルコピーから作成

1. このテンプレートをクローンします。

   git clone https://github.com/codingthefuturewithai/mcp-cookie-cutter
   

2. ローカルテンプレートを使用してプロジェクトを作成します。

   cookiecutter path/to/mcp-cookie-cutter
   

テンプレートの設定

次の情報を入力します。

• project_name：人が読みやすい名前（例：「My MCP Server」）
• __project_slug：Python パッケージ名（project_name から自動生成されます。例：「my_mcp_server」）
• description：プロジェクトの簡単な説明
• author_name：作成者名
• email：メールアドレス
• server_port：Streamable HTTP トランスポート用のポート（デフォルト：3001）

生成されるプロジェクト構成

my_mcp_server/              # Your project directory
├── .claude/                # Claude Code integration
│   ├── agents/            # Security scanner agent
│   └── commands/          # DevFlow workflow commands
│       └── devflow/       # JIRA-integrated development workflow
├── my_mcp_server/          # Python package directory
│   ├── __init__.py
│   ├── __main__.py
│   ├── client/             # Client implementations
│   │   ├── __init__.py
│   │   └── app.py         # Test client for development
│   ├── server/            # Server implementation
│   │   ├── __init__.py
│   │   └── app.py        # Multi-transport MCP server (stdio, streamable HTTP)
│   ├── tools/             # Tool implementations
│   │   ├── __init__.py
│   │   └── example_tools.py  # Example tools with decorators
│   ├── decorators/        # Automatic tool decorators
│   │   ├── exception_handler.py
│   │   ├── tool_logger.py
│   │   ├── type_converter.py
│   │   └── parallelize.py
│   ├── log_system/        # Unified logging system
│   │   ├── correlation.py     # Correlation ID tracking
│   │   ├── unified_logger.py  # Main logging interface
│   │   └── destinations/      # Log destinations (SQLite, etc.)
│   ├── ui/                # Streamlit management UI
│   │   ├── app.py
│   │   ├── lib/          # UI components and utilities
│   │   └── pages/        # UI pages (Home, Config, Logs, Docs)
│   ├── config.py          # Server configuration
│   └── logging_config.py  # Logging setup
├── tests/                 # Test suite
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── pyproject.toml         # Project configuration and dependencies
├── README.md             # Project documentation template
├── DEVELOPMENT.md        # Development guide
├── DEVELOPER_GUIDE.md    # Developer reference
└── SETUP_PROMPT.md       # AI-assisted setup guide

次のステップ

プロジェクトを生成したら、次の手順に進みます。

1. ドキュメントのテンプレートを確認する

   • プロジェクトに合わせて README.md をカスタマイズします
   • 開発ワークフローについて DEVELOPMENT.md を確認します
   • アーキテクチャの詳細について DEVELOPER_GUIDE.md を確認します
   • AI を活用したセットアップには SETUP_PROMPT.md を使用します

2. 開発環境をセットアップする

   • 依存関係をインストールします：uv pip install -e .
   • テストを実行します：pytest
   • サーバーを起動します：python -m your_project_name --transport stdio

3. トランスポートを確認する

   • STDIO：python -m your_project_name --transport stdio
   • Streamable HTTP：python -m your_project_name --transport streamable-http --port 3001

4. MCP Inspector でテストする

   • インストールします：npm install -g @modelcontextprotocol/inspector
   • 実行します：mcp dev your_project_name/server/app.py

5. 管理 UI にアクセスする

   • UI を起動します：streamlit run your_project_name/ui/app.py
   • ログの確認、サーバーの設定、ドキュメントの閲覧ができます

6. 独自のツールを追加する

   • tools/example_tools.py に関数を追加します
   • デコレーターは自動的に適用されます
   • example_tools または parallel_example_tools のリストに登録します

7. DevFlow ワークフローを使用する（任意）

   • JIRA に接続します
   • /devflow:plan-work ISSUE-KEY を使用して計画します
   • /devflow:implement ISSUE-KEY を使用して実装します
   • /devflow:security-review ISSUE-KEY を使用してスキャンします
   • /devflow:complete ISSUE-KEY を使用して PR を作成します

ライセンス

このテンプレートは MIT ライセンスのもとで公開されています。詳細については LICENSE ファイルを参照してください。