mcp-demo

最小限のPython MCPサーバーです。各コミットで1つの概念を学べるように段階的に構築されています。 最終状態：Claude CodeがローカルのOllamaモデル（gemma3:4b / 3:12b）をツールとして呼び出し、重要度の低いタスクをAPIからホームラボへオフロードします。

MCPとは何か？

Model Context Protocol (MCP) は、標準化されたJSON-RPC 2.0プロトコルです。これにより、LLMクライアント（Claude Code、Claude Desktop、Cursor）は、MCPサーバーと呼ばれる別のプロセスからツールを発見・呼び出し、リソースを取得し、プロンプトテンプレートを読み込むことができます。MCPとLLMツールの関係は、LSPとIDEの言語サポートの関係に似ています。つまり、1つのプロトコルで多くの相互運用可能な実装が可能になります。

構成要素

    ┌───────────────────┐  stdio / HTTP   ┌──────────────────┐
    │  MCP Client       │ ◄──JSON-RPC──► │  MCP Server      │
    │  (Claude Code)    │                │  (this repo)     │
    └───────────────────┘                └──────────────────┘
            │                                     │
            │ spawns as child                     │ hits
            │ process (stdio)                     │ localhost:11434
            ▼                                     ▼
     your shell env                        Ollama / gemma3

• クライアント — LLMアプリに組み込まれています

• サーバー — MCPを話すあらゆるプロセス

• トランスポート — stdio（クライアントがサーバーを子プロセスとして起動し、JSON-RPCをパイプする）または streamable-http（サーバーがWebサービスとして動作する）。このリポジトリではstdioを使用します。

MCPサーバーが公開する3つのプリミティブ

フェーズの進行

各フェーズは1つのコミットに対応しています。git logで進化の過程を確認できます。

1. ✅ scaffold — pyproject, README, .gitignoreの作成。

2. ✅ hello-world server — 1つの echo ツールとスモークテスト用クライアント。クライアントの起動 → ハンドシェイク → ツールの発見 → ツールの呼び出しという完全なライフサイクルを証明します。

3. ✅ ollama_ask tool — localhost:11434/api/generate にPOSTし、Gemmaの応答を返す非同期ツール。

4. ✅ polish — ollama_ask に system パラメータを追加し、ollama://models（プル済みのモデル一覧）でリソースを公開します。

インストールと実行

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
# Phase 2+ only: run the server by hand to smoke-test
python -m mcp_demo.server

サーバーは標準入力(stdin)からJSON-RPCを読み取り、標準出力(stdout)に書き込みます。ターミナルで直接実行しても、入力待ちの状態で停止します。これは正常な動作です。実際にデータを供給するのはクライアント（Claude Code）です。

Claude Codeへの登録

~/.claude/settings.json に以下を追加します：

{
  "mcpServers": {
    "mcp-demo": {
      "command": "/home/booty/mcp-demo/.venv/bin/python",
      "args": ["-m", "mcp_demo.server"]
    }
  }
}

Claude Codeを再起動してください。ツールは mcp__mcp-demo__<tool_name> として表示されます。

参考文献

• 仕様: https://modelcontextprotocol.io/specification

• Python SDK: https://github.com/modelcontextprotocol/python-sdk

• Inspector (あらゆるMCPサーバーを調査するためのデバッグUI): npx @modelcontextprotocol/inspector