Code Context Storage MCP

code-context-storage-mcp ist der lokale Speicher für Code-Kontext-Wissensdatenbanken und der MCP-Protokolldienst. Es speichert Code-Knoten, Aufruf-Kanten, semantische Informationen, Belege, Geschäftsverzeichnisse/-zuordnungen und Versions-Snapshots in SQLite und stellt über den stdio-Transport von FastMCP strukturierte Tools bereit.

Das Projekt positioniert sich zwischen „Skill / externer KI" und persistenten Geschäftsfähigkeiten: Aufrufer lesen und schreiben die Wissensdatenbank über MCP-Tools und sollten nicht direkt auf SQLite zugreifen. Das MVP richtet sich an ein einzelnes Code-Repository und eine feste Quellcode-Version, mit Schwerpunkt auf Index-/Artefakt-Import, versionsgebundene Abfragen, Geschäftszuordnung, Belegvalidierung, inkrementelle Synchronisierung, Snapshot-Veröffentlichung und Evaluierung.

Features

• SQLite-Persistenz von Code-Fakten: node, edge, evidence, node_semantic.

• Knoten-Recall basierend auf Semantik und Geschäftsbegriffen sowie budgetgebundener Graph-Kontext, Pfad- und Auswirkungsanalyse.

• Geschäftsverzeichnis, Kontext, Mapping und Mapping-Schritte; Kandidaten und bestätigte Ergebnisse haben einen klaren Status.

• Staging → published Snapshot-Veröffentlichungsprozess mit idempotenten Operationen, CAS-Parallelitätsschutz und Stale-Propagation/-Wiederherstellung.

• MCP-Protokoll v2-Envelope: request_id, operation_id, Schema-/Tool-Version und strukturierte Fehler.

• Testabdeckung für Unit-, Vertrags-, Blackbox- und reale stdio-MCP-Adapter-Szenarien.

Nicht im Umfang dieses Projekts enthalten sind Codegenerierung/-ausführung, repositoryübergreifende einheitliche Graphen, automatische Geschäftsmodellierung ohne menschliche Bestätigung sowie die Vermischung von Laufzeitbeobachtungen mit statischen Code-Fakten. Die vollständigen Grenzen finden Sie im MVP-Entwurfsdokument.

Related MCP server: local-code-intel-mcp

Requirements

• Python 3.11 oder höher

• pip

• Das Arbeitsverzeichnis in den Windows-PowerShell-Beispielen ist das Repository-Root

Abhängigkeiten werden in pyproject.toml deklariert; die zentrale Laufzeitabhängigkeit ist fastmcp==3.4.7.

Install

Es wird empfohlen, eine virtuelle Umgebung zu verwenden:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Wenn PowerShell die Ausführung von Aktivierungsskripten blockiert, können Sie die Umgebung auch ohne Aktivierung nutzen, indem Sie die folgenden Befehle direkt mit .\.venv\Scripts\python.exe ausführen.

Run the MCP server

Nach der Installation verwenden Sie den mitgelieferten Befehlszeilen-Einstiegspunkt:

code-context-storage-mcp --database .data\context.db

Oder direkt den Modul-Einstiegspunkt:

python -m code_context_storage_mcp.server --database .data\context.db

Beide Startmethoden verwenden den stdio-Transport. Der Prozess liest MCP-JSON-RPC-Nachrichten von stdin und schreibt Antworten nach stdout. Fügen Sie daher keine normalen Logs an stdout an; der Standardpfad der Datenbank ist .data/context.db, über --database kann eine andere SQLite-Datei angegeben werden.

Befehlszeilenargumente anzeigen:

code-context-storage-mcp --help

MCP client configuration

stdio-Clients sollten den folgenden Befehl starten und Anfragen an stdin schreiben:

{
  "mcpServers": {
    "code-context-storage": {
      "command": "code-context-storage-mcp",
      "args": ["--database", ".data/context.db"]
    }
  }
}

Wenn das Console-Script nicht installiert ist, kann command auf Python geändert werden und args auf:

["-m", "code_context_storage_mcp.server", "--database", ".data/context.db"]

