mcp-trial

我通过学习构建一个 GitHub API 服务器来掌握 Model Context Protocol。 使用 Python SDK v2，通过 stdio 运行，并接入 Claude Code。

功能

两个工具，一个用于获取仓库摘要，另一个用于获取最近的提交消息。还有一个 resource 用于提供仓库的原始 README，以及一个用于评估仓库是否适合作为作品集展示的 prompt 模板。

Related MCP server: MCP GitHub Reader

运行方式

uv sync
uv run mcp dev server.py          # opens the inspector
uv run python test_server.py      # calls the server directly, no host needed

要将其注册到 Claude Code：

claude mcp add gh-lab -- uv run --directory /path/to/mcp-trial mcp run server.py

我学到的东西

你的类型提示就是实际的 API 契约，因为 SDK 会直接从函数签名构建工具的 JSON schema。写 limit: int = 5 也会让该参数变为可选，这样模型就可以跳过它。

文档字符串（Docstrings）的重要性超出了我的预期，因为它们会被作为工具描述发送给模型，并决定模型会选择哪个工具。我问 Claude Code 某个仓库是否在积极维护，它同时调用了两个工具并得出了结论，这之所以能发生，正是因为描述让这两个工具看起来可以组合使用。

工具返回的所有内容都会变成模型上下文中的文本，因此每个字段都会消耗 token。GitHub 会返回大约一百个字段，而我只返回五个。

抛出错误比返回错误更好，因为抛出会设置一个宿主检查的标志，并且消息会以模型可操作的形式到达模型。

异步并不会让任何东西变快。无论哪种方式，单次调用所需的时间都一样。await 的作用是挂起函数并释放事件循环，这样在等待期间其他调用就可以运行。

备注

mcp-reference.md 包含了我构建这个项目时的工作笔记。