GitLumen MCP

io.github.gitlumen-team由 GitHub 帳號 gitlumen-team 發布v1.0.0更新於 Oct 24, 2026

Screens public GitHub repos and PRs to generate risk maps, findings, and merge-readiness signals.

已驗證Streamable HTTP可網頁執行開發者工具安全與監控

概覽

AI 產生的概覽

GitLumen MCP 篩檢公開 GitHub 儲存庫與拉取請求，向 AI 助理回傳風險圖、發現項目與可合併性訊號。

可以做什麼
篩檢公開 GitHub 儲存庫或拉取請求網址，產生風險分數、分類風險圖、發現項目與可合併性訊號，支援精簡、Markdown 或 JSON 輸出。檢視儲存庫或 PR 結構，而不產生完整風險報告。依報告 ID 取得先前儲存的報告，或列出已存報告。說明此伺服器的審查流程，以及後續鏈上付款階段如何接入。
適用情境
適合讓助理對公開 GitHub 儲存庫或拉取請求快速給出風險與可合併性判斷，例如在審查或合併第三方程式碼之前。也適合在審查對話中調閱先前的篩檢報告。
執行需求
遠端端點，透過 streamable HTTP 存取，需在 Authorization 標頭提供 bearer 權杖。README 另描述本機 Node.js 20+ 版本，需要連線 GitHub 的網路，可選用 GITHUB_TOKEN 提高速率上限或存取私有儲存庫。
安裝前請注意
Authorization bearer 權杖為必填，屬於機密。篩檢會從 GitHub 取得儲存庫中繼資料與部分原始碼檔案；README 稱本機分析器不會將原始碼傳送給外部大型語言模型。儲存的報告可能包含檔案路徑、發現項目與程式碼片段中繼資料，私有儲存庫的報告應妥善保管。README 說明目前不執行鏈上交易。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 GitLumen MCP，將其新增到工作區。
  2. 連接 Authorization token 憑證。它們會被私密儲存，絕不會在公開頁面上展示。
  3. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式，或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南，先向你展示發布者、端點和登入方式，經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.gitlumen-team%2Fgitlumen-mcp/install.md，並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前，先告訴我它的發布者、端點和登入方式，等我確認。不要把 API 金鑰寫進命令或我會提交的檔案；問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "mcpServers": {
    "gitlumen": {
      "type": "http",
      "url": "https://mcp-github-screen.gitlumen.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

GitLumen MCP Server - Version 1.0.0

GitLumen MCP Server is a Node.js project that exposes a GitLumen-style review intelligence layer through the Model Context Protocol (MCP), so AI agents can call it as tools.

This project focuses on:

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

This project intentionally does not execute onchain transactions yet and does not use Base MCP send_calls. A Base MCP custom plugin can be attached in Path 2 after this intelligence server is ready.

Features

  • MCP stdio server that can be used by Claude Desktop, Cursor, Claude Code, or other MCP clients.
  • Screens public GitHub repository URLs.
  • Screens GitHub Pull Request URLs /pull/<number>.
  • No GitHub token required for small/medium public repositories.
  • Optional GITHUB_TOKEN for higher rate limits and private repositories (depending on token scope).
  • Local analyzer: source code is not sent to external LLMs.
  • Produces:
    • risk score
    • category risk map
    • findings
    • review chapters
    • decision questions
    • merge-readiness signal
    • recommended next actions
  • Stores reports locally in .gitlumen-mcp/reports/*.json.
  • Includes a CLI for local testing without an MCP client.

Project Structure

txt
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

Requirements

  • Node.js 20+
  • npm
  • Internet access to fetch metadata/files from GitHub

Check Node version:

bash
node -v

If your version is Node 18 or below, upgrade to Node 20+.

1. Install Dependencies

Open the project directory:

bash
cd gitlumen-mcp-server

Install dependencies:

bash
npm install

2. Optional Env Setup

Copy env example:

bash
cp .env.example .env

Fill optional values:

bash
GITHUB_TOKEN=ghp_xxx_or_fine_grained_tokenGITLUMEN_MCP_DATA_DIR=.gitlumen-mcpGITLUMEN_MAX_FILE_BYTES=120000

For public repositories, GITHUB_TOKEN can be empty. A token is still recommended to avoid low GitHub rate limits.

3. Run Doctor

bash
npm run doctor

Expected output:

txt
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. Test Screening via CLI

Offline test without GitHub network

bash
npm run sample

This command generates a report from a local fixture so you can verify analyzer and report-store behavior without GitHub connectivity.

Screen a public repository

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

Screen a public PR

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

Available scopes

txt
quick     = fastest, fewer filesstandard  = balanced default

Examples:

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

After completion, CLI prints a markdown report and saves JSON to:

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

5. Read Previous Reports

bash
npm run list -- 10

Take a reportId, then:

bash
npm run report -- glr_xxxxxxxxxxxxxxxx markdown

Or full JSON:

bash
npm run report -- glr_xxxxxxxxxxxxxxxx json

6. Run as MCP Server

The MCP server uses stdio, so it is normally started by an MCP client instead of being run manually.

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

To debug MCP protocol, use MCP Inspector:

bash
npm run inspect

Then open the Inspector URL printed in terminal.

Optional: Run as Remote MCP HTTP Server (for VPS/PM2)

This project also includes a Streamable HTTP transport endpoint at /mcp.

Run locally:

bash
npm run start:http

Environment variables:

bash
PORT=3333HOST=0.0.0.0MCP_AUTH_TOKEN=replace_with_a_long_random_token
  • MCP_AUTH_TOKEN is optional but strongly recommended for production.
  • When set, clients must send Authorization: Bearer <token>.

Health check:

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

Production deployment guide:

Client configuration templates (Copilot / VS Code / Codex):

7. Install in Claude Desktop

Open Claude Desktop config.

Common location:

macOS

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

Windows

txt
%APPDATA%\Claude\claude_desktop_config.json

Add:

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"      }    }  }}

Replace /ABSOLUTE/PATH/TO/... with your real path.

Restart Claude Desktop.

Example prompt:

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

8. Install in Cursor

Create or edit Cursor MCP config (format may vary by Cursor version):

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

Restart Cursor, then ask the agent to use GitLumen tools.

Available MCP Tools

screen_repository

Screen a repository or PR.

Input:

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

For PR:

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

Output modes:

txt
compact   = concise JSON for agent repliesmarkdown  = full markdown reportjson      = full JSON report

get_review_report

Fetch a previous report by reportId.

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

list_review_reports

List local reports.

json
{  "limit": 20}

get_repository_structure

Get repository/PR structure without generating a full risk report.

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

explain_gitlumen_mcp_flow

Explain Path 1 flow and how Path 2 Base MCP can be attached later.

How the Analyzer Works

The local analyzer reads:

  • repository metadata
  • default branch
  • recursive tree
  • selected source/config files
  • PR metadata and changed files (for PR URLs)

Then it generates signals:

  • language/framework detection
  • dependency surface
  • lockfile presence
  • lifecycle script risk
  • test presence
  • CI presence
  • Dockerfile/container risk
  • possible hardcoded secret patterns
  • dynamic code execution
  • command execution pattern
  • SQL interpolation pattern
  • GitHub Actions supply-chain pattern
  • merge-readiness estimate

Risk categories:

txt
securitydependenciestestsarchitectureoperationsmaintainability

Severity:

txt
criticalhighmediumlowinfo

Example Compact Report Output

json
{  "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 vs Path 2

Path 1 (this project)

txt
Repo/PR intelligenceRisk mapReview chaptersDecision questionsReport retrieval

Path 2 (future)

txt
Base MCP get_walletsGitLumen quote endpointGitLumen prepare endpointBase MCP send_callsReview credit purchaseReward claimReviewer reputation

This project is intentionally standalone for Path 1 first. Later, Path 2 can read reportId and connect it with onchain payment/reward/reputation flows.

Troubleshooting

Unable to reach GitHub API or fetch failed

Check internet connection, DNS, proxy/VPN, or retry. For offline verification:

bash
npm run sample

GitHub API 403 rate limit exceeded

Add GITHUB_TOKEN in .env or MCP client config.

Only github.com repositories are supported

This prototype does not support GitLab/Bitbucket yet. Add a new adapter in src/services/github.js or create a separate service.

MCP client cannot see tools

Check:

  1. args path is absolute.
  2. npm install has been run.
  3. Node 20+ is installed.
  4. MCP client was restarted.
  5. Verify with npm run inspect.

Report is not saved

Run:

bash
npm run doctor

Ensure .gitlumen-mcp/reports is writable.

Important Files for Future Changes

Add a new detector

Edit:

txt
src/services/analyzer.js

Change repository fetching behavior

Edit:

txt
src/services/github.js

Replace local analyzer with hosted GitLumen API

Edit:

txt
src/services/gitlumen.js

Potential production direction:

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

Security Notes

  • Do not commit .env.
  • Do not hardcode GitHub tokens in publicly shared config.
  • For private repositories, use least-privilege fine-grained GitHub tokens.
  • Local reports may contain paths, findings, and snippet metadata. Store them securely for private repositories.

License

MIT

來源：README.md，提交 81e5132

工具

0
SourceWeft 尚未讀取此伺服器的工具。

版本歷史

1
  1. v1.0.0最新Sep 16, 2026

評分

已滿足適用檢查項的 75%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。