agent-context-mcp

Persistenter, Harness-unabhängiger Projektspeicher für KI-Codierungsagenten.

Ein zustandsloser MCP-Server, der jedem Agenten – Claude Code, Codex, Kilo Code, OpenCode, Cursor – strukturierten Lese-/Schreibzugriff auf einen projektspezifischen ai_context/-Ordner mit einfachem Markdown bietet. Entscheidungen, Pläne, Einschränkungen und Notizen leben im Repository, synchronisieren sich über git und bleiben für Agenten lesbar, die den Server nicht installiert haben.

Der Agent entscheidet, wann und was er aufzeichnet. Der Server entscheidet über Format und Ort. Diese Meinungsstärke ist der Punkt: Gib einem Agenten freie Schreibrechte und der Ordner verkommt zu Schlamm.

Was es nicht ist

Keine Codeabfrage, keine semantische Suche, keine Embeddings, keine Datenbank, kein Daemon-Zustand. Reine Datei-E/A. Es ergänzt ein Code-Suchwerkzeug, anstatt mit einem zu konkurrieren.

Related MCP server: Jarvis Markdown MCP

Installation

Benötigt Node ≥ 18. Es muss nichts global installiert werden – jeder unten genannte Harness führt es über npx aus.

npx agent-context-mcp init

init erstellt das ai_context/-Grundgerüst, legt project.md und constraints.md an, hängt den Aktivierungsausschnitt an AGENTS.md an und gibt den Registrierungsblock für deinen Harness aus. Es überschreibt niemals eine vorhandene Datei.

Bei deinem Harness registrieren

Claude Code, vom Projektstammverzeichnis aus:

claude mcp add agent-context -- npx -y agent-context-mcp .

Oder committe eine .mcp.json, damit das gesamte Team sie erhält:

{
  "mcpServers": {
    "agent-context": {
      "command": "npx",
      "args": ["-y", "agent-context-mcp", "."]
    }
  }
}

Codex, in ~/.codex/config.toml:

[mcp_servers.agent-context]
command = "npx"
args = ["-y", "agent-context-mcp", "."]

Kilo Code, OpenCode, Cursor, Windsurf und andere MCP-Clients übernehmen denselben mcpServers-JSON-Block in ihrer eigenen Einstellungsdatei.

Der nachgestellte . bewirkt, dass der Server das Arbeitsverzeichnis des Harness als Projektstamm behandelt. Gib stattdessen einen absoluten Pfad an, wenn dein Harness woanders startet. Der Transport ist ausschließlich stdio.

AGENTS.md-Ausschnitt

init hängt dies an; füge es von Hand hinzu, wenn du init nicht ausführen möchtest. Es ist das, was Agenten tatsächlich dazu bringt, die Werkzeuge zu nutzen:

## Persistent project context

This project uses the agent-context MCP server. At session start, call
`get_context` (no arguments) to orient yourself. When you make or the user
confirms a significant architectural/technical decision, call
`record_decision`. Persist gotchas and conventions with `record_note`.
Human-curated ground truth lives in ai_context/project.md and
ai_context/constraints.md — read them, never contradict them.

Der Ordner

<project-root>/
  AGENTS.md                 entry point — yours, never written except by `init`
  ai_context/
    INDEX.md                auto-maintained table of contents (server-owned)
    project.md              what this project is (yours; server reads, never writes)
    constraints.md          hard rules and good practices (yours; read-only to the server)
    memory.md               notes, written via record_note
    decisions/
      0001-use-postgres.md  ADRs, written via record_decision
    plans/
      auth-refactor.md      mutable plans, written via update_plan

• ai_context/ wird beim ersten Schreiben lazy erstellt oder vorab durch init.

• INDEX.md wird nach jedem Schreiben neu generiert und jedes Mal von der Festplatte neu eingelesen. Niemals von Hand bearbeiten.

• Entscheidungen sind append-only (nur anhängen). Eine zu ersetzen bedeutet, eine neue aufzuzeichnen, die darauf verweist; die einzige Änderung, die jemals an einer bestehenden ADR vorgenommen wird, ist eine Metadatenzeile - Superseded-by: NNNN.

• Pläne sind änderbar – update_plan überschreibt.

• project.md und constraints.md sind die menschliche Grundwahrheit. Der Server liest sie und schreibt sie nie.

Werkzeuge

Längenbegrenzungen sind bewusste Anti-Schlamm-Disziplin, keine Speicherlimits: Titel 80 Zeichen, ADR-Abschnitte je 1200, Notizen 500, Pläne 8000. Das Überschreiten einer Grenze gibt eine Meldung mit der tatsächlichen Länge und dem Limit zurück, damit der Agent zusammenfassen und erneut versuchen kann.

Es gibt kein search_context. Grep über einen kleinen Markdown-Ordner reicht aus, und Agenten haben es bereits.

Sicherheit

• Jeder Pfad wird durch eine einzige Schutzfunktion aufgelöst; nichts außerhalb von ai_context/ wird jemals gelesen oder geschrieben, und Traversal in einem Slug oder Thema wird abgelehnt, anstatt stillschweigend in etwas anderes bereinigt zu werden.

• Schreibvorgänge gehen in eine temporäre Datei und werden an Ort und Stelle umbenannt, sodass ein Absturz keine halb geschriebene Datei hinterlassen kann.

• Kein Zustand zwischen Aufrufen, keine Caches. Änderungen von einem Menschen, einem git pull oder einem anderen Agenten werden beim nächsten Aufruf übernommen.

Entwicklung

npm install
npm test          # unit + stdio integration tests
npm run typecheck # sources and tests
npm run build

Lizenz

MIT