Skip to main content
Glama

repo_context_mcp

Fast, read-only MCP server for GitHub issues and repository code with bounded context and HEAD-consistent reads.

repo_context_mcp is designed to give AI clients useful repository context without encouraging broad, expensive repository exploration.

The default tool surface is intentionally small. Specialized capabilities can be enabled as optional profiles.

Features

Core tools

  • issue_get — fetch one GitHub issue with comments

  • issues_list — list issues from the configured repository

  • issue_lookup — resolve an issue from a number, title, description, or optional repository index

  • repo_code — locate and read relevant repository code with bounded output

Optional profiles

Enable additional capabilities with REPO_CONTEXT_FEATURES.

Available profiles:

  • db

    • db_context

    • db_impact

    • db_mermaid

  • ui

    • ui_context

    • ui_inventory

    • ui_flow

  • history

    • repo_file_history

    • repo_diff

  • workflow

    • repo_guidance

    • repo_commands

Example:

REPO_CONTEXT_FEATURES=db,ui,history,workflow

If the variable is empty or omitted, the optional capability profiles are not exposed. The core tools remain available. page_render is configured separately and is not part of REPO_CONTEXT_FEATURES.

Optional page rendering

page_render renders a route from an explicitly configured, already-running application. It is separate from the static ui profile and can be enabled in either legacy or OAuth mode.

Page rendering is disabled unless both of these values are configured:

REPO_CONTEXT_RENDER_ORIGIN=http://127.0.0.1:5173
REPO_CONTEXT_RENDER_BROWSER_EXECUTABLE=/absolute/path/to/chromium-compatible-browser

REPO_CONTEXT_RENDER_ORIGIN must be an exact HTTP(S) origin containing only the scheme, host, and optional port.

The browser executable must already exist. Repo Context MCP does not discover, download, or install a browser, and it does not install dependencies or start the target application.

In legacy mode, the render target is bound to the configured legacy repository. Do not set REPO_CONTEXT_RENDER_REPOSITORY_ID.

In OAuth mode, rendering must additionally be bound to exactly one repository connection:

REPO_CONTEXT_RENDER_REPOSITORY_ID=connection-id

The binding is connection-scoped. A principal must still be authorized for the requested repository through normal RepositoryToolAccess; knowing a repository connection ID is not sufficient authorization.

The renderer uses a fresh browser context and:

  • renders only application-local routes below the configured origin,

  • blocks cross-origin HTTP(S) resource requests,

  • blocks cross-origin WebSocket connections,

  • blocks top-level navigation away from the configured origin,

  • disables downloads and service workers,

  • bounds extracted text, visible interactive elements, and screenshot size,

  • always closes the browser after the render.

page_render returns structured rendered-page metadata as text and, when within the configured size limit, a JPEG screenshot as separate MCP image content.

Related MCP server: GitHub Activity MCP Server

Design goals

Small tool surface

The default configuration exposes only the tools needed for normal issue analysis and repository code retrieval.

This reduces unnecessary tool selection and repeated repository exploration.

Bounded context

repo_code applies limits to:

  • search queries

  • candidate files

  • lines returned per file

  • total response size

The goal is to return enough code for reasoning without dumping large parts of the repository into model context.

HEAD-consistent reads

Repository code is read against a concrete Git commit SHA.

The server resolves the configured branch to its current HEAD and uses that snapshot for tree discovery and file reads.

This prevents a single tool result from accidentally combining files from different commits if the branch changes during analysis.

Repository drift detection

repo_code tracks repository HEAD during a model response when the MCP host provides a request identifier.

If the branch changes between productive repo_code calls, the tool can return:

mode=repository_changed

The client should then discard conclusions derived from the previous HEAD and restart repository analysis against the new snapshot.

The per-response call budget is best-effort and is only enforced when the host supplies a usable request identifier.

Read-only access

The current server does not modify the configured repository.

GitHub App permissions should therefore be limited to read-only access.

Requirements

  • Node.js

  • a GitHub App installed on the repository you want to expose

  • GitHub App access to:

    • repository contents: read-only

    • issues: read-only

  • a GitHub App private key stored outside this repository

Setup

Clone the repository and install dependencies:

git clone https://github.com/JakubManikowski1/repo_context_mcp.git
cd repo_context_mcp
npm ci

Copy the environment template:

cp .env.example .env

Configure the server explicitly for one of two modes.

Legacy / single-repository mode