Nach der Verbindung sollte der Client zuerst tools/list des MCP aufrufen, um die aktuell registrierten Tools und deren Eingabe-Schemas zu sehen. Die Tools decken Schreiben/Lesen von Code-Fakten, Graph-Abfragen, Geschäftsverzeichnis und -Mapping, Synchronisierungssteuerung, Veröffentlichung, Belege, Wissensgenerierung und Evaluierung ab; die konkrete Registrierungsmenge richtet sich nach dem zur Laufzeit vom Dienst zurückgegebenen tools/list.

Development commands

Im Repository-Root ausführen:

python -m pytest tests -q

Blackbox-Tests ausführen:

python -m pytest tests\blackbox -q

Für Szenarien in Blackbox-Tests, die einen echten MCP-stdio-Dienst benötigen, kann der Dienstbefehl konfiguriert werden:

$env:PYTHONPATH = "src"
$env:KNOWLEDGE_GENERATE_MCP_COMMAND = '["python", "-m", "code_context_storage_mcp.server"]'
python -m pytest tests\blackbox -q

Einige Blackbox-Tests werden übersprungen, wenn diese Konfiguration fehlt; in CI sollte sie explizit konfiguriert werden, damit die Tests Konfigurations- oder Protokollprobleme aufdecken.

Phase acceptance and evaluation

Phase-Acceptance-Bericht und zugehörige Evaluation-Request generieren:

python scripts\run_phase_acceptance.py --output artifacts\phase-acceptance.json

Offline-Evaluierung mit der generierten Request und den Schwellwerten ausführen:

python scripts\run_evaluation.py `
  --request artifacts\evaluation-request.json `
  --thresholds artifacts\thresholds.json `
  --output artifacts\evaluation-result.json `
  --database .data\context.db

run_evaluation.py verwendet standardmäßig einen leeren Antwort-Satz, was sich zur Validierung der Evaluierungs-Pipeline und des Eingabe-Vertrags eignet; für aussagekräftige Evaluierungsergebnisse sollten Blackbox-Antworten des MCP-Clients über --responses bereitgestellt werden. Das Skript beendet sich mit einem Nicht-Null-Exit-Code, wenn der Evaluierungsstatus nicht passed ist.

Repository layout

src/code_context_storage_mcp/
  server.py                 CLI 入口，创建 Store 并启动 stdio MCP 服务
  fastmcp_server.py         FastMCP server、tool 注册和 protocol envelope
  tool_definitions.py       tool 输入 schema
  router.py                 tool 到 handler/service 的分发
  handlers/                 代码事实、图查询和业务操作处理器
  services/                 查询、同步、索引、幂等、追踪等业务服务
  publication/              发布适配与发布服务
  store.py                  SQLite 持久化
  entities.py/contracts.py  数据实体与协议契约
migrations/                 SQLite schema migrations
tests/                      单元、契约、集成和黑盒测试
scripts/                    验收与评测脚本
docs/design/                设计文档

Die Hauptkette ist: server.main -> Store -> create_mcp_server -> ToolRouter -> handlers/services -> SQLite. Schreiboperationen gehen in der Regel zunächst in Staging, durchlaufen Konflikt-/Abdeckungs-Gates und veröffentlichen dann einen Snapshot; Abfragen sind auf einen Snapshot und eine Source-Revision fixiert und geben einen nachvollziehbaren Ausführungskontext zurück.

Data and migrations

Die Standard-Datenbankdatei .data/context.db sind Laufzeitdaten und sollten nicht in die Versionskontrolle eingecheckt werden. Das Schema wird durch SQL-Dateien in migrations/ gepflegt; bevor neue Codeversionen mit einer bestehenden Datenbank verbunden werden, sollte sichergestellt werden, dass die entsprechende Migration angewendet wurde. Tests verwenden in der Regel temporäre SQLite-Datenbanken und hängen daher nicht von der Standard-Datendatei auf dem Entwicklungsrechner ab.

License

Das aktuelle Repository enthält keine separate Lizenzdatei; für eine externe Veröffentlichung sollten zunächst Lizenz- und Beitragshinweise ergänzt werden.