Skip to main content
Glama

mcp-trial

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

功能

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

Related MCP server: GitHub MCP Server

运行方式

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 包含了我构建这个项目时的工作笔记。

Available Tools

2 tools
get_repoA

Get summary info for a GitHub repository: description, stars, language, last push.

Inputs: repo (required), owner (required).

recent_commitsB

List the most recent commit messages on a repository's default branch.

Inputs: repo (required), owner (required), limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 2 tools

    Disambiguation5/5

    get_repo and recent_commits are clearly distinct: one fetches repository metadata, the other lists recent commit messages. There is no ambiguity between them.

    Naming Consistency3/5

    Both names use snake_case but follow different patterns: get_repo uses a verb_noun construction while recent_commits is an adjective_noun phrase. The inconsistency is minor but noticeable.

    Tool Count3/5

    With only 2 tools, the server feels thin for a GitHub-related purpose. It is slightly under the typical well-scoped range, though acceptable for a narrow read-only trial.

    Completeness2/5

    The tools only cover repository metadata and recent commits. Obvious gaps like branches, issues, pull requests, and other common repository operations are missing, which would significantly hinder agents needing broader repo access.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables analyzing and querying GitHub repositories through the GitHub Chat API, allowing users to index repositories and ask questions about their code, architecture and tech stack.
      2
      36 PyPI
      90
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides tools for interacting with the GitHub API, enabling AI assistants to query repositories, pull requests, issues, commits, users, and more.
      497 npm
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server that exposes GitHub user profiles, repository info, and search via tools for AI assistants like Claude.
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that enables AI assistants to look up and analyze GitHub repositories, including stars, forks, description, open issues, and README content.
      2
      ISC