Legacy mode preserves the original self-hosted setup. One GitHub App installation and one repository are configured globally.

REPO_CONTEXT_AUTH_MODE=legacy

GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=/absolute/path/to/github-app.pem

GITHUB_INSTALLATION_ID=12345678
GITHUB_OWNER=your-github-user-or-org
GITHUB_REPO=your-repository
GITHUB_BRANCH=main

PORT=3000

legacy is currently the default when REPO_CONTEXT_AUTH_MODE is not set.

Optional capability profiles (db, ui, history, workflow) are legacy-only.

OAuth / multi-user mode

OAuth mode does not use a globally configured repository as proof of repository access. Repository access is derived from the verified MCP principal and that principal's active encrypted repository connections.

REPO_CONTEXT_AUTH_MODE=oauth

REPO_CONTEXT_MCP_URL=https://mcp.example.com/mcp

REPO_CONTEXT_OAUTH_ISSUER=https://auth.example.com/
REPO_CONTEXT_OAUTH_AUTHORIZATION_ENDPOINT=https://auth.example.com/authorize
REPO_CONTEXT_OAUTH_TOKEN_ENDPOINT=https://auth.example.com/oauth/token
REPO_CONTEXT_OAUTH_JWKS_URL=https://auth.example.com/.well-known/jwks.json

REPO_CONTEXT_CONNECTION_DB_PATH=/absolute/path/to/repository-connections.sqlite

REPO_CONTEXT_USER_LOOKUP_KEY=<base64-32-byte-key>
REPO_CONTEXT_CONNECTION_ENCRYPTION_KEY=<different-base64-32-byte-key>

GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=/absolute/path/to/github-app.pem

REPO_CONTEXT_GITHUB_APP_SLUG=your-github-app-slug
REPO_CONTEXT_GITHUB_CLIENT_ID=Iv1.example
REPO_CONTEXT_GITHUB_CLIENT_SECRET=<github-app-client-secret>

# Optional operator sensitive-data access.
# These three values must be configured together.
REPO_CONTEXT_OPERATOR_ID=primary-operator
REPO_CONTEXT_OPERATOR_SUBJECT=<exact-oauth-sub>
REPO_CONTEXT_OPERATOR_TOTP_SECRET=<base32-totp-secret>

PORT=3000

Generate the lookup and encryption keys independently, for example:

openssl rand -base64 32

MCP OAuth and GitHub OAuth serve different purposes:

  • MCP OAuth authenticates the MCP user.

  • GitHub OAuth is temporary and is used during repository connection.

  • Repository access after connection uses the GitHub App installation.

  • GitHub user access and refresh tokens are not persisted as repository connection data.

When GitHub connect is enabled, configure the GitHub App with:

Setup URL:
https://mcp.example.com/connect/github/setup

Callback URL:
https://mcp.example.com/connect/github/callback

REPO_CONTEXT_GITHUB_APP_SLUG, REPO_CONTEXT_GITHUB_CLIENT_ID, and REPO_CONTEXT_GITHUB_CLIENT_SECRET must either all be configured or all be absent. Partial configuration fails closed.

Optional operator sensitive-data access

Operator reveal is disabled unless all three operator variables are configured:

REPO_CONTEXT_OPERATOR_ID=primary-operator
REPO_CONTEXT_OPERATOR_SUBJECT=<exact-oauth-sub>
REPO_CONTEXT_OPERATOR_TOTP_SECRET=<base32-totp-secret>

REPO_CONTEXT_OPERATOR_ID is an operator label written to the reveal audit. It is not an authentication credential.

The operator identity is bound to:

  • the exact OAuth issuer from REPO_CONTEXT_OAUTH_ISSUER

  • the exact OAuth sub in REPO_CONTEXT_OPERATOR_SUBJECT

The TOTP secret must be valid Base32 and decode to at least 20 bytes.

Operator access is OAuth-only. Supplying any operator configuration in legacy mode fails closed. Supplying only part of the operator configuration also fails closed.

The flow has two HTTP endpoints:

POST /operator/session
POST /operator/reveal

Both require the normal OAuth bearer token of the configured operator.

POST /operator/session performs the TOTP step-up:

{
  "totp_code": "123456"
}

A successful response contains a short-lived privileged session token:

{
  "session_token": "ops1.<opaque-token>",
  "expires_at": "..."
}

The privileged session:

  • expires after 5 minutes

  • is stored only in process memory

  • is invalidated by a process restart

  • authorizes exactly one reveal attempt

  • cannot be used by another OAuth principal

