MCP Server template for better AI Coding

AI コーディングを改善する MCP サーバーテンプレート

MCP 公式チュートリアルに触発されています

概要

このテンプレートは、Python で Model Context Protocol（MCP）サーバーを構築するための、合理化された基盤を提供します。MCP ツールの AI 支援開発をより簡単かつ効率的にすることを目的としています。

特長

• すぐに使える MCP サーバーの実装
• 設定可能なトランスポートモード（stdio、SSE）
• 天気サービスとの連携例（NWS API）
• 整理され、十分に文書化されたコード構成
• 最小限の依存関係
• AI ツールの理解を深めるための組み込み MCP 仕様とドキュメント

Cursor Rules との連携

このプロジェクトでは、Awesome Cursor Rulesのパターンを取り入れた Cursor Rules を使用し、AI コーディング支援を強化しています。

• クリーンコードのガイドライン：組み込みのクリーンコードルールにより、一貫性と品質を維持できます
• AI の理解を強化：ルールがコンテキストを提供し、AI アシスタントによるより良いコードの生成を支援します
• 標準化されたパターン：MCP サーバー実装で確立されたベストプラクティスに従います

Cursor Rules は、AI コーディングアシスタントと人間の開発者の両方が、高いコード品質基準を維持し、ベストプラクティスに従うのに役立ちます。

MCP ドキュメントの統合

このテンプレートには、包括的な MCP ドキュメントがプロジェクト内に直接含まれています。

• MCP 仕様の全文（protocals/mcp.md）：AI モデルが外部のツールやリソースとどのように連携できるかを定めた、Model Context Protocol の完全な仕様です。外部の資料を参照しなくても、AI アシスタントが MCP の概念や実装の詳細を理解できるようにします。

• Python SDK ガイド（protocals/sdk.md）：MCP Python SDK の詳細なドキュメントです。AI ツールが正確なコード提案を行い、ライブラリの機能を理解しやすくなります。

• 実装例（protocals/example_weather.py）：実際の MCP サーバーのパターンとベストプラクティスを示す、実用的な天気サービスの実装です。

これらのリソースをプロジェクトに組み込むことで、AI コーディングアシスタントが MCP の概念をより深く理解し、開発中により正確でコンテキストに即した提案を行えるようになります。

要件

• Python 3.12+
• 依存関係：
  • mcp>=1.4.1
  • httpx>=0.28.1
  • starlette>=0.46.1
  • uvicorn>=0.34.0

はじめに

インストール

1. このリポジトリをクローンします。

   git clone https://github.com/yourusername/mcp-server-python-template.git
   cd mcp-server-python-template
   

2. 仮想環境を作成し、依存関係をインストールします。

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e .
   

サンプルサーバーの実行

このテンプレートには、MCP ツールの構築方法を示す天気サービスのサンプルが含まれています。

# Run with stdio transport (for CLI tools)
python server.py --transport stdio

# Run with SSE transport (for web applications)
python server.py --transport sse --host 0.0.0.0 --port 8080

独自の MCP ツールを作成する

独自の MCP ツールを作成するには、次の手順に従います。

1. mcp から必要なコンポーネントをインポートします。

   from mcp.server.fastmcp import FastMCP
   

2. 名前空間を指定して MCP サーバーを初期化します。

   mcp = FastMCP("your-namespace")
   

3. @mcp.tool() デコレーターを使ってツールを定義します。

   @mcp.tool()
   async def your_tool_function(param1: str, param2: int) -> str:
       """
       Your tool description.
       
       Args:
           param1: Description of param1
           param2: Description of param2
           
       Returns:
           The result of your tool
       """
       # Your implementation here
       return result
   

4. 適切なトランスポートを使ってサーバーを実行します。

   mcp.run(transport='stdio')  # or set up SSE as shown in server.py
   

プロジェクト構成

• server.py：サンプルの天気ツールを含む、MCP サーバーのメイン実装
• main.py：カスタムコード用のシンプルなエントリーポイント
• protocals/：ドキュメントとプロトコルのサンプル
  • mcp.md：MCP 仕様の全文（約7000行）
  • sdk.md：MCP Python SDK のドキュメント
  • example_weather.py：天気サービスの実装例
• pyproject.toml：プロジェクトの依存関係とメタデータ

MCP の理解

Model Context Protocol（MCP）は、AI モデルが外部のツールやリソースとやり取りするための標準化された方法です。主な概念は次のとおりです。

• ツール：モデルがアクションの実行や情報の取得に使用できる関数
• リソース：モデルが参照できる外部データソース
• トランスポート：クライアントと MCP サーバー間の通信チャネル（stdio、SSE）
• 名前空間：関連するツールを論理的にまとめたもの

このテンプレートは、MCP をより手軽に利用できるように特別に設計されています。ドキュメントが組み込まれているため、AI ツールが MCP の実装に適したコードをより適切に理解し、生成できるようになります。

学習リソース

• MCP 公式ドキュメント
• プロトコルのドキュメント
• SDK ガイド

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。