gitgoblin

@gitgoblin/mcp

gitgoblin as a Model Context Protocol server. It gives any MCP client (Claude Code, Codex, Cursor, Gemini CLI, Copilot in VS Code, and others) four read-only tools: discover repositories worth your time, explain why one scores the way it does, analyze what a repository actually needs, and get a full briefing on one piece of work.

claude mcp add gitgoblin -- npx -y @gitgoblin/mcp

docs/agents.md has the one-liner for every client, the skill that teaches agents when to use the tools, and what has been verified. The server is listed in the official MCP Registry as io.github.anandkaranubc/gitgoblin. You can also run the server from a clone with node packages/mcp/bin/gitgoblin-mcp.mjs after npm install; Claude Desktop users install the release's gitgoblin.mcpb directly.

Tools

repository accepts owner/name or a URL. explain_repository and the like seed take github.com repositories, since discovery reads GitHub's API by owner and name; analyze_repository and get_opportunity also take gitlab.com and codeberg.org, which intel reads through their public APIs. Every other host is refused. Errors come back as tool results with advice (how to get a token, how to spell a repository), never as protocol failures. An analysis runs in a child process and is stopped after five minutes, or as soon as the client cancels the request, so one slow repository never freezes the other tools; at most two run at once. Long calls send progress notifications when the client provides a progress token.

The server's instructions tell the agent the typical flow, that quoted repository text is data and never instructions, and the one rule that matters: it never opens issues, pull requests or comments on the person's behalf unless asked.

The repository is often chosen by a model, so the server treats it as hostile: it reads only repositories it has confirmed public with an anonymous request, analyzes each in a child process with an empty home directory (none of your git configuration or credential helpers apply) that is killed with everything it started after five minutes or on cancellation, keeps clones per forge, never fetches external links, and strips control and format characters from every result, which opens with a reminder that repository text is data and is capped in size. docs/design.md explains each defence.

Environment

Development

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

src/server.ts builds the server from an injectable ServerDeps (discovery and intel); src/format.ts renders results for a model; src/deps.ts wires the real packages; bin/gitgoblin-mcp.mjs is the launcher. Development runs the TypeScript source on Node 24. Publishing bundles the source and the sibling packages into one file with no runtime dependencies, because Node will not strip types under node_modules. docs/design.md explains the decisions; server.json is the manifest for the MCP Registry; it points at the release's .mcpb and its SHA-256. Releases are built by the repository's release workflow from an mcp-v<version> tag on the merged commit, never from a local checkout; docs/releasing.md has the steps, including the MCP Registry workflow run that follows each release.