POST /operator/reveal requires the OAuth bearer token, privileged session, an exact repository connection ID, and an explicit reason:

{
  "session_token": "ops1.<opaque-token>",
  "connection_id": "<exact-connection-id>",
  "reason": "Investigate support case 123"
}

There is intentionally no operator repository list, search, or reveal-all endpoint.

Reveal responses are sent with Cache-Control: no-store. The internal pseudonymous userLookup is not returned by the HTTP endpoint.

Valid reveal attempts are audited with one of:

  • success

  • not_found

  • decrypt_failed

The audit table is append-only through application code and SQLite triggers. This prevents ordinary updates and deletes through the application database connection, but it is not tamper-proof against an administrator with direct access to the SQLite files.

Invalid TOTP attempts are throttled after 5 failures in a rolling 60-second window. TOTP replay tracking and privileged sessions are process-local, so both reset when the process restarts.

Do not configure optional capability profiles in OAuth mode.

Keep the GitHub App private key outside the repository.

Do not commit .env, private keys, OAuth client secrets, connection encryption keys, or user lookup keys.

Optional issue index

issue_lookup works with GitHub Issues without any additional configuration.

A repository-local issue index can optionally be configured:

ISSUE_INDEX_PATH=Backlog.md

The index is used only to help resolve references to issue numbers.

GitHub Issues remain the source of truth.

If the index is missing, unreadable, or cannot confidently resolve the query, issue_lookup falls back to GitHub issue search.

Run locally

Development mode:

npm run dev

Production build:

npm run build
npm start

Default endpoints:

http://127.0.0.1:3000/mcp
http://127.0.0.1:3000/health

The MCP endpoint must be reachable by the MCP client you want to connect.

For remote clients, expose the server through an HTTPS endpoint using infrastructure appropriate for your environment.

Verify GitHub access

Run:

npm run check:github

This checks:

  • GitHub App authentication

  • configured repository access

  • configured branch

  • current HEAD

  • issue read access

The command does not print credentials or private keys.

Development

Type-check:

npm run typecheck

Run tests:

npm test

Build:

npm run build

repo_code

repo_code supports two primary modes.

Use queries when exact repository-relative paths are not known.

Example:

{
  "queries": [
    "createUser",
    "userService",
    "user validation"
  ]
}

The tool uses repository-tree discovery and bounded search to identify relevant files and return compact source excerpts.

Fetch

Use paths only when exact repository-relative paths are already known.

Example:

{
  "paths": [
    "src/services/userService.ts"
  ],
  "focusQueries": [
    "createUser"
  ]
}

For large files, focusQueries can extract relevant regions and, where possible, expand complete function or callback definitions.

Do not provide both queries and paths in the same call.

Database profile

The db profile is currently oriented toward repositories using database migrations and includes additional PocketBase-aware behavior.

It can:

  • locate schema and migration files

  • gather database context

  • estimate code impact of collection or field changes

  • generate Mermaid ER diagrams from PocketBase schemas or migrations

Migration-derived diagrams are best-effort and should be verified against the actual schema.

UI analysis profile

The ui profile analyzes frontend source code.

It can:

  • locate files related to a route

  • inventory headings, buttons, links, form controls, labels, and states

  • identify navigation, API calls, clicks, form submissions, overlays, and guards

This profile analyzes repository UI code.

Runtime page rendering is intentionally separate from static UI analysis. When page_render is configured, it can inspect the current rendered state of an already-running application and return a bounded screenshot plus rendered DOM context.

This does not turn the repository tools into an interactive MCP App UI inside the chat client.

Workflow profile

The workflow profile discovers repository-specific development instructions and commands.

It can inspect files such as:

  • AGENTS.md

  • CLAUDE.md

  • CONTRIBUTING.md

  • Cursor rules

  • GitHub prompts

  • Claude commands

  • package.json scripts

  • Makefile

  • Taskfile

  • justfile

These tools are intended for tasks where repository-specific procedures materially affect implementation.

History profile

The history profile provides:

  • recent commits affecting a file

  • diffs between Git refs

  • changed files and commit metadata

  • bounded patches

Use it for regression analysis, investigating why code exists, or comparing implementations.

Benchmarks

The scripts/ directory contains development benchmarks used while designing the retrieval strategy.

Most benchmark inputs can be customized with:

BENCHMARK_QUERIES=query1,query2,query3

The MCP benchmark endpoint can be changed with:

