GitHub Assistant MCP

Model Context Protocol（MCP）サーバーを実装した、小規模で自己完結型のサーバーです。AIコーディングアシスタント（例：OpenCode）に5つの読み取り専用ツールを公開します。このサーバーにより、アシスタントはローカルワークスペースを検査し、クリーンでサンドボックス化されたstdioトランスポート経由で公開GitHubプロフィールを取得できます。

「OpenCodeのためのシンプルなGitHub MCPサーバー」

目次

• 概要

• 動作の仕組み（アーキテクチャ）

• トランスポートとライフサイクル

• ツールリファレンス

• セキュリティモデル

• プロジェクトウォークスルー

• 設定

• ビルドと実行

• ファイル構成

• 制限事項

Related MCP server: chatgpt-codex-local-mcp

概要

このサーバーは、OpenCodeが子プロセスとして起動するローカルMCPサーバーです。stdio（stdin/stdout）経由でMCPプロトコルを話し、5つのツールを登録します。アシスタントがツールを呼び出すと、サーバーが処理（ファイルシステムの読み取り、git diff、またはGitHub API呼び出し）を実行し、構造化されたテキスト結果を返します。

ファイルシステムに触れる処理はすべて単一のWORKSPACE_ROOTディレクトリに限定されるため、アシスタントがプロジェクトフォルダの外を読み取ったり、外部へ逃れたりすることは絶対にできません。

動作の仕組み（アーキテクチャ）

