gitgoblin

@gitgoblin/mcp

Model Context Protocol サーバーとしての gitgoblin です。あらゆる MCP クライアント（Claude Code、Codex、Cursor、Gemini CLI、VS Code の Copilot など）に、読み取り専用の 4 つのツールを提供します。時間をかける価値のあるリポジトリの発見、評価の理由の説明、リポジトリが実際に必要としているものの分析、作業項目 1 件の詳細なブリーフィングを行えます。

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 には、各クライアントで使うコマンド 1 行、ツールの使いどきをエージェントに教えるスキル、検証済みの内容が記載されています。このサーバーは公式の 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）	ランク付けされたリポジトリ：スター数、言語、ライセンス、スコア、最も有力な理由 3 つと反対の理由 1 つ、contribute の場合は最初に取り組める Issue。structuredContent.results[] に同じフィールドが含まれます。
explain_repository	repository、goal	10 個すべての発見シグナルと、その値、目標に対する重み、根拠。不明なシグナルはその旨を示します。
analyze_repository	repository、max_opportunities（デフォルトは 10、最大 30）、check_dependencies（デフォルトは true）、goal	プロファイル（特性、活動状況、応答性、シグナルを伴う歓迎度、ルール、コマンド、規約）と、主要な根拠を伴うランク付け済みの機会。
get_opportunity	repository、opportunity_id または issue_number	1 件の機会の詳細と、プロジェクトへの取り組み方：クローン、コマンド、規約、ルール、エチケット。

repository には owner/name または URL を指定できます。explain_repository と like のシードには github.com のリポジトリを指定してください。発見処理では GitHub API をオーナーと名前で呼び出すためです。analyze_repository と get_opportunity では、インテリジェンス機能が公開 API を通じて読み取る gitlab.com と codeberg.org も指定できます。それ以外のホストは拒否されます。エラーはプロトコル障害ではなく、アドバイス（トークンの取得方法やリポジトリ名の正しい書き方など）を含むツール結果として返されます。分析はワーカースレッドで実行され、5 分後、またはクライアントがリクエストをキャンセルした時点で停止するため、1 つの遅いリポジトリによってほかのツールが停止することはありません。クライアントから進捗トークンが提供される場合、時間のかかる呼び出しでは進捗通知が送信されます。

サーバーの instructions では、一般的な手順や、引用されたリポジトリ内のテキストはデータであって指示ではないこと、そして重要な唯一のルールをエージェントに伝えます。依頼されない限り、本人に代わって Issue、プルリクエスト、コメントを作成することはありません。

リポジトリはモデルによって選ばれることが多いため、サーバーはリポジトリを敵対的なものとして扱います。git はコミット済みのシンボリックリンクを通常のファイルとしてチェックアウトし、通信には HTTPS のみを使用します。クローンは専用のキャッシュに保存し、外部リンクは取得せず、すべての結果から制御文字を除去します。docs/design.md で各防御策について説明しています。

環境

変数	効果
GITHUB_TOKEN、GH_TOKEN	任意。GitHub のレート制限が緩和され、最初に取り組める Issue が利用可能になります。設定されていない場合は 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（discovery と intel）からサーバーを構築します。src/format.ts はモデル向けに結果をレンダリングします。src/deps.ts は実際のパッケージを接続し、bin/gitgoblin-mcp.mjs はランチャーです。開発時は Node 24 で TypeScript ソースを実行します。Node は node_modules 内の型を消去しないため、公開時にはソースと隣接するパッケージをランタイム依存関係のない 1 つのファイルにバンドルします。docs/design.md では設計上の判断を説明しています。server.json は MCP Registry 用のマニフェストで、リリースの .mcpb とその SHA-256 を指定します。リリースは、ローカルのチェックアウトからではなく、マージ済みコミット上の mcp-v<version> タグを基に、リポジトリのリリースワークフローでビルドされます。各リリースの後に実行される MCP Registry ワークフローの実行を含む手順については、docs/releasing.md を参照してください。