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_token
GITLUMEN_MCP_DATA_DIR=.gitlumen-mcp
GITLUMEN_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 files
standard  = balanced default

Examples:

npm run screen -- https://github.com/owner/repo standard
npm 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=3333
HOST=0.0.0.0
MCP_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 replies
markdown  = full markdown report
json      = 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:

security
dependencies
tests
architecture
operations
maintainability

Severity:

critical
high
medium
low
info

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 intelligence
Risk map
Review chapters
Decision questions
Report retrieval

Path 2 (future)

Base MCP get_wallets
GitLumen quote endpoint
GitLumen prepare endpoint
Base MCP send_calls
Review credit purchase
Reward claim
Reviewer 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:

args path is absolute.
npm install has been run.
Node 20+ is installed.
MCP client was restarted.
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

GitLumen MCP

GitLumen MCP Server - Version 1.0.0

Features

Project Structure

Requirements

1. Install Dependencies

2. Optional Env Setup

3. Run Doctor

4. Test Screening via CLI

Offline test without GitHub network

Screen a public repository

Screen a public PR

Available scopes

5. Read Previous Reports

6. Run as MCP Server

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

7. Install in Claude Desktop

macOS

Windows

8. Install in Cursor

Available MCP Tools

screen_repository

get_review_report

list_review_reports

get_repository_structure

explain_gitlumen_mcp_flow

How the Analyzer Works

Example Compact Report Output

Path 1 vs Path 2

Path 1 (this project)

Path 2 (future)

Troubleshooting

Unable to reach GitHub API or fetch failed

GitHub API 403 rate limit exceeded

Only github.com repositories are supported

MCP client cannot see tools

Report is not saved

Important Files for Future Changes

Add a new detector

Change repository fetching behavior

Replace local analyzer with hosted GitLumen API

Security Notes

License

`screen_repository`

`get_review_report`

`list_review_reports`

`get_repository_structure`

`explain_gitlumen_mcp_flow`

`Unable to reach GitHub API` or `fetch failed`

`GitHub API 403 rate limit exceeded`

`Only github.com repositories are supported`