┌─────────────────────────┐         stdio (MCP/JSON-RPC)        ┌──────────────────────────────┐
│                         │  ───────────────────────────────▶  │   github-assistant  (this)   │
│     OpenCode / AI       │  tool call: get_github_profile     │                              │
│     Assistant           │                                    │  ┌────────────────────────┐  │
│                         │  ◀───────────────────────────────  │  │      McpServer          │  │
│  - sees 5 tools         │     result (JSON text)             │  │  (server.ts)            │  │
│  - calls them           │                                    │  └───────────┬────────────┘  │
│  - sandbox enforced     │                                    │              │ registerTools  │
└─────────────────────────┘                                    └──────────────┼──────────────┘
                                                                          ▼
                                                         ┌────────────────────────────────┐
                                                         │  tools.ts  (5 tool handlers)   │
                                                         └───┬──────┬──────┬──────┬─────┬──┘
                                          ┌───────────────┘      │      │      │     │
                                          ▼                      ▼      ▼      ▼     ▼
                                   ┌────────────┐        ┌────────────┐ ┌─────────┐ ┌────────────┐
                                   │ github.ts  │        │ workspace.ts│ │ git.ts │ │ paths.ts   │
                                   │ GitHub API │        │ list/read/  │ │ git diff│ │ resolve    │
                                   │ (fetch)   │        │ search      │ │         │ │ sandbox    │
                                   └─────┬──────┘        └─────┬──────┘ └────┬────┘ └─────┬──────┘
                                         │                    │            │           │
                                         ▼                    ▼            ▼           ▼
                                 api.github.com       WORKSPACE_ROOT/*   git CLI    config.ts
                                                        (files only)   (cwd=root)  WORKSPACE_ROOT

単一のツール呼び出しのデータフロー:

Assistant ──JSON-RPC request──▶ McpServer
                                     │
                                     ▼
                               tool handler (tools.ts)
                                     │  validates args with zod
                                     ▼
                          business logic (github / workspace / git / paths)
                                     │  resolveWorkspacePath() enforces sandbox
                                     ▼
                          result helper (result.ts) → { content: [{ type:"text", text }] }
                                     │
                                     ▼
Assistant ◀──JSON-RPC response── McpServer

トランスポートとライフサイクル

• タイプ: local — OpenCodeがサーバーを子プロセスとして起動します。

• トランスポート: @modelcontextprotocol/server/stdio の serveStdio() による stdio。

• 起動シーケンス:

  1. node dist/server.js が実行されます（opencode.json で宣言、cwd = "."）。

  2. createServer() が github-assistant（v1.0.0）という名前の McpServer を構築します。

  3. registerTools(server) が5つのツールを配線します。

  4. serveStdio(createServer) がstdinからJSON-RPCメッセージを読み取り、結果をstdoutに書き込み始めます。

• シャットダウン: セッション終了時にOpenCodeがプロセスを終了します。

プロセスはOpenCodeの作業ディレクトリを継承するため、WORKSPACE_ROOT はプロジェクトディレクトリ（path.resolve(process.cwd())）に解決されます。

ツールリファレンス

すべてのツールは src/tools.ts に登録され、MCPテキスト結果（JSONまたはプレーンテキスト）を返します。

1. get_github_profile

ハードコードされたユーザー（imshashwatsingh）の公開GitHubプロフィールを取得します。

• 入力: なし

• バックエンド: Accept: application/vnd.github+json と User-Agent ヘッダーを付けた https://api.github.com/users/imshashwatsingh への fetch()。

• 戻り値: ユーザー名、名前、会社、所在地、自己紹介、公開リポジトリ/公開gist数、フォロワー数、フォロー中数、プロフィールURL、作成/更新タイムスタンプ。

• ファイル: src/github.ts

2. list_files

ワークスペースディレクトリ配下のファイルを深さ指定付きで一覧表示します。

• 入力: path（デフォルト "."）、maxDepth（0〜10、デフォルト3）

• バックエンド: src/workspace.ts の再帰的 collectFiles() — シンボリックリンクをスキップし（ループ防止）、設定済みディレクトリ（node_modules、.git、dist、.next、coverage、.cache）を無視します。MAX_RESULTS（500）で上限を設定。

• 戻り値: ワークスペースルート、ファイル数、相対ファイルパス。

• ファイル: src/workspace.ts

3. read_file

オプションの行範囲指定付きでUTF-8テキストファイルを読み取ります。

• 入力: path（必須）、startLine（オプション）、endLine（オプション）

• バックエンド: readWorkspaceFile() — サンドボックスを強制し、非ファイルを拒否し、MAX_FILE_SIZE（1 MB）を超えるファイルとバイナリ拡張子のファイルを拒否します。行番号付きで返します。

• 戻り値: 行番号: テキスト のプレフィックス付きファイル内容。

• ファイル: src/workspace.ts

4. search_context

ワークスペース全体を周辺コンテキスト付きでキーワード検索します。

• 入力: query（必須）、path（デフォルト "."）、maxResults（1〜100、デフォルト50）、contextLines（0〜10、デフォルト2）

• バックエンド: searchContext() がファイルを収集し、テキストのみ・サイズ制限内のファイルに絞り込み、各行を（大文字小文字を区別せずに）スキャンし、各一致の前後 contextLines 行を取得します。

• 戻り値: クエリ、検索パス、一致数、およびファイル/行/コンテキスト付きの一致結果。

• ファイル: src/workspace.ts

5. summarize_diff

現在のGit diffを検査し、構造化されたサマリーを返します。

• 入力: staged（デフォルト false）、base（オプションのgit参照）、path（オプションのファイル/ディレクトリ）、maxDiffChars（1000〜200000、デフォルト50000）

• バックエンド: summarizeDiff() が WORKSPACE_ROOT から git diff --no-ext-diff --unified=3（--cached / base参照 / pathフィルター付き）を実行します。統計はunified diff自体から解析されます（2回目の git 呼び出しは不要）。diffが maxDiffChars を超える場合は切り詰められます。

• 戻り値: 変更ファイル数、挿入数、削除数、ファイルごとの統計、生のdiff — 変更がない場合は { empty: true }。

• ファイル: src/git.ts

セキュリティモデル

このサーバーは意図的に読み取り専用かつサンドボックス化されています:

サンドボックス境界は完全に paths.ts に存在します。ファイルシステムに触れる新しいツールは必ず resolveWorkspacePath() 経由でパスをルーティングする必要があります。

プロジェクトウォークスルー

1. エントリポイント — src/server.ts createServer() が McpServer をインスタンス化し、registerTools() を呼び出します。serveStdio() がそれをstdin/stdoutに橋渡しします。

2. ツール登録 — src/tools.ts 5つの server.registerTool(...) 呼び出し。それぞれが説明、zod検証済みの inputSchema、非同期ハンドラーを宣言します。ハンドラーは以下のモジュールに委譲し、result.ts のヘルパーで出力をラップします。

3. 設定 — src/config.ts 中央定数: WORKSPACE_ROOT（process.cwd() から解決）、サイズ/結果の上限、GitHubユーザー名/URL、無視セットとバイナリセット。

4. パス安全性 — src/paths.ts resolveWorkspacePath() がサンドボックスゲートです。toWorkspaceRelative() は絶対パスを表示用のワークスペース相対文字列に戻します。isProbablyTextFile() は拡張子でファイルを分類します。

5. ワークスペースI/O — src/workspace.ts collectFiles()（再帰的一覧表示）、readWorkspaceFile()（安全な読み取り）、searchContext()（キーワードスキャン）。すべて resolveWorkspacePath() を経由します。

6. GitHub — src/github.ts fetchGitHubProfile() が公開APIを呼び出し、生の GitHubUser をより親しみやすい GitHubProfile の形にマッピングします。

7. Git — src/git.ts summarizeDiff() が git diff コマンドを構築・実行します。parseDiffStats() はdiffテキストから直接、ファイルごとの挿入/削除数を導出します。

8. 結果 — src/result.ts 小さなヘルパー（textResult、errorResult、errorWithContext）がMCPの content エンベロープとエラーフラグを標準化します。

設定

opencode.json（プロジェクトルート）がサーバーを宣言します:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github-assistant": {
      "type": "local",
      "command": ["node", "dist/server.js"],
      "cwd": ".",
      "enabled": true
    }
  }
}

サーバー内部では、src/config.ts の定数で動作を調整します:

ビルドと実行

# install dependencies
npm install

# compile TypeScript -> dist/
npm run build

# start the server (used by opencode.json)
npm start

# run directly from source (no build step)
npm run dev

# the workspace must be a git repo for summarize_diff to work
git init

ビルド後（dist/server.js）、OpenCodeは opencode.json からサーバーを自動的に認識します。

ファイル構成

github_assistant_mcp/
├── opencode.json          # MCP server declaration for OpenCode
├── package.json           # scripts + dependencies
├── tsconfig.json          # TypeScript config
├── src/
│   ├── server.ts          # Entry point: create + serve McpServer
│   ├── tools.ts           # Registers the 5 tools + handlers
│   ├── config.ts          # Constants, limits, GitHub target
│   ├── paths.ts           # Sandbox path resolution + helpers
│   ├── workspace.ts       # list / read / search filesystem
│   ├── github.ts          # GitHub profile fetch
│   ├── git.ts             # git diff summary + stat parsing
│   └── result.ts          # MCP result/error helpers
└── dist/                  # Compiled output (npm run build)

制限事項

• get_github_profile は単一のハードコードされたユーザーを対象としており、パラメータ化されていません。

• summarize_diff は作業ツリーの変更のみを報告します — 未追跡ファイルは git diff に表示されません。

• ファイルシステムツールは WORKSPACE_ROOT に限定されており、プロジェクト間アクセスはできません。

• すべてのツールは設計上読み取り専用です — 編集、削除、シェル実行はありません。

• 認証なし: GitHub呼び出しは未認証の公開APIを使用します（IPあたり毎時60リクエストにレート制限）。