Skip to main content
Glama
repoprimer

RepoPrimer

Official
by repoprimer
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

RepoPrimer

English · 简体中文

Fresh project context for every coding agent.

RepoPrimer is a local-first, read-only project handoff layer. It combines the Markdown documentation you already maintain with live Git state, then exposes a compact startup brief to Codex, Claude, Cursor, and other MCP-compatible coding agents.

One repoprimer context call returns a bounded startup brief — project state, open tasks, accepted decisions, and live Git status. On this repository the compact brief measures about 3 KB (≈800 tokens, within the 6,000-character default budget) instead of a multi-turn cold-start exploration.

Status: early development. The npm package has not been published yet. The package commands below describe the intended public interface; use the source workflow while developing locally.

Why RepoPrimer?

Coding agents repeatedly spend time rediscovering the same facts: what the project does, what changed recently, what is in progress, and which decisions must not be revisited. General-purpose AI memory products solve a broader problem. RepoPrimer deliberately solves one narrow one:

Before an agent starts work, tell it where this repository is now.

RepoPrimer is designed to be:

  • Local-first: project files and the registry stay on your machine.

  • Read-only at runtime: MCP tools do not modify project files or Git state.

  • Markdown-native: no database, embeddings, or proprietary storage format.

  • Live: the handoff includes current Git state rather than only cached notes.

  • Small: four MCP tools, bounded responses, and no model API dependency.

  • Portable: one context source can serve multiple MCP-compatible agents.

Related MCP server: codex-project-context

How it works

existing Markdown docs + live Git state
                    |
                    v
           compact project context
                    |
                    v
      Codex / Claude / Cursor / other MCP clients

RepoPrimer does not try to remember every conversation and does not replace a knowledge base. It reads the project facts you choose to register and returns only the context an agent asks for.

MCP tools

The public MCP surface is intentionally limited to four read-only tools:

Tool

Purpose

list_projects

Discover registered projects and their basic health.

get_project_context

Build a compact handoff from project docs and live Git state.

search_project

Search registered project Markdown and return bounded snippets.

get_document

Read one allowed project document with an optional size limit.

Tools accept project identifiers, not arbitrary filesystem paths. RepoPrimer resolves and validates paths against the local registry before reading.

Quick start

Public package

The current release is a pre-release published under the alpha dist-tag, so install it with @alpha rather than @latest.

Initialize or register a project explicitly:

npx -y @repoprimer/mcp@alpha init
npx -y @repoprimer/mcp@alpha context

Add the MCP server to Codex:

codex mcp add repoprimer -- npx -y @repoprimer/mcp@alpha serve

For long-lived MCP configuration, pin an exact tested version instead of a moving dist-tag.

Local development

RepoPrimer requires Node.js 22 or 24.

git clone https://github.com/repoprimer/repoprimer.git
cd repoprimer
npm install
npm test
node dist/cli.js doctor
node dist/cli.js serve

Project documents

RepoPrimer works with existing Markdown conventions. A minimal project can use:

