MCP Python Starter

MCP Python Starter

FastMCP を使用した、機能が充実した Python 製 Model Context Protocol（MCP）サーバーのテンプレートです。このスターターでは、主要な MCP 機能をすべて、読みやすく Python らしいコードで紹介します。

📚 ドキュメント

• Model Context Protocol
• Python SDK
• FastMCP ガイド

✨ 機能

カテゴリー	機能	説明
ツール	hello	アノテーション付きの基本的なツール
	get_weather	構造化データを返すツール
	ask_llm	LLM サンプリングを実行するツール
	long_task	5秒間、進捗を更新するツール
	load_bonus_tool	新しいツールを動的に読み込む
リソース	info://about	静的な情報リソース
	file://example.md	ファイルベースの Markdown リソース
テンプレート	greeting://{name}	名前に合わせたあいさつ
	data://items/{id}	ID によるデータ検索
プロンプト	greet	さまざまなスタイルのあいさつ
	code_review	注目する領域を指定したコードレビュー

🚀 クイックスタート

前提条件

• Python 3.11+
• uv（推奨）または pip

インストール

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-python-starter.git
cd mcp-python-starter

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

サーバーの実行

stdio トランスポート（ローカル開発向け）：

uv run mcp-python-starter --stdio

HTTP トランスポート（リモート／ウェブへのデプロイ向け）：

uv run mcp-python-starter --http --port 3000

🔧 VS Code との統合

このプロジェクトには、スムーズな開発のための VS Code 設定が含まれています。

1. VS Code でプロジェクトを開きます
2. MCP の設定は .vscode/mcp.json にあります
3. VS Code の MCP ツールを使ってサーバーをテストします

DevContainers の使用

1. Dev Containers 拡張機能をインストールします
2. コマンドパレットを開き、「Dev Containers: Reopen in Container」を選択します
3. すべて設定済みで、すぐに使用できます。

📁 プロジェクト構成

.
├── mcp_starter/
│   ├── __init__.py
│   ├── tools.py       # Tool definitions (hello, get_weather, ask_llm, etc.)
│   ├── resources.py   # Resource and template definitions
│   ├── prompts.py     # Prompt definitions
│   └── server.py      # Server orchestration (imports and wires modules)
├── .vscode/
│   ├── mcp.json       # MCP server configuration
│   ├── settings.json  # Python settings
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── pyproject.toml     # Project configuration (uv/pip, Ruff config)
└── .python-version

🛠️ 開発

# Run the server (Python reloads automatically on changes)
uv run mcp-python-starter --stdio

# Use MCP Inspector for debugging
uv run mcp dev mcp_starter/server.py

# Format code
uv run ruff format .

# Lint
uv run ruff check .

# Lint with auto-fix
uv run ruff check --fix .

# Type check
uv run pyright

ライブリロード

uv run で実行すると、Python スクリプトは自動的に再読み込みされます。デバッグ機能を強化するには、 MCP Inspector UI を備えた mcp dev を使用してください。

🔍 MCP Inspector

MCP Inspector は、MCP サーバーのテストとデバッグに欠かせない開発ツールです。

Inspector の実行

npx @modelcontextprotocol/inspector -- uv run mcp-python-starter

Inspector でできること

• Tools タブ：登録済みのすべてのツールとパラメーターを一覧表示し、実行できます
• Resources タブ：リソースとテンプレートを参照して読み取れます
• Prompts タブ：プロンプトテンプレートを表示してテストできます
• Logs タブ：クライアントとサーバー間の JSON-RPC メッセージを確認できます
• スキーマ検証：ツールの入出力スキーマを検証できます

デバッグのヒント

1. IDE／クライアントに接続する前に Inspector を起動します
2. 「Logs」タブで、リクエスト／レスポンスのペイロードを正確に確認します
3. ツールのアノテーション（ToolAnnotations）が正しく公開されていることをテストします
4. long_task の進捗通知が表示されることを確認します
5. サンプリングツールで Context の注入が機能することを確認します

📖 機能の例

アノテーション付きツール（FastMCP デコレーター）

@mcp.tool(
    title="Say Hello",
    description="A friendly greeting tool",
    annotations={"readOnlyHint": True},
)
def hello(name: str) -> str:
    """Say hello to someone.
    
    Args:
        name: The name to greet
    """
    return f"Hello, {name}!"

リソーステンプレート

@mcp.resource("greeting://{name}")
def greeting_template(name: str) -> str:
    """Generate a personalized greeting."""
    return f"Hello, {name}!"

進捗を更新するツール

@mcp.tool(title="Long Task")
async def long_task(
    task_name: str,
    ctx: Context[ServerSession, None],
) -> str:
    for i in range(5):
        await ctx.report_progress(
            progress=i / 5,
            total=1.0,
            message=f"Step {i + 1}/5",
        )
        await asyncio.sleep(1.0)
    return "Done!"

サンプリングを行うツール

@mcp.tool(title="Ask LLM")
async def ask_llm(
    prompt: str,
    ctx: Context[ServerSession, None],
) -> str:
    result = await ctx.session.create_message(
        messages=[{"role": "user", "content": {"type": "text", "text": prompt}}],
        max_tokens=100,
    )
    return result.content.text

🔐 環境変数

.env.example を .env にコピーして設定します。

cp .env.example .env

🤝 貢献

貢献を歓迎します！変更を加える際は、ほかの言語のスターターと機能が同等に保たれるようにしてください。

📄 ライセンス

MIT License - 詳細はLICENSEをご覧ください。