{
  "markdown": "# GitLumen MCP Server - Version 1.0.0\n\nGitLumen 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.\n\nThis project focuses on:\n\n```txt\nAI Agent / MCP Client\n-> GitLumen MCP Server\n-> GitHub public repo / PR reader\n-> local risk analyzer\n-> GitLumen-style report\n```\n\nThis 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.\n\n---\n\n## Features\n\n- MCP stdio server that can be used by Claude Desktop, Cursor, Claude Code, or other MCP clients.\n- Screens public GitHub repository URLs.\n- Screens GitHub Pull Request URLs `/pull/<number>`.\n- No GitHub token required for small/medium public repositories.\n- Optional `GITHUB_TOKEN` for higher rate limits and private repositories (depending on token scope).\n- Local analyzer: source code is not sent to external LLMs.\n- Produces:\n  - risk score\n  - category risk map\n  - findings\n  - review chapters\n  - decision questions\n  - merge-readiness signal\n  - recommended next actions\n- Stores reports locally in `.gitlumen-mcp/reports/*.json`.\n- Includes a CLI for local testing without an MCP client.\n\n---\n\n## Project Structure\n\n```txt\ngitlumen-mcp-server/\n|- package.json\n|- README.md\n|- .env.example\n|- examples/\n|  |- claude_desktop_config.example.json\n|  \\- cursor_mcp.example.json\n|- docs/\n|  |- ARCHITECTURE.md\n|  \\- TOOLS.md\n\\- src/\n   |- index.js                  # MCP stdio server entrypoint\n   |- cli.js                    # CLI local test\n   |- doctor.js                 # environment checker\n   |- config.js\n   |- types.js\n   |- services/\n   |  |- github.js              # GitHub API + raw file loader\n   |  |- analyzer.js            # local heuristic risk engine\n   |  |- gitlumen.js            # service orchestrator\n   |  \\- reportStore.js         # local report persistence\n   \\- utils/\n      |- githubUrl.js\n      |- ids.js\n      \\- text.js\n```\n\n---\n\n## Requirements\n\n- Node.js 20+\n- npm\n- Internet access to fetch metadata/files from GitHub\n\nCheck Node version:\n\n```bash\nnode -v\n```\n\nIf your version is Node 18 or below, upgrade to Node 20+.\n\n---\n\n## 1. Install Dependencies\n\nOpen the project directory:\n\n```bash\ncd gitlumen-mcp-server\n```\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\n---\n\n## 2. Optional Env Setup\n\nCopy env example:\n\n```bash\ncp .env.example .env\n```\n\nFill optional values:\n\n```bash\nGITHUB_TOKEN=ghp_xxx_or_fine_grained_token\nGITLUMEN_MCP_DATA_DIR=.gitlumen-mcp\nGITLUMEN_MAX_FILE_BYTES=120000\n```\n\nFor public repositories, `GITHUB_TOKEN` can be empty. A token is still recommended to avoid low GitHub rate limits.\n\n---\n\n## 3. Run Doctor\n\n```bash\nnpm run doctor\n```\n\nExpected output:\n\n```txt\nGitLumen MCP Doctor\n\n✅ Node version: v20.x.x\n✅ GITHUB_TOKEN configured: no (public unauthenticated mode)\n✅ Data directory: /path/to/gitlumen-mcp-server/.gitlumen-mcp\n✅ Reports directory writable: /path/to/gitlumen-mcp-server/.gitlumen-mcp/reports\n```\n\n---\n\n## 4. Test Screening via CLI\n\n### Offline test without GitHub network\n\n```bash\nnpm run sample\n```\n\nThis command generates a report from a local fixture so you can verify analyzer and report-store behavior without GitHub connectivity.\n\n### Screen a public repository\n\n```bash\nnpm run screen -- https://github.com/modelcontextprotocol/typescript-sdk quick\n```\n\n### Screen a public PR\n\n```bash\nnpm run screen -- https://github.com/modelcontextprotocol/typescript-sdk/pull/1 quick\n```\n\n### Available scopes\n\n```txt\nquick     = fastest, fewer files\nstandard  = balanced default\n```\n\nExamples:\n\n```bash\nnpm run screen -- https://github.com/owner/repo standard\nnpm run screen -- https://github.com/owner/repo quick main\n```\n\nAfter completion, CLI prints a markdown report and saves JSON to:\n\n```txt\n.gitlumen-mcp/reports/<reportId>.json\n```\n\n---\n\n## 5. Read Previous Reports\n\n```bash\nnpm run list -- 10\n```\n\nTake a `reportId`, then:\n\n```bash\nnpm run report -- glr_xxxxxxxxxxxxxxxx markdown\n```\n\nOr full JSON:\n\n```bash\nnpm run report -- glr_xxxxxxxxxxxxxxxx json\n```\n\n---\n\n## 6. Run as MCP Server\n\nThe MCP server uses stdio, so it is normally started by an MCP client instead of being run manually.\n\n```bash\nnode /ABSOLUTE/PATH/TO/gitlumen-mcp-server/src/index.js\n```\n\nTo debug MCP protocol, use MCP Inspector:\n\n```bash\nnpm run inspect\n```\n\nThen open the Inspector URL printed in terminal.\n\n### Optional: Run as Remote MCP HTTP Server (for VPS/PM2)\n\nThis project also includes a Streamable HTTP transport endpoint at `/mcp`.\n\nRun locally:\n\n```bash\nnpm run start:http\n```\n\nEnvironment variables:\n\n```bash\nPORT=3333\nHOST=0.0.0.0\nMCP_AUTH_TOKEN=replace_with_a_long_random_token\n```\n\n- `MCP_AUTH_TOKEN` is optional but strongly recommended for production.\n- When set, clients must send `Authorization: Bearer <token>`.\n\nHealth check:\n\n```bash\ncurl -s http://localhost:3333/health\n```\n\nProduction deployment guide:\n\n- PM2 example config: [examples/ecosystem.pm2.example.cjs](examples/ecosystem.pm2.example.cjs)\n\nClient configuration templates (Copilot / VS Code / Codex):\n\n- [docs/CLIENT_CONFIG_TEMPLATES.md](docs/CLIENT_CONFIG_TEMPLATES.md)\n- VS Code remote endpoint template: [examples/vscode_mcp.gitlumen.remote.example.json](examples/vscode_mcp.gitlumen.remote.example.json) (copy into `.vscode/mcp.json`, which is gitignored)\n\n---\n\n## 7. Install in Claude Desktop\n\nOpen Claude Desktop config.\n\nCommon location:\n\n### macOS\n\n```txt\n~/Library/Application Support/Claude/claude_desktop_config.json\n```\n\n### Windows\n\n```txt\n%APPDATA%\\Claude\\claude_desktop_config.json\n```\n\nAdd:\n\n```json\n{\n  \"mcpServers\": {\n    \"gitlumen\": {\n      \"command\": \"node\",\n      \"args\": [\"/ABSOLUTE/PATH/TO/gitlumen-mcp-server/src/index.js\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"optional_github_token_here\",\n        \"GITLUMEN_MCP_DATA_DIR\": \"/ABSOLUTE/PATH/TO/gitlumen-mcp-server/.gitlumen-mcp\"\n      }\n    }\n  }\n}\n```\n\nReplace `/ABSOLUTE/PATH/TO/...` with your real path.\n\nRestart Claude Desktop.\n\nExample prompt:\n\n```txt\nUse GitLumen to screen https://github.com/modelcontextprotocol/typescript-sdk with quick scope. Return the risk map and top findings.\n```\n\n---\n\n## 8. Install in Cursor\n\nCreate or edit Cursor MCP config (format may vary by Cursor version):\n\n```json\n{\n  \"mcpServers\": {\n    \"gitlumen\": {\n      \"command\": \"node\",\n      \"args\": [\"/ABSOLUTE/PATH/TO/gitlumen-mcp-server/src/index.js\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"optional_github_token_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor, then ask the agent to use GitLumen tools.\n\n---\n\n## Available MCP Tools\n\n### `screen_repository`\n\nScreen a repository or PR.\n\nInput:\n\n```json\n{\n  \"repoUrl\": \"https://github.com/owner/repo\",\n  \"scope\": \"standard\",\n  \"output\": \"compact\"\n}\n```\n\nFor PR:\n\n```json\n{\n  \"repoUrl\": \"https://github.com/owner/repo/pull/123\",\n  \"scope\": \"quick\",\n  \"output\": \"markdown\"\n}\n```\n\nOutput modes:\n\n```txt\ncompact   = concise JSON for agent replies\nmarkdown  = full markdown report\njson      = full JSON report\n```\n\n### `get_review_report`\n\nFetch a previous report by `reportId`.\n\n```json\n{\n  \"reportId\": \"glr_xxxxxxxxxxxxxxxx\",\n  \"output\": \"markdown\"\n}\n```\n\n### `list_review_reports`\n\nList local reports.\n\n```json\n{\n  \"limit\": 20\n}\n```\n\n### `get_repository_structure`\n\nGet repository/PR structure without generating a full risk report.\n\n```json\n{\n  \"repoUrl\": \"https://github.com/owner/repo\",\n  \"limit\": 300\n}\n```\n\n### `explain_gitlumen_mcp_flow`\n\nExplain Path 1 flow and how Path 2 Base MCP can be attached later.\n\n---\n\n## How the Analyzer Works\n\nThe local analyzer reads:\n\n- repository metadata\n- default branch\n- recursive tree\n- selected source/config files\n- PR metadata and changed files (for PR URLs)\n\nThen it generates signals:\n\n- language/framework detection\n- dependency surface\n- lockfile presence\n- lifecycle script risk\n- test presence\n- CI presence\n- Dockerfile/container risk\n- possible hardcoded secret patterns\n- dynamic code execution\n- command execution pattern\n- SQL interpolation pattern\n- GitHub Actions supply-chain pattern\n- merge-readiness estimate\n\nRisk categories:\n\n```txt\nsecurity\ndependencies\ntests\narchitecture\noperations\nmaintainability\n```\n\nSeverity:\n\n```txt\ncritical\nhigh\nmedium\nlow\ninfo\n```\n\n---\n\n## Example Compact Report Output\n\n```json\n{\n  \"reportId\": \"glr_abc123...\",\n  \"risk\": {\n    \"score\": 42,\n    \"level\": \"medium\",\n    \"mergeReadiness\": \"review_required\",\n    \"categoryScores\": {\n      \"security\": 24,\n      \"dependencies\": 13,\n      \"tests\": 24,\n      \"architecture\": 0,\n      \"operations\": 13,\n      \"maintainability\": 5\n    }\n  },\n  \"summary\": \"The repository/PR has medium risk signals...\",\n  \"findings\": [],\n  \"decisionQuestions\": [],\n  \"recommendations\": []\n}\n```\n\n---\n\n## Path 1 vs Path 2\n\n### Path 1 (this project)\n\n```txt\nRepo/PR intelligence\nRisk map\nReview chapters\nDecision questions\nReport retrieval\n```\n\n### Path 2 (future)\n\n```txt\nBase MCP get_wallets\nGitLumen quote endpoint\nGitLumen prepare endpoint\nBase MCP send_calls\nReview credit purchase\nReward claim\nReviewer reputation\n```\n\nThis project is intentionally standalone for Path 1 first. Later, Path 2 can read `reportId` and connect it with onchain payment/reward/reputation flows.\n\n---\n\n## Troubleshooting\n\n### `Unable to reach GitHub API` or `fetch failed`\n\nCheck internet connection, DNS, proxy/VPN, or retry. For offline verification:\n\n```bash\nnpm run sample\n```\n\n### `GitHub API 403 rate limit exceeded`\n\nAdd `GITHUB_TOKEN` in `.env` or MCP client config.\n\n### `Only github.com repositories are supported`\n\nThis prototype does not support GitLab/Bitbucket yet. Add a new adapter in `src/services/github.js` or create a separate service.\n\n### MCP client cannot see tools\n\nCheck:\n\n1. `args` path is absolute.\n2. `npm install` has been run.\n3. Node 20+ is installed.\n4. MCP client was restarted.\n5. Verify with `npm run inspect`.\n\n### Report is not saved\n\nRun:\n\n```bash\nnpm run doctor\n```\n\nEnsure `.gitlumen-mcp/reports` is writable.\n\n---\n\n## Important Files for Future Changes\n\n### Add a new detector\n\nEdit:\n\n```txt\nsrc/services/analyzer.js\n```\n\n### Change repository fetching behavior\n\nEdit:\n\n```txt\nsrc/services/github.js\n```\n\n### Replace local analyzer with hosted GitLumen API\n\nEdit:\n\n```txt\nsrc/services/gitlumen.js\n```\n\nPotential production direction:\n\n```txt\nscreen_repository MCP tool\n-> GitLumen hosted API /v1/screenings\n-> GitLumen Review Intelligence Engine\n-> reportId\n-> get_review_report MCP tool\n```\n\n---\n\n## Security Notes\n\n- Do not commit `.env`.\n- Do not hardcode GitHub tokens in publicly shared config.\n- For private repositories, use least-privilege fine-grained GitHub tokens.\n- Local reports may contain paths, findings, and snippet metadata. Store them securely for private repositories.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 10798,
  "sha": "dbd8ce90448c79c66dc7e4b274ea9e0b5aaf50e04e36ab017198d1c38e8b4f86",
  "repo_slug": "gitlumen-team/gitlumen-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gitlumen_team_gitlumen_mcp_98f3d9b0/readme"
}