GitLumen MCP

GitLumen MCP 服务 - Version 1.0.0

GitLumen MCP 服务是一个 Node.js 项目，通过模型上下文协议（MCP）提供 GitLumen 风格的审查智能层，让 AI Agent 可以将其作为工具调用。

本项目专注于：

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 自定义插件。

---

功能

• MCP stdio 服务，可供 Claude Desktop、Cursor、Claude Code 或其他 MCP 客户端使用。
• 检查公开的 GitHub 仓库 URL。
• 检查 GitHub Pull Request URL /pull/<number>。
• 对小型和中型公开仓库，无需 GitHub 令牌。
• 可选使用 GITHUB_TOKEN 提高速率限制，并访问私有仓库（取决于令牌权限范围）。
• 本地分析器：源代码不会发送给外部大模型。
• 生成：
  • 风险评分
  • 分类风险图
  • 发现项
  • 审查章节
  • 决策问题
  • 合并就绪信号
  • 建议的后续操作
• 在本地 .gitlumen-mcp/reports/*.json 中存储报告。
• 提供 CLI，可在没有 MCP 客户端的情况下进行本地测试。

---

项目结构

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

此命令会根据本地 fixture 生成报告，以便你在无法连接 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，然后让 Agent 使用 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。

---

分析器的工作方式

本地分析器会读取：

• 仓库元数据
• 默认分支
• 递归目录树
• 选定的源文件/配置文件
• 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