代码库上下文 MCP 服务器

Engram MCP

A graph-aware codebase context server for AI coding agents. Engram is a Model Context Protocol server, written in Rust, that gives any MCP-capable agent (Claude Desktop, Claude Code, Codex, your own SDK client) a persistent, evidence-backed picture of a real codebase: a typed knowledge graph, full-text and semantic search, git temporal intelligence, a revert-derived anti-pattern index, per-file coding conventions, a ten-gate pre-commit review, a CLAUDE.md generator, a diff narrator, and an Autonomous Decision Protocol for agents that want to edit without asking every time.

• Deterministic by default. Core tools — graph traversal, search, temporal coupling, pre-commit review, immune checks, secret scanning, CLAUDE.md generation — never call an LLM. The server runs fully offline.
• Language-aware. Tree-sitter parsers for Rust, Python, Go, Java, C, C++, C#, VB.NET, TypeScript, and JavaScript; custom extractors for ASP.NET WebForms (ASPX / ASCX / Master), Classic ASP, T-SQL, SSRS, Crystal Reports, Google Maps, and Esri ArcGIS JS.
• Per-project, per-agent. Each project has its own index; every query is scoped by project_id. No cross-project leakage.
• Append-only and crash-safe. Generation-based indexing, Blake3 fingerprints, Redb-backed durable checkpoints, integrity sentinels with auto-repair, and a multi-client dispatcher that lets several agents share one daemon without races.

What Engram gives an agent

Capabilities

Each capability is independently usable. Every tool is scoped by project_id and every file path is validated against configured allowed_roots.

The sections below are ordered by how much they change an agent's behaviour compared to running without Engram — the top ones are the reason Engram exists; the bottom ones are operational surface.

Pre-commit review (pre_commit_review)

Eleven deterministic gates run over a unified diff (raw text, staged, unstaged, head, or a .patch path) and emit severity-ranked findings with concrete evidence and fix suggestions. No LLM calls. Typical run: under two seconds.

Every finding carries a stable ID (for run-to-run tracking in CI), specific line numbers, diff-context snippets, evidence lines (graph data, revert hashes, coupling weights, convention statistics), an actionable fix suggestion, and a Next tool recommendation. Output is either rendered Markdown with a single 🟢 / 🟡 / 🔴 verdict badge, or a stable JSON payload (output_json: true) for CI pipelines.

Immune system (revert-derived anti-patterns)

Every reverted commit in the git history is treated as a lesson. The immune actor harvests each revert, extracts the pattern that was undone, and indexes it as an anti-pattern with the reverting commit hash attached as evidence.

This is how an agent stops re-introducing the DeleteAllOnSubmit that was reverted three months ago: immune_check flags the proposed code with the revert hash, and pre_commit_review's immune gate blocks the commit automatically.

Autonomous Decision Protocol

Eight-gate mandatory pipeline for autonomous edits:

1. Extraction confidence — do we actually understand the method?
2. Trace certainty — are the call / state traces verified?
3. Safety policy — does the policy allow this class of edit?
4. Retrieval quality — did search return relevant context?
5. Blast radius — is the change contained?
6. Anti-pattern clearance — does it avoid indexed reverts?
7. Runtime evidence — does observed behaviour support the edit?
8. Evidence sufficiency — is there enough signal to commit?

Three verdicts: allow / deny / abstain. Progressive rollout — shadow → advisory → guarded → autonomous — with an emergency kill-switch that forces every verdict to deny. Every decision is written to an immutable JSON audit trail with inputs, gate outputs, and final verdict for offline replay.

This is the surface an agent framework drives when it wants to edit code without a human in every loop.

Knowledge graph (~40 edge kinds)

Typed graph across seven concern domains:

• Code structure — Calls, Contains, Imports, Dependency
• Data access — QueriesTable, HasColumn, ForeignKey, CallsStoredProcedure, StoredProcReadsTable
• State flow — ReadsState, WritesState, StateAffinity
• UI wiring — ContainsUi, DataBinding, TriggersPostback, ManipulatesDom, FillsRegion
• Web surface — ExposesWebService, ExposesHttpHandler, ExposesWcfService
• Change coupling — TemporalCoupling, CoOccurrence
• Runtime evidence — ObservedRuntimeControl, ObservedRuntimeSql

