GitLumen MCP

GitLumen MCP サーバー - Version 1.0.0

GitLumen MCP サーバーは、Model Context Protocol（MCP）を通じてGitLumenスタイルのレビューインテリジェンスレイヤーを公開するNode.jsプロジェクトです。AIエージェントは、これをツールとして呼び出すことができます。

このプロジェクトでは、以下に重点を置いています。

AI Agent / MCP Client
-> GitLumen MCP Server
-> GitHub public repo / PR reader
-> local risk analyzer
-> GitLumen-style report

このプロジェクトでは、現時点ではオンチェーントランザクションを実行せず、Base MCPのsend_callsも使用しません。このインテリジェンスサーバーの準備ができた後、Path 2でBase MCPのカスタムプラグインを追加できます。

---

機能

• Claude Desktop、Cursor、Claude Code、その他のMCPクライアントで使用できるMCP stdioサーバー。
• 公開GitHubリポジトリのURLをスクリーニングします。
• GitHubプルリクエストのURL /pull/<number> をスクリーニングします。
• 小規模・中規模の公開リポジトリでは、GitHubトークンは不要です。
• レート制限の緩和やプライベートリポジトリへのアクセス（トークンのスコープによって異なります）には、GITHUB_TOKENを任意で設定できます。
• ローカルアナライザー：ソースコードが外部LLMに送信されることはありません。
• 以下を出力します。
  • リスクスコア
  • カテゴリ別リスクマップ
  • 検出結果
  • レビューの章
  • 判断に関する質問
  • マージ準備状況のシグナル
  • 推奨される次のアクション
• レポートをローカルの.gitlumen-mcp/reports/*.jsonに保存します。
• MCPクライアントを使わずにローカルテストを行うためのCLIが含まれています。

---

プロジェクト構成

gitlumen-mcp-server/
|- package.json
|- README.md
|- .env.example
|- examples/
|  |- claude_desktop_config.example.json
|  \- cursor_mcp.example.json
|- docs/
|  |- ARCHITECTURE.md
|  \- TOOLS.md
\- src/
   |- index.js                  # MCP stdio server entrypoint
   |- cli.js                    # CLI local test
   |- doctor.js                 # environment checker
   |- config.js
   |- types.js
   |- services/
   |  |- github.js              # GitHub API + raw file loader
   |  |- analyzer.js            # local heuristic risk engine
   |  |- gitlumen.js            # service orchestrator
   |  \- reportStore.js         # local report persistence
   \- utils/
      |- githubUrl.js
      |- ids.js
      \- text.js

---

必要条件

• Node.js 20+
• npm
• GitHubからメタデータやファイルを取得するためのインターネット接続

Nodeのバージョンを確認します。

node -v

Node 18以下を使用している場合は、Node 20+にアップグレードしてください。

---

1. 依存関係をインストールする

プロジェクトディレクトリを開きます。

cd gitlumen-mcp-server

依存関係をインストールします。

npm install

---

2. 環境変数の設定（任意）

環境変数の例をコピーします。

cp .env.example .env

任意の値を入力します。

GITHUB_TOKEN=ghp_xxx_or_fine_grained_token
GITLUMEN_MCP_DATA_DIR=.gitlumen-mcp
GITLUMEN_MAX_FILE_BYTES=120000

公開リポジトリの場合、GITHUB_TOKENは空でもかまいません。ただし、GitHubの低いレート制限を回避するため、トークンの設定をおすすめします。

---

3. Doctorを実行する

npm run doctor

想定される出力：

GitLumen MCP Doctor

✅ Node version: v20.x.x
✅ GITHUB_TOKEN configured: no (public unauthenticated mode)
✅ Data directory: /path/to/gitlumen-mcp-server/.gitlumen-mcp
✅ Reports directory writable: /path/to/gitlumen-mcp-server/.gitlumen-mcp/reports

---

4. CLIでスクリーニングをテストする

GitHubネットワークを使わないオフラインテスト

npm run sample

このコマンドはローカルフィクスチャからレポートを生成します。GitHubに接続せずに、アナライザーとレポートストアの動作を確認できます。

公開リポジトリをスクリーニングする

npm run screen -- https://github.com/modelcontextprotocol/typescript-sdk quick

公開PRをスクリーニングする

npm run screen -- https://github.com/modelcontextprotocol/typescript-sdk/pull/1 quick

使用可能なスコープ

quick     = fastest, fewer files
standard  = balanced default

例：

npm run screen -- https://github.com/owner/repo standard
npm run screen -- https://github.com/owner/repo quick main

完了すると、CLIはMarkdownレポートを出力し、JSONを以下に保存します。

.gitlumen-mcp/reports/<reportId>.json

---

5. 過去のレポートを読む

npm run list -- 10

reportIdを取得し、次を実行します。

npm run report -- glr_xxxxxxxxxxxxxxxx markdown

または、完全なJSONを取得します。

npm run report -- glr_xxxxxxxxxxxxxxxx json

---

6. MCPサーバーとして実行する

MCPサーバーはstdioを使用するため、通常は手動で実行するのではなく、MCPクライアントによって起動されます。

node /ABSOLUTE/PATH/TO/gitlumen-mcp-server/src/index.js

MCPプロトコルをデバッグするには、MCP Inspectorを使用します。

npm run inspect

その後、ターミナルに表示されたInspectorのURLを開きます。

任意：リモートMCP HTTPサーバーとして実行する（VPS/PM2向け）

このプロジェクトには、/mcpのStreamable HTTPトランスポートエンドポイントも含まれています。

ローカルで実行します。

npm run start:http

環境変数：

PORT=3333
HOST=0.0.0.0
MCP_AUTH_TOKEN=replace_with_a_long_random_token

• MCP_AUTH_TOKENは任意ですが、本番環境では強く推奨されます。
• 設定した場合、クライアントはAuthorization: Bearer <token>を送信する必要があります。

ヘルスチェック：

curl -s http://localhost:3333/health

本番環境へのデプロイガイド：

• PM2の設定例：examples/ecosystem.pm2.example.cjs

クライアント設定テンプレート（Copilot / VS Code / Codex）：

• docs/CLIENT_CONFIG_TEMPLATES.md
• VS Codeのリモートエンドポイントテンプレート：examples/vscode_mcp.gitlumen.remote.example.json（.vscode/mcp.jsonにコピーしてください。このファイルはgitignoreの対象です）

---

7. Claude Desktopにインストールする

Claude Desktopの設定を開きます。

一般的な場所：

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

以下を追加します。

{
  "mcpServers": {
    "gitlumen": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gitlumen-mcp-server/src/index.js"],
      "env": {
        "GITHUB_TOKEN": "optional_github_token_here",
        "GITLUMEN_MCP_DATA_DIR": "/ABSOLUTE/PATH/TO/gitlumen-mcp-server/.gitlumen-mcp"
      }
    }
  }
}

/ABSOLUTE/PATH/TO/...を実際のパスに置き換えます。

Claude Desktopを再起動します。

プロンプトの例：

Use GitLumen to screen https://github.com/modelcontextprotocol/typescript-sdk with quick scope. Return the risk map and top findings.

---

8. Cursorにインストールする

CursorのMCP設定を作成または編集します（形式はCursorのバージョンによって異なる場合があります）。

{
  "mcpServers": {
    "gitlumen": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gitlumen-mcp-server/src/index.js"],
      "env": {
        "GITHUB_TOKEN": "optional_github_token_here"
      }
    }
  }
}

Cursorを再起動し、GitLumenのツールを使用するようエージェントに依頼します。

---

使用可能なMCPツール

screen_repository

リポジトリまたはPRをスクリーニングします。

入力：

{
  "repoUrl": "https://github.com/owner/repo",
  "scope": "standard",
  "output": "compact"
}

PRの場合：

{
  "repoUrl": "https://github.com/owner/repo/pull/123",
  "scope": "quick",
  "output": "markdown"
}

出力モード：

compact   = concise JSON for agent replies
markdown  = full markdown report
json      = full JSON report

get_review_report

reportId を指定して過去のレポートを取得します。

{
  "reportId": "glr_xxxxxxxxxxxxxxxx",
  "output": "markdown"
}

list_review_reports

ローカルのレポートを一覧表示します。

{
  "limit": 20
}

get_repository_structure

完全なリスクレポートを生成せずに、リポジトリ／PR の構造を取得します。

{
  "repoUrl": "https://github.com/owner/repo",
  "limit": 300
}

explain_gitlumen_mcp_flow

Path 1 のフローと、後から Path 2 Base MCP を接続する方法を説明します。

---

Analyzer の仕組み

ローカルアナライザーは、次の情報を読み取ります。

• リポジトリのメタデータ
• デフォルトブランチ
• 再帰的なツリー
• 選択されたソース／設定ファイル
• PR のメタデータと変更ファイル（PR URL の場合）

その後、次のシグナルを生成します。

• 言語／フレームワークの検出
• 依存関係の範囲
• ロックファイルの有無
• ライフサイクルスクリプトのリスク
• テストの有無
• CI の有無
• Dockerfile／コンテナのリスク
• ハードコードされたシークレットのパターンの可能性
• 動的コード実行
• コマンド実行パターン
• SQL 補間パターン
• GitHub Actions のサプライチェーンパターン
• マージ準備状況の推定

リスクカテゴリ：

security
dependencies
tests
architecture
operations
maintainability

重大度：

critical
high
medium
low
info

---

コンパクトなレポート出力の例

{
  "reportId": "glr_abc123...",
  "risk": {
    "score": 42,
    "level": "medium",
    "mergeReadiness": "review_required",
    "categoryScores": {
      "security": 24,
      "dependencies": 13,
      "tests": 24,
      "architecture": 0,
      "operations": 13,
      "maintainability": 5
    }
  },
  "summary": "The repository/PR has medium risk signals...",
  "findings": [],
  "decisionQuestions": [],
  "recommendations": []
}

---

Path 1 と Path 2

Path 1（このプロジェクト）

Repo/PR intelligence
Risk map
Review chapters
Decision questions
Report retrieval

Path 2（今後）

Base MCP get_wallets
GitLumen quote endpoint
GitLumen prepare endpoint
Base MCP send_calls
Review credit purchase
Reward claim
Reviewer reputation

このプロジェクトは、まず Path 1 のための単独プロジェクトとして意図的に設計されています。今後、Path 2 では reportId を読み取り、オンチェーンの支払い／報酬／評判のフローと連携できます。

---

トラブルシューティング

Unable to reach GitHub API または fetch failed

インターネット接続、DNS、プロキシ／VPN を確認するか、再試行してください。オフラインで確認するには、次を実行します。

npm run sample

GitHub API 403 rate limit exceeded

.env または MCP クライアントの設定に GITHUB_TOKEN を追加してください。

Only github.com repositories are supported

このプロトタイプはまだ GitLab／Bitbucket に対応していません。src/services/github.js に新しいアダプターを追加するか、別のサービスを作成してください。

MCP クライアントにツールが表示されない

次の点を確認してください。

1. args のパスが絶対パスであること。
2. npm install を実行済みであること。
3. Node 20 以降がインストールされていること。
4. MCP クライアントを再起動したこと。
5. npm run inspect で確認すること。

レポートが保存されない

次を実行してください。

npm run doctor

.gitlumen-mcp/reports に書き込み権限があることを確認してください。

---

今後の変更に関する重要なファイル

新しい検出器を追加する

次を編集します。

src/services/analyzer.js

リポジトリの取得動作を変更する

次を編集します。

src/services/github.js

ローカルアナライザーをホスト型 GitLumen API に置き換える

次を編集します。

src/services/gitlumen.js

本番環境で想定される方向性：

screen_repository MCP tool
-> GitLumen hosted API /v1/screenings
-> GitLumen Review Intelligence Engine
-> reportId
-> get_review_report MCP tool

---

セキュリティに関する注意事項

• .env をコミットしないでください。
• 公開される設定に GitHub トークンをハードコードしないでください。
• プライベートリポジトリでは、最小限の権限を持つきめ細かな GitHub トークンを使用してください。
• ローカルレポートには、パス、検出結果、スニペットのメタデータが含まれる場合があります。プライベートリポジトリのレポートは安全に保管してください。

---

ライセンス

MIT