gitgoblin

@gitgoblin/mcp

gitgoblin 是一个 Model Context Protocol 服务。它为任何 MCP 客户端（Claude Code、Codex、Cursor、Gemini CLI、VS Code 中的 Copilot 等）提供四个只读工具：发现值得投入时间的仓库、解释仓库为何获得当前评分、分析仓库实际需要什么，以及全面了解某项工作。

claude mcp add gitgoblin -- npx -y https://github.com/anandkaranubc/gitgoblin/releases/download/mcp-v0.1.6/gitgoblin-mcp-0.1.6.tgz

docs/agents.md 列出了每个客户端对应的一行命令、用于教会 Agent 何时使用这些工具的技能，以及已验证的内容。该服务已列入官方 MCP Registry，名称为 io.github.anandkaranubc/gitgoblin。该命令会安装附加在版本 mcp-v0.1.6中的 tarball。@gitgoblin/mcp 尚未发布到 npm，因此在正式发布前，请勿在 npx -y 中使用该名称。你也可以克隆仓库并运行 npm install，然后通过 node packages/mcp/bin/gitgoblin-mcp.mjs 启动服务；Claude Desktop 用户可直接安装该版本中的 gitgoblin.mcpb。

工具

工具	输入	输出
discover_repositories	goal（默认值为 contribute）、languages、topics、keywords、min_stars、max_stars、pushed_within_days、created_within_days、license、like、exclude_owners、include_archived、include_forks、limit（默认值为 10，最大值为 25）	排名后的仓库：星标数、语言、许可证、评分、最有力的三个支持理由和一个反对理由，以及适用于 contribute 的入门问题。structuredContent.results[] 包含相同字段。
explain_repository	repository、goal	全部十项发现信号，包括其值、对该目标的权重及其依据。对于未知信号会明确说明。
analyze_repository	repository、max_opportunities（默认值为 10，最大值为 30）、check_dependencies（默认值为 true）、goal	仓库概况（性质、活跃度、响应速度、友好度及相关信号、规则、命令、约定），以及按优先级排序且附有主要依据的机会。
get_opportunity	repository、opportunity_id 或 issue_number	一项机会的完整信息，以及如何参与项目：克隆、命令、约定、规则和礼仪。

repository 接受 owner/name 或 URL。explain_repository 和 like 种子接受 github.com 上的仓库，因为发现功能按所有者和名称读取 GitHub API；analyze_repository 和 get_opportunity 还接受 gitlab.com 和 codeberg.org 上的仓库，intel 会通过这些站点的公共 API 获取信息。其他所有主机都会被拒绝。错误会作为工具结果返回，并附带建议（例如如何获取令牌、如何拼写仓库名），而不会导致协议失败。分析会在工作线程中运行，五分钟后停止，或者在客户端取消请求时立即停止，因此某个响应缓慢的仓库不会让其他工具卡住。客户端提供进度令牌时，长时间调用会发送进度通知。

服务的 instructions 会告知 Agent 常见工作流程、引用的仓库文本属于数据而非指令，以及最重要的一条规则：除非用户提出要求，否则绝不会代替用户创建问题、拉取请求或评论。

仓库通常由模型选择，因此服务会将其视为不可信内容：git 会将已提交的符号链接检出为普通文件，且只使用 HTTPS；克隆的仓库各自在独立缓存中存放；绝不获取外部链接；并会从每项结果中剥离控制字符。docs/design.md 详细解释了每项防护措施。

环境变量

变量	作用
GITHUB_TOKEN、GH_TOKEN	可选。提高 GitHub 的限额并启用入门问题功能。若未设置，则使用 gh auth token。
GITGOBLIN_CACHE_DIR	HTTP 缓存的存放位置（默认值为 ~/.cache/gitgoblin）；服务不包含 blob 的克隆存放在其 mcp 子目录中。

开发

npm test -w @gitgoblin/mcp                                       # protocol tests with fakes, offline
npm run typecheck -w @gitgoblin/mcp
GITGOBLIN_E2E=1 npx vitest run --root packages/mcp test/e2e      # the real server over stdio, against GitHub
npm run bundle -w @gitgoblin/mcp                                 # what `npm pack` ships: dist/gitgoblin-mcp.mjs and its THIRD_PARTY_NOTICES.md
npm run mcpb -w @gitgoblin/mcp                                   # the Claude Desktop bundle: dist/gitgoblin.mcpb

src/server.ts 使用可注入的 ServerDeps（发现和情报）构建服务；src/format.ts 为模型呈现结果；src/deps.ts 连接实际使用的包；bin/gitgoblin-mcp.mjs 是启动器。开发时会在 Node 24 上运行 TypeScript 源代码。发布时会将源代码和同级包打包到一个文件中，且不包含运行时依赖，因为 Node 不会剥离 node_modules 下的类型。docs/design.md 说明了这些设计决策；server.json 是 MCP Registry 的清单，其中指向该版本的 .mcpb 文件及其 SHA-256。发布版本由仓库的发布工作流从合并提交上的 mcp-v<version> 标签构建，绝不从本地检出构建；docs/releasing.md 介绍了相关步骤，包括每次发布后运行的 MCP Registry 工作流。