Query by type / name / file. BFS traversal up to 12 hops with edge-kind filters. compute_blast_radius returns a 1–10 risk score with seam-candidate identification; impact_analysis estimates what breaks if a file or symbol changes; detect_design_patterns surfaces Repository / Factory / Singleton / Observer structures. Runtime-evidence edges let you cross-check static extraction against actual observed behaviour.

Legacy modernization engine

End-to-end migration tooling for ASP.NET WebForms and Classic ASP codebases:

• Control mapping catalog (WebForms → Blazor / React / Angular)
• Scaffold generation with real business logic pulled from graph edges (not invented)
• Database-strategy advisor; per-key state-migration recommendations
• Characterization test generation (NUnit / xUnit / MSTest)
• Strangler-fig infrastructure (YARP + feature flags + Polly)
• Runtime instrumentation code generation
• Topologically-ordered migration waves via Kahn sort
• analyze_full_project_migration — a single call that produces a comprehensive per-file migration report with a cross-cutting summary, suitable for handing to a team or a migration agent

Git temporal intelligence

• index_git_history — libgit2-backed commit-graph indexing
• analyze_temporal_couplings — files that frequently change together
• search_history — structured search over commit messages and diffs
• The immune system (above) is built on top of this layer

Temporal coupling is the quiet superpower: it surfaces files that aren't related by any import or call edge but are consistently changed in the same commit — the kind of hidden coupling that turns a one-file edit into a four-file regression.

Hybrid search

Full-text (Tantivy) + vector (LanceDB) with Reciprocal Rank Fusion, Maximal Marginal Relevance diversity, namespace / path / language filters, and content preview. Standalone vector search with 3× oversampling. Multi-language structured stacktrace parser with frame-boosted search. Graph-aware search that expands hits along configurable edge kinds so you get the method PLUS its callers, callees, or temporal-coupling partners in one call.

Per-method access layer

Precise per-method context retrieval so an agent can touch one method without re-reading an entire file:

Cognitive features (LLM-optional)

Everything in the sections above runs without an LLM. These extras use one when available:

• REM Dreaming — clusters co-occurrence patterns into Insight nodes. Runs on a schedule or on demand.
• Style mimicry — per-file coding conventions extracted from the file's current state (no LLM needed for the core extraction).
• Business-logic comprehension — local-Ollama method-level analysis with a deterministic fallback, validation gate, and hallucination detection.
• Migration boundary suggestion — LLM + deterministic boundary detection with cross-cluster dependency analysis.

Project memory and diff artefacts

Nice-to-haves rather than core capabilities, grouped here so they don't clutter the top:

