GitLumen MCP

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:

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

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:

node -v

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

1. Install Dependencies

Open the project directory:

cd gitlumen-mcp-server

Install dependencies:

npm install

2. Optional Env Setup

Copy env example:

cp .env.example .env

Fill optional values:

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

npm run doctor

Expected output:

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

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

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

Screen a public PR

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

Available scopes

quick     = fastest, fewer filesstandard  = balanced default

Examples:

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:

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

5. Read Previous Reports

npm run list -- 10

Take a reportId, then:

npm run report -- glr_xxxxxxxxxxxxxxxx markdown

Or full JSON:

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.

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

To debug MCP protocol, use MCP Inspector:

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:

npm run start:http

Environment variables:

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:

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

Production deployment guide:

• PM2 example config: examples/ecosystem.pm2.example.cjs

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

• docs/CLIENT_CONFIG_TEMPLATES.md
• VS Code remote endpoint template: examples/vscode_mcp.gitlumen.remote.example.json (copy into .vscode/mcp.json, which is gitignored)

7. Install in Claude Desktop

Open Claude Desktop config.

Common location:

macOS

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

Windows

%APPDATA%\Claude\claude_desktop_config.json

Add:

{  "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:

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):

{  "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:

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

For PR:

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

Output modes:

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

get_review_report

Fetch a previous report by reportId.

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

list_review_reports

List local reports.

{  "limit": 20}

get_repository_structure

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

{  "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:

securitydependenciestestsarchitectureoperationsmaintainability

Severity:

criticalhighmediumlowinfo

Example Compact Report Output

{  "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)

Repo/PR intelligenceRisk mapReview chaptersDecision questionsReport retrieval

Path 2 (future)

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:

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:

npm run doctor

Ensure .gitlumen-mcp/reports is writable.

Important Files for Future Changes

Add a new detector

Edit:

src/services/analyzer.js

Change repository fetching behavior

Edit:

src/services/github.js

Replace local analyzer with hosted GitLumen API

Edit:

src/services/gitlumen.js

Potential production direction:

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