GitLumen MCP

What GitLumen MCP MCP server does

GitLumen MCP MCP server exposes GitHub repository and pull request review analysis through the Model Context Protocol. An MCP client can submit a public repository URL or a URL containing /pull/<number>, choose a scan scope, and request compact JSON, full JSON, or Markdown output.

The analyzer produces a risk score, severity level, category scores, findings, review chapters, decision questions, recommended next actions, and a merge-readiness signal. Risk categories include security, dependencies, tests, architecture, operations, and maintainability. Findings can cover areas such as possible hardcoded secrets, dynamic code execution, command execution, SQL interpolation, container configuration, and GitHub Actions supply-chain concerns.

Reports are saved locally as JSON files under the configured data directory, allowing later retrieval by report ID. The project also includes a CLI for testing scans and reading saved reports without connecting an MCP client.

How it works

GitLumen MCP MCP server fetches repository metadata, the default branch, a recursive file tree, and selected source or configuration files from GitHub. For pull request URLs, it also reads PR metadata and changed files. The local analyzer then detects languages and frameworks, examines dependency and lockfile information, checks for tests and CI, and generates heuristic risk signals.

Source code stays within the local analysis flow rather than being sent to an external LLM. The quick scope examines fewer files for faster results, while standard provides the balanced default. A local fixture can be used to test analyzer and report-storage behavior without GitHub network access.

Setup and configuration

The project requires Node.js 20 or newer, npm, and internet access when fetching GitHub metadata or files. Install dependencies with npm install, then run the included doctor command to check the Node version, data directory, and report directory.

Public repositories can be scanned without a GitHub token, although GITHUB_TOKEN is available for higher API limits and private repositories when its permissions allow access. GITLUMEN_MCP_DATA_DIR changes where reports are stored, and GITLUMEN_MAX_FILE_BYTES limits the size of files considered by the analyzer.

The normal MCP entry point uses stdio and is started by an MCP client. The project also provides a Streamable HTTP endpoint at /mcp, with PORT, HOST, and optional MCP_AUTH_TOKEN settings. When HTTP authentication is enabled, clients must send a bearer token. A /health endpoint is available for checks.

Tools and capabilities

The available MCP tools are:

• screen_repository scans a repository or pull request and selects scope and output format.
• get_review_report retrieves a previously saved report by ID.
• list_review_reports lists locally stored reports with a requested limit.
• get_repository_structure returns repository or PR structure without creating a full risk report.
• explain_gitlumen_mcp_flow explains the current repository-intelligence path and how a future Base MCP path could be attached.

The CLI supports repository scans, pull request scans, report listing, and report retrieval in Markdown or JSON. It also supports an offline sample command and MCP debugging through MCP Inspector.

Limitations and notes

Analysis is heuristic and should be treated as review input rather than proof that a repository is safe or ready to merge. GitHub access is required for live scans, and unauthenticated requests may encounter lower rate limits. Private repository access depends on the configured token and its scope.

The current project does not execute onchain transactions and does not use Base MCP send_calls. The documented Base MCP connection is a future extension after the repository-intelligence flow is in place.