MCP_URL=http://127.0.0.1:3000/mcp

Security

Recommended deployment rules:

  • use a dedicated GitHub App

  • grant only required repositories

  • use read-only repository permissions

  • keep the private key outside the project directory

  • never commit .env

  • terminate public access through HTTPS

  • protect externally reachable MCP endpoints according to your deployment environment

  • keep operator TOTP secrets outside the repository

  • enable operator reveal only when operationally required

  • treat repository reveal responses as sensitive data

  • protect the repository connection SQLite database and its WAL/SHM files

The MCP tool set is designed to be read-only.

The optional operator reveal HTTP flow is deliberately separate from the MCP tool surface and can decrypt stored repository connection metadata after OAuth identity verification and a fresh TOTP step-up.

License

Apache License 2.0.

See LICENSE and NOTICE.

Roadmap

Current focus: Phase 1 — Multi-repository context.

The project is evolving from a single-repository, read-only context server into a repository-aware development and review assistant.

The roadmap is intentionally incremental. Each phase should remain useful on its own and should avoid introducing infrastructure that is not yet required by the active use case.

Phase 1 — Multi-repository context

Run a single MCP server behind a single endpoint and allow the client to choose which configured repository a tool call should operate on.

Goals:

  • support multiple repositories from one MCP instance,

  • expose available repositories through repositories_list,

  • use an opaque repository_id consistently across all repository-bound tools,

  • keep repository selection request-scoped rather than storing global mutable active-repository state,

  • preserve repository isolation in caches, budgets, and request context,

  • support repository-specific optional capabilities such as page-render targets,

  • retain simple single-user operation during this phase.

The intended interaction is:

ChatGPT
    ↓
one Repo Context MCP
    ↓
repository selection
    ├── repository A
    ├── repository B
    └── repository C

Separate MCP deployments per repository are considered a transitional configuration rather than the target architecture.

Phase 2 — Interactive ChatGPT views

Once repository selection is stable, improve the user experience with interactive views inside ChatGPT.

Goals:

  • provide a repository picker,

  • expose repository and route context visually where useful,

  • integrate static UI analysis with runtime page rendering,

  • make UI review workflows usable by non-developers,

  • keep text and tool interfaces available as a fallback when rich UI is unavailable.

The UI must remain a client convenience. Repository authorization and tool behavior must never depend solely on client-side state.

Phase 3 — Bounded GitHub write operations

After the read and review workflow is mature, introduce narrowly scoped write capabilities.

The first planned write workflow is GitHub issue creation.

Goals:

  • create issues from repository or UI review context,

  • include evidence such as relevant routes, files, and analysis summaries,

  • require an explicit target repository,

  • clearly distinguish read-only tools from write tools,

  • mark MCP tool annotations accurately,

  • keep write operations narrow and auditable rather than adding generic repository mutation.

Source-code modification is not part of this phase.

Phase 4 — Multi-user authentication and authorization

Authentication and fine-grained repository authorization are deliberately deferred until the repository-selection, UI, and review workflows are established.

The target model separates:

RepositoryConnection
    = how the service technically accesses a repository

RepositoryAccess
    = who is allowed to use that connection and with what role

Goals:

  • authenticate each MCP user,

  • identify users through a stable external identity rather than GitHub account ownership,

  • allow users without GitHub accounts to receive repository access,

  • authorize every repository-bound request independently,

  • support grants and revocation,

  • support repository-specific roles such as viewer, reviewer, and administrator,

  • ensure knowledge of a repository_id never grants access by itself,

  • keep provider credentials and repository connection details server-side.

This phase should make the MCP suitable for broader multi-user deployment without changing the repository-facing workflow introduced in earlier phases.

Planned sequencing

multi-repository selection
        ↓
interactive ChatGPT views
        ↓
bounded GitHub issue creation
        ↓
multi-user authentication and authorization

This order is intentional. The immediate goal is to validate repository and UI workflows with a minimal operational model before adding multi-user identity and access-management complexity.

Design principles

Across all phases:

  • prefer one MCP service over repository-specific MCP deployments,

  • keep repository choice explicit and request-scoped,

  • fail closed when repository access cannot be established,

  • treat UI state as convenience rather than authorization,

  • keep read and write capabilities clearly separated,

  • add write operations individually rather than introducing generic mutation,

  • preserve compatibility with simple local and private deployments where practical,

  • avoid coupling repository access to a user's personal GitHub account unless the deployment explicitly requires it.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers