repo_context_mcp
Provides read-only access to GitHub issues and repository code, including fetching issues with comments, listing issues, resolving issues from various inputs, and locating and reading relevant repository code with bounded output.
Adds PocketBase-aware database context tools for repositories using database migrations, including locating schema and migration files, estimating code impact of collection or field changes, and generating Mermaid ER diagrams from PocketBase schemas or migrations.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 commentsissues_list— list issues from the configured repositoryissue_lookup— resolve an issue from a number, title, description, or optional repository indexrepo_code— locate and read relevant repository code with bounded output
Optional profiles
Enable additional capabilities with REPO_CONTEXT_FEATURES.
Available profiles:
dbdb_contextdb_impactdb_mermaid
uiui_contextui_inventoryui_flow
historyrepo_file_historyrepo_diff
workflowrepo_guidancerepo_commands
Example:
REPO_CONTEXT_FEATURES=db,ui,history,workflowIf 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-browserREPO_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-idThe 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_changedThe 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 ciCopy the environment template:
cp .env.example .envConfigure 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=3000legacy 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=3000Generate the lookup and encryption keys independently, for example:
openssl rand -base64 32MCP 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/callbackREPO_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_ISSUERthe exact OAuth
subinREPO_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/revealBoth 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:
successnot_founddecrypt_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.mdThe 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 devProduction build:
npm run build
npm startDefault endpoints:
http://127.0.0.1:3000/mcp
http://127.0.0.1:3000/healthThe 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:githubThis 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 typecheckRun tests:
npm testBuild:
npm run buildrepo_code
repo_code supports two primary modes.
Search
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.mdCLAUDE.mdCONTRIBUTING.mdCursor rules
GitHub prompts
Claude commands
package.jsonscriptsMakefileTaskfilejustfile
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,query3The MCP benchmark endpoint can be changed with:
MCP_URL=http://127.0.0.1:3000/mcpSecurity
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
.envterminate 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.
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_idconsistently 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 CSeparate 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 roleGoals:
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_idnever 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 authorizationThis 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to list, search, and inspect issues on any public GitHub repository via natural language.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to search and inspect code repositories, manage issues and pull requests, and analyze user contributions.13MIT
- AlicenseAqualityCmaintenanceLets agents read a GitHub repository's live issues through read-only tools for listing, filtering, fetching details with comments and cross-references, searching, and exploring labels and milestones, with transparent pagination and provenance notes.5MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI clients such as Cursor to interact with GitHub repositories and perform issue listing, triage, health checks, prioritization, commenting, weekly digests, and release-note generation through purpose-built MCP tools.-