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:

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