• produce_claude_md — generate CLAUDE.md + .claude/rules/* from indexed signals. Rules bucketed into three confidence tiers (Hard — live reverts and security invariants; Strong — team-enforced conventions; Observed — pattern observations, advisory). Convention files use an Applies to / Mandatory / Strong / Observed / Avoid template with explicit sample-scoping. Merge modes: splice, optimize, replace. Optional use_llm: true polish pass is registry-cached so reruns against the same inputs cost zero tokens.
• explain_change — narrates a diff as commit message, PR description, or changelog entry. Deterministic pass with optional LLM polish; cached by diff hash.

Memory bank and repo rules

Per-project persistent notes the agent reads and writes across sessions. File-pattern rules automatically injected into chunk retrieval (for example, "files matching *Repository.cs must use IUnitOfWork" attaches to every read of those files).

Multi-client daemon

Auto-daemon dispatcher so several MCP clients can share one Engram process. First client spawns the daemon; subsequent clients attach as proxies; the daemon lingers past the last disconnect so repeated short sessions don't pay the warm-up cost every time. File-based lock, race-free session counting, startup retry.

Observability and integrity

Lock-free metrics (job latency, queue depth, index drift, memory pressure, checkpoint recovery, extraction confidence, safety decisions). Cross-store integrity sentinels with 5 % tolerance and auto-repair. Crash-safe job orchestration with resume-from-failure. Retrieval quality benchmarking (NDCG@10, Recall@10, MRR) with configurable pass / fail thresholds.

Languages and ecosystems

Unknown extensions fall through to a generic text chunker + full-text indexing path.

Install

Prerequisites

• Rust 1.81+ (edition 2024)
• On Linux / macOS: libgit2 and cmake development packages
• Optional: Ollama for local LLM / embedding backends

Build

git clone https://github.com/your-org/engram-mcp-v2
cd engram-mcp-v2
cargo build --release

The binary lands at target/release/engram_server.

Configure

Minimal engram_mcp.yaml:

allowed_roots:
  - /home/user/projects
data_dir: /home/user/.engram-data

embedding_backend: local       # "local" | "ollama" | "openai"
advertise_all_tools: true       # default: full tool discovery, including .NET tools

Set advertise_all_tools: false only for clients requiring the limited core tool list. Tools omitted from tools/list may be unavailable to client agents; list_advanced_tools is a catalog, not a substitute for protocol discovery. Restart the daemon and reconnect clients after changing this setting.

validate_generated_code defaults to checking native code edits. Set include_migration_advice: true when you also want VB-to-C# translation and ASP.NET Core migration cautions. Blocking task/lock checks run in both modes.

analyze_business_logic preserves separate method overloads. When analyzing a single overloaded name, pass its one-based declaration line; file analysis returns that selector as overload_line. Empty VB methods receive a deterministic summary. VB extraction preserves Windows line endings and one-based source references, and successful file reanalysis removes obsolete method summaries. Interface and abstract declarations have no executable body and are excluded. Incomplete model JSON receives one retry with a larger response budget; its deadline fits within the HTTP transport ceiling. If that also fails, the original diagnostic remains available.

grep_project includes a doc_id for indexed matches in both JSON and Markdown, so they can be passed directly to get_chunk. Working-tree-only matches have no indexed identifier and explicitly point callers to the file instead.

Point the server at it via environment variable:

export ENGRAM_CONFIG_PATH=/path/to/engram_mcp.yaml
./target/release/engram_server

The server runs over stdio. All stdout is reserved for MCP protocol messages; logs go to stderr. Enable debug logs with RUST_LOG=debug.

Connect

Claude Desktop

{
  "mcpServers": {
    "engram": {
      "command": "/path/to/engram_server",
      "env": { "ENGRAM_CONFIG_PATH": "/path/to/engram_mcp.yaml" }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "engram": {
      "type": "stdio",
      "command": "/path/to/engram_server",
      "env": { "ENGRAM_CONFIG_PATH": "/path/to/engram_mcp.yaml" }
    }
  }
}

First session

Index /home/user/myapp as project "myapp" (project_type: dotnetwebformscs).
Wait for indexing to complete. Then give me a codebase overview.

After any set of staged changes:

Run pre_commit_review on the staged diff for project "myapp".

Tool reference

Engram exposes roughly 110 MCP tools, all scoped by project_id. The groups below match the capability hierarchy above — revolutionary tools first, operational surface last. Full parameter reference in docs/TOOL_CONTRACT.md.

Architecture

Storage layers

Indexing a project produces five persistent stores:

┌─────────────────────────────────────────────────────────┐
│  Full-text index (Tantivy)                              │
│    camelCase / snake_case tokenisation, namespace-aware │
├─────────────────────────────────────────────────────────┤
│  Vector index (LanceDB)                                 │
│    local trigram / Ollama / OpenAI — RRF + MMR fusion   │
├─────────────────────────────────────────────────────────┤
│  Knowledge graph (Redb)                                 │
│    ~40 edge kinds, O(degree) adjacency, PageRank        │
├─────────────────────────────────────────────────────────┤
│  Git intelligence (libgit2)                             │
│    commit graph, revert detection, temporal coupling    │
├─────────────────────────────────────────────────────────┤
│  Registry (Redb)                                        │
│    projects, jobs, memory bank, repo rules, meta        │
└─────────────────────────────────────────────────────────┘

Crates

Background actors

• Dreamer — co-occurrence clustering into Insight generation.
• Immune actor — git-revert harvesting into anti-pattern indexing.
• Watcher — directory monitoring for incremental re-index.
• GC scheduler — orphaned-job cleanup.
• Integrity sentinel — cross-store consistency checks with configurable auto-repair.
• Memory-budget watcher — per-subsystem soft / hard limits with CAS allocation and backpressure.
• Multi-client dispatcher — auto-daemon, file-based lock, proxy forwarding, race-free session counting.

Configuration

Full YAML:

# Required
allowed_roots:
  - /home/user/projects
data_dir: /home/user/.engram-data

# Embedding backend
embedding_backend: local              # "local" | "ollama" | "openai"
embedding_model: nomic-embed-text
ollama_url: http://localhost:11434
openai_api_key: sk-...
openai_api_base: https://api.openai.com/v1

# LLM backend for cognitive features (optional — everything except
# `dream`, `analyze_business_logic`, `suggest_migration_boundaries`,
# and the optional `use_llm` curation pass on `produce_claude_md`
# works without it)
llm_backend: none                     # "none" | "ollama" | "openai" | "openrouter"
llm_provider: openrouter
llm_model: llama3.2
llm_ollama_url: http://localhost:11434
llm_openai_api_key: sk-...
llm_http_referer: https://your-app.example

# Limits
max_project_files: 100000
max_project_bytes: 5368709120         # 5 GiB
max_chunks_per_file: 2000
max_concurrent_jobs: 2
max_commits_per_watch: 50

# Safety and Autonomous Decision Protocol
safety_policy_enabled: true
safety_min_confidence: 0.7
safety_min_coverage: 0.6
adp_enabled: true
adp_min_extraction_confidence: 0.5
adp_max_blast_radius: 6
adp_rollout_phase: shadow             # shadow | advisory | guarded | autonomous
adp_kill_switch: false                # emergency kill-switch — forces every verdict to deny

Project types

Any unknown type falls back to a broad default covering common source and config extensions.

Example agent prompts

Orientation

Give me a codebase overview for project "myapp". Then run pre_commit_review
on the staged diff.

Safe refactor

Before I refactor UserRepository.cs in project "myapp":
1. Run impact_analysis for this file
2. Run compute_blast_radius
3. Find all temporal couplings so I know which files to change together
4. Show me the top 5 reverted commits that touched this file

Pre-commit review (JSON for CI)

Run pre_commit_review on the unstaged diff for project "myapp" with
output_json: true, then summarise the CRITICAL and WARNING findings.

Generate project memory

Run produce_claude_md on project "myapp" with write_to_disk: true and
merge_mode: "optimize". Show me the summary notes.

Narrate a diff

Run explain_change on the staged diff for project "myapp" — I need a PR
description.

Legacy modernization

Run analyze_full_project_migration on project "myapp-legacy". Share the
cross-cutting summary and the top 3 files by migration risk.

Anti-pattern guard

Here's code I'm about to commit. Run immune_check on it against project
"myapp" with file_path="Site/App_Code/dal/orders.vb":

[paste code]

Security model

• Path confinement. All file access is validated against allowed_roots. Paths that escape via symlinks, .., or canonicalisation tricks are rejected.
• Project-ID validation. Restricted to [A-Za-z0-9_-]{1,128} at the handler boundary.
• Single-writer semantics. Per-project mutexes serialise concurrent index updates.
• No shell execution. Every git operation uses libgit2 directly; no subprocess is spawned.
• Secrets redacted in output. pre_commit_review fingerprints matched secrets; the raw value is never echoed back in findings.
• Fail-closed on integrity. The FTS watcher is fail-closed (no silent downgrades); integrity sentinels detect cross-store drift and can auto-repair.

Documentation

• docs/ARCHITECTURE.md — system design and component interactions
• docs/DATA_MODEL.md — storage-layer schemas
• docs/TOOL_CONTRACT.md — full tool parameter reference
• docs/COGNITIVE_PIPELINES.md — dreaming, immune system, style analysis
• docs/GENERATION_MODEL.md — append-only generation semantics
• docs/DEVELOPER_SPEC.md — contributing and internals
• docs/ROADMAP.md — planned features

License

Licensed under PolyForm Noncommercial License 1.0.0 (PolyForm-Noncommercial-1.0.0).

• Noncommercial use — personal, hobby, learning, research — is allowed under PolyForm Noncommercial 1.0.0.
• Commercial, business, or for-profit use requires a separate written commercial license.
• A company using this code — internally, in product development, SaaS, services, or any revenue-generating work — must obtain a commercial license.

See LICENSE for the full terms and COMMERCIAL-LICENSE.md for the commercial-use notice.