Prelude

What prelude MCP server does

The prelude MCP server exposes a repository's committed project memory to AI agents over MCP. Prelude first scans a codebase and writes structured files under .context/, then serves that information to later sessions. The context can describe the project's languages and tooling, architecture, constraints, design decisions, module notes, import relationships, tests, and project history.

The code map is intended to answer questions that source search alone cannot: which files depend on a module, which tests import it, what decisions constrain a change, and what a previous session recorded. The data remains in the repository, so it can be reviewed and committed with the code.

How it works

Prelude uses local regex heuristics for TypeScript, JavaScript, Python, Go, and Rust. It does not use embeddings, make network calls, or require a hosted service. Its map records modules, exports, import relationships, importer counts, hub files, and related tests. The locate command ranks files for a task phrase and explains the matches, while also attaching relevant tests, decisions, and impact information.

A project context contains files such as project.json, stack.json, architecture.json, constraints.json, decisions.json, map.json, and changelog.md. A .prelude/ directory tracks which values were inferred and which were edited manually. Updates refresh inferred fields while preserving user-authored values. The generated context can also be rendered as compact text or exported to CLAUDE.md and AGENTS.md.

Setup and configuration

Use Node.js 20.19 or later. From a project directory, initialize the context with npx prelude-context init, or install the package globally with npm install -g prelude-context and run prelude init. Commit .context/ to share the project memory, and ignore .context/*.session.json.

For MCP, run the server over stdio with npx -y prelude-context serve. A client can pass --root /path/to/project when the server is launched outside the target project directory. The repository must already have a .context/ directory for the server to provide initialized project context.

Tools and capabilities

The prelude MCP server connects an agent to local, structured codebase context rather than to a remote code search service. Supported workflows include:

• Reading the project context and code map through MCP.
• Recording architecture decisions with prelude_record_decision.
• Preserving module-specific notes with prelude_annotate_module.
• Finding likely files for a task through Prelude's ranked locate workflow.
• Supplying context to Claude Code, Cursor, Codex, Claude Desktop, or other MCP clients.

The same .context/ files can be used by the CLI, generated Markdown files, and MCP access.

Limitations and notes

Results are based on deterministic term matching and regex heuristics, not semantic embeddings or AST parsing. The project documentation describes locate benchmarks as in-sample measurements, so they should not be treated as a guarantee for a particular repository. A newly initialized project has its import graph and test relationships, but decisions and module notes remain empty until people or agents record them.

Prelude is local and static: it does not provide hosted indexing or network-backed retrieval. It supports the languages listed above, and its MCP transport is stdio. Keep the generated context synchronized with the code; prelude diff --check can detect when committed context has drifted.