GitHub MCP Server

Node.js と TypeScript で構築された MCP サーバー。自然言語で GitHub の操作を実行できるエージェントに対応します。

アーキテクチャ

Usuario -> Antigravity (Host) -> MCP Client -> MCP Server -> Octokit -> GitHub API

チャットボットは主に会話を行います。アシスタント AI は追加の機能を使って支援します。AI エージェントは目標を解釈し、必要なアクションを決定し、ツールを使ってそれを達成します。

MCP（Model Context Protocol）は、AI ホスト、MCP クライアント、ツールやデータソースを公開するサーバー間の通信を標準化します。このプロジェクトではトランスポートとして stdio を使用します。プロトコルメッセージは stdin/stdout を介して送受信され、ログは stderr に出力されます。

Related MCP server: GitHub MCP Server

テクノロジー

• Node.js 18 以上

• TypeScript、strict: true 設定

• @modelcontextprotocol/sdk

• @octokit/rest

• zod

• dotenv

• Vitest

インストール

npm install
npm run build

設定

.env.example を .env としてコピーし、トークンをローカルで設定します：

GITHUB_TOKEN=tu_token_de_github

.env は .gitignore によって除外されており、コミットしてはいけません。

トークンには必要な権限のみを付与してください。プライベートリポジトリの場合、fine-grained トークンはリポジトリおよびコンテンツ/イシューへのアクセスを許可する必要があります。クラシックな PAT では repo が必要になる場合があります。user 権限はユーザー操作にのみ必要で、admin:org は現在の 5 つのツールには不要です（組織がその権限を要求しない限り）。トークンを例、テスト、ログ、MCP レスポンスに含めないでください。

スクリプト

npm run dev       # Ejecuta TypeScript directamente
npm run build     # Compila a dist/
npm start         # Ejecuta el JavaScript compilado
npm test          # Ejecuta los tests unitarios

MCP ツール

create_repository

認証済みアカウントで新しいリポジトリを作成します。

入力：name、description。

出力：リポジトリの完全な名前と URL。

create_issue

既存のリポジトリにイシューを作成します。

入力：owner、repo、title、body。

出力：イシュー番号、タイトル、URL。

list_repositories

認証済みユーザーのリポジトリを一覧表示します。

オプション入力：page、per_page。

出力：完全な名前と URL の要約リスト。

create_commit

Contents API を使用してファイルを作成または更新し、コミットを生成します。

入力：owner、repo、path、message、content。branch はオプションです。

このツールはまずファイルを照会します。ファイルが存在する場合はその SHA を使用し、GitHub が 404 を返した場合は SHA なしでファイルを作成します。

list_issues

リポジトリのオープンなイシューを一覧表示し、プルリクエストを除外します。

入力：owner、repo。page と per_page はオプションです。

エラーハンドリング

エラーは ValidationError、AuthenticationError、GitHubAPIError、NetworkError として分類されます。MCP レスポンスには実用的なメッセージが含まれ、資格情報を漏洩させる可能性のある技術的なメッセージは転送されません。

操作は、レート制限、5xx エラー、または回復可能なネットワークエラーの場合にのみ、最大 3 回再試行されます。検証エラー、認証エラー、および存在しないリソースは再試行されません。

テスト

テストは実際の GitHub を呼び出しません。モックされた Octokit クライアントを使用し、以下をカバーします：

• リポジトリとイシューのスキーマの有効/無効ケース

• リポジトリとイシューの作成

• リポジトリとオープンなイシューの一覧表示

• 新しいファイルの作成

• SHA を使用した既存ファイルの更新

• エラーの変換

• バックオフを伴う再試行

npm test を実行して完全なスイートを実行します。

MCP Inspector

プロジェクトをコンパイルし、Inspector を使用してサーバーを起動します：

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Inspector を起動する前に、環境で GITHUB_TOKEN を設定します。5 つのツール、その説明、スキーマが表示されることを確認します。実際のテストにはテスト用リポジトリを使用し、破壊的な操作は避けてください。

Antigravity と VS Code

.vscode/mcp.json には、資格情報を含まない stdio 設定が含まれています。Host からサーバーを起動する前に npm run build を使用します。この設定は dist/index.js を実行し、GITHUB_TOKEN をローカル環境から取得します。

MCP 対応の他の Host では、同等のコマンドを登録します：

{
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"],
  "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
}

Host が create_repository、create_issue、list_repositories、create_commit、list_issues を検出することを確認します。

構造

src/
  errors/       Errores clasificados y sanitizacion
  github/       Cliente Octokit y operaciones GitHub
  schemas/      Schemas Zod y tipos inferidos
  tools/        Handlers MCP individuales
  utils/        Retry, logging, respuestas y ensamblado del servidor
  index.ts      Entrada y transporte stdio
tests/          Tests unitarios con mocks

セキュリティ

• トークンをハードコードしない。

• .env をコミットしない。

• トークンや認証ヘッダーをログに出力しない。

• プロトコルを汚染しないように、ログは stderr に保持する。

• PAT には最小権限の原則を適用する。

• GitHub に書き込むツールを実行する前に、変更内容を確認する。