docs/
|-- PROJECT_STATE.md
|-- TASKS.md
`-- DECISIONS.md

Projects are not required to adopt those exact filenames. A project config can map existing files such as AGENTS.md, CLAUDE.md, ADRs, or a Memory Bank into the document set that RepoPrimer may read.

Generated context is assembled on demand. It is not another source of truth.

Read-only and privacy boundaries

The MCP server:

  • reads only registered projects and configured documents;

  • reads Git metadata through bounded, non-mutating commands;

  • does not write project files or alter the working tree;

  • does not call model APIs, upload content, or collect telemetry;

  • does not require a background database or cloud account.

The CLI has a separate, explicit setup boundary: commands such as init, add, and remove may update RepoPrimer configuration or its user-level registry. They are never invoked implicitly by an MCP read tool.

Scope

RepoPrimer v0.1 focuses on project discovery, live context, document retrieval, and text search. The following are intentionally out of scope:

  • conversation capture and autonomous memory writes;

  • embeddings, vector databases, or knowledge graphs;

  • cloud sync, accounts, teams, or a hosted service;

  • a web UI or IDE-specific extension;

  • source-code indexing or autonomous repository analysis;

  • model inference, API keys, or telemetry.

See Architecture, Decisions, and Tasks for the current design and implementation status.

FAQ

Why not just let the agent explore the repository itself?

It can, and RepoPrimer does not prevent that. The difference is the first turn: exploration is re-run in every session by every agent, varies between runs, and spends context-window tokens on rediscovery. RepoPrimer makes the first turn deterministic and bounded — every agent starts from the same brief within a fixed character budget, and deeper reads remain available through get_document and search_project.

How does this relate to CLAUDE.md or AGENTS.md?

They are complementary. Those files hold durable instructions for one repository, read by the agents that support them. RepoPrimer adds what a static file cannot: live Git state, a multi-project registry, bounded responses, and one context source shared by every MCP-compatible agent. A project config can map CLAUDE.md or AGENTS.md into the document set RepoPrimer serves.

Contributing

RepoPrimer is being prepared as an independent open-source project. Please read CONTRIBUTING.md before proposing a change and follow the Code of Conduct. Security issues should follow SECURITY.md, not the public issue tracker.

English is the canonical language for repository metadata and project governance. The complete Simplified Chinese README provides a secondary onboarding path, and issues or feedback in Chinese are welcome.

License

Licensed under the Apache License 2.0.

Available Tools

4 tools
get_documentRead a configured documentA
Read-onlyIdempotent

Read one configured Markdown document by id. Arbitrary file paths are not accepted.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesDocument id returned in get_project_context.
projectNoRegistered project id. Omit to use the default.
maxCharsNo

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description aligns with annotations (readOnlyHint, idempotentHint, non-destructive) and adds the constraint that arbitrary file paths are not accepted, providing useful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences front-loading the main purpose and adding a key constraint. No superfluous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (1 required param, no output schema, safe behavior via annotations), the description covers the core functionality and a notable constraint. Lacks return format info, but the simplicity makes it nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 67% schema coverage, the tool description adds no parameter details beyond the schema. It does not explain the purpose of project or maxChars, relying on the schema descriptions which are adequate but not enhanced.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Read), the resource (configured Markdown document), and selection method (by id). It also clarifies what is not accepted (arbitrary file paths), distinguishing it from potential sibling tools that might accept paths.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus siblings. It implies the need for an id from get_project_context (noted in schema, not description), and adds a constraint on file paths, but lacks explicit when-not or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_project_contextGet fresh project contextA
Read-onlyIdempotent

Build a fresh project handoff from live Git status and configured Markdown. Compact mode is the default startup view; standard mode includes longer excerpts.

ParametersJSON Schema
NameRequiredDescriptionDefault
detailNo
projectNoRegistered project id. Omit to use the default.
maxCharsNo

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds value by specifying source (live Git status, Markdown) and default view (compact), but could mention response scope or freshness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences with front-loaded purpose, no unnecessary words, earning its conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 params, no output schema, and comprehensive annotations, the description provides adequate context for a read-only tool. Could add output format hint to raise further.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 3 params with 33% description coverage. Description explains compact vs standard (mapped to detail parameter) and hints at default, but lacks explicit mapping for maxChars and project beyond schema info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'Build' and resource 'fresh project handoff from live Git status and configured Markdown', clearly distinguishing from siblings like list_projects, search_project, get_document.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description gives context for compact vs standard mode but does not explicitly state when to use this tool over alternatives like list_projects or search_project.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsList registered projectsA
Read-onlyIdempotent

List registered RepoPrimer projects and their compact document/task coverage. Call this first in a new session. Set refresh=true to rescan configured discovery roots.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum projects to return.
refreshNoRefresh registry and opt-in discovery roots.
verboseNoInclude the document catalog for each project.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false. Description adds that it returns compact coverage info and that refresh rescans roots. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with purpose and usage guidance. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity, no output schema, and simple parameters, the description adequately covers key usage. Could mention idempotency or safe re-call, but not necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3. Description adds context for the refresh parameter beyond the schema description, explaining its effect on discovery roots.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists registered projects and their document/task coverage. It distinguishes from siblings by being the initial session call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to call first in a new session and explains when to use refresh=true. No explicit when-not-to or alternatives, but sufficient for a simple listing tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_projectSearch project contextA
Read-onlyIdempotent

Search configured Markdown by heading and section. Pass project="*" to search all registered projects with a global result limit.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
projectNoRegistered project id, or "*" for all projects.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond annotations, such as searching by heading/section and a global result limit. Annotations already indicate read-only and idempotent behavior, so the description does not need to repeat that. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. Front-loaded with the core purpose and a practical usage tip. Very concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the annotations and schema (3 params, no output schema), the description covers the core functionality and special behavior. However, it could be more complete by explaining what 'configured Markdown' means and how results are returned, especially when compared to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds meaning beyond the input schema: explains that query searches headings/sections, project can be '*' for all projects, and limit is a global result limit. Schema coverage is only 33% (only project described), so the description compensates effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches configured Markdown by heading and section, which distinguishes it from sibling tools like list_projects (lists) and get_project_context (retrieves full context).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance for the special case of project='*' to search all projects, implying when to use this tool for cross-project searches. However, it does not explicitly state when not to use it or mention alternatives like get_project_context or get_document.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv0.1.0-alpha.0
    • First observedget_document
    • First observedget_project_context
    • First observedlist_projects
    • First observedsearch_project
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: listing projects, building context, searching documents, and reading a specific document. No overlapping functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (list_projects, get_project_context, search_project, get_document) with underscores, making predictions easy.

Tool Count4/5

With 4 tools, the set is slightly small but covers the core query operations for project and document management. It avoids unnecessary bloat.

Completeness4/5

The surface covers listing, searching, reading, and context building. Missing write operations (create/update/delete) but appears intentionally read-only, so no significant gaps for its purpose.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers