mcp-demo

一个极简的 Python MCP 服务器，分阶段构建，以便每个提交都能教授一个概念。 最终状态：Claude Code 可以将本地 Ollama 模型（gemma3:4b / 3:12b）作为工具调用， 将低风险工作从 API 转移到家庭实验室运行。

到底什么是 MCP？

模型上下文协议 (Model Context Protocol) 是一种标准化的 JSON-RPC 2.0 协议，它允许 LLM 客户端（Claude Code、Claude Desktop、Cursor）发现并调用工具、 获取资源，以及从称为 MCP 服务器 的独立进程中加载提示词模板。MCP 之于 LLM 工具，正如 LSP 之于 IDE 语言支持： 一种协议，多种可互操作的实现。

核心组件

    ┌───────────────────┐  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

• 客户端 (Client) — 嵌入在 LLM 应用中

• 服务器 (Server) — 任何支持 MCP 的进程

• 传输 (Transport) — stdio（客户端将服务器作为子进程启动，通过管道传输 JSON-RPC）或 streamable-http（服务器作为 Web 服务）。本仓库使用 stdio。

MCP 服务器暴露的三个原语

阶段演进

每个阶段对应一个提交 — git log 展示了演进过程。

1. ✅ 脚手架 (scaffold) — pyproject, README, .gitignore。

2. ✅ hello-world 服务器 — 一个 echo 工具 + 冒烟测试客户端。 验证了完整的生命周期：客户端启动 → 握手 → 工具发现 → 工具调用。

3. ✅ ollama_ask 工具 — 异步工具，向 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