Trailmark MCP-Server

Trailmark MCP-Server ist ein eigenständiger MCP-Wrapper um .

Obwohl ich die Verwendung durch ToB mit verstehe, erfordert mein Anwendungsfall einen MCP-Server, der mehrere Graphen analysieren und bereitstellen kann. Der Server kann mehrere Repositories scannen und das LLM kann Informationen von jedem einzeln anfordern.

Größtenteils erstellt mit OpenAI GPT-5.5 via Github Copilot in VS Code. Verweisen Sie Ihr LLM für Dokumentation und Entwicklungsunterstützung auf das Verzeichnis ai-docs.

Anforderungen

• Python 3.12+

• uv

Projekt-Metadaten:

• Paketname: trailmark-mcp

• CLI-Befehl: trailmark-mcp

Installation

Installieren Sie Laufzeit- und Entwicklungsabhängigkeiten:

uv sync --group dev

Schnellstart

Starten Sie den Server über stdio:

uv run trailmark-mcp serve --transport stdio

Smoke-Test des direkten Scan-Pfads ohne MCP-Client:

uv run trailmark-mcp scan /path/to/repo

Überspringen der Voranalyse während des Scans bei Bedarf:

uv run trailmark-mcp scan /path/to/repo --skip-preanalysis

Funktionsweise des Servers

Der primäre Lebenszyklus-Einstiegspunkt ist open_repository(...).

Zusammenfassung des Verhaltens:

• Wenn kein Snapshot existiert, scannt der Server die Quelle, führt optional eine Voranalyse durch und speichert den ersten Snapshot.

• Wenn ein Snapshot existiert und rescan=False gesetzt ist, lädt der Server den neuesten Snapshot in eine Live-Sitzung.

• Wenn rescan=True gesetzt ist, baut der Server die Quelle neu auf und speichert einen frischen Snapshot.

Das bedeutet, der übliche Ablauf ist:

1. open_repository aufrufen

2. Graph-Tools gegen die zurückgegebene Sitzung verwenden

3. save_snapshot nach bedeutsamen Mutationen im Arbeitsspeicher aufrufen, wenn Persistenz gewünscht ist

Sitzungsmodell

session_id ist ein Zustand des MCP-Wrappers, kein Zustand des Trailmark-Kerns.

Aktuelle Semantik:

• Jeder open_repository(...)-Aufruf erstellt eine neue Sitzungs-ID.

• Mehrere Live-Sitzungen können koexistieren.

• Tools akzeptieren session_id, um einen bestimmten Graphen anzusprechen.

• Eine weggelassene session_id verwendet die zuletzt geöffnete, noch aktive Sitzung.

• Das Schließen der Standardsitzung befördert die zuletzt geöffnete verbleibende Sitzung.

Verwenden Sie current_repository(session_id=...), um zu überprüfen, auf welches Repository eine Sitzung verweist.

Öffentliche MCP-Tools

Lebenszyklus:

• open_repository

• current_repository

• close_repository

• save_snapshot

Navigation:

• graph_summary

• diff_graphs

• search_nodes

• callers_of

• callees_of

• ancestors_of

• reachable_from

• paths_between

• entrypoint_paths_to

• attack_surface

• complexity_hotspots

• functions_that_raise

Kontext und Mutation:

• subgraph

• annotations_of

• findings

• nodes_with_annotation

• run_preanalysis

• annotate_node

• clear_annotations

• augment_findings

Hinweise:

• diff_graphs(before_session_id, after_session_id) behandelt after als den neuen Zustand.

• search_nodes unterstützt contains, exact und suffix.

• Entfernte Hilfsflächen wie scan_repository und tool_manifest sind absichtlich nicht mehr Teil der öffentlichen Laufzeit.

Snapshot-Verhalten

Snapshots werden unter dem analysierten Repository geschrieben, nicht unter diesem Server-Repository:

<target-repo>/.trailmark/snapshots/<timestamp>/

Aktuelle Snapshot-Artefakte beinhalten:

• graph.json

• summary.json

• entrypoints.json

• hotspots.json

• subgraphs.json

• scan-metadata.json

Snapshots unterstützen das Neuladen in eine Live-Sitzung. Verwenden Sie rescan=True, wenn Sie explizit einen frischen Neuaufbau aus der Quelle benötigen.

Repository-Struktur

Wichtige Dateien:

• src/trailmark_mcp/cli.py: CLI-Einstiegspunkt für scan und serve

• src/trailmark_mcp/mcp_app.py: MCP-Tool-Registrierung

• src/trailmark_mcp/tool_catalog.py: deklarative Metadaten für bereitgestellte Tools

• src/trailmark_mcp/services/registry.py: Sitzungsverfolgung

• src/trailmark_mcp/services/runtime.py: Haupt-Laufzeitverhalten basierend auf Trailmark

Entwicklung

Führen Sie die fokussierte Testsuite aus:

uv run --group dev pytest tests/test_tool_catalog.py tests/test_registry.py tests/test_stdio_server.py

Die aktuelle CI führt dieselbe fokussierte Suite unter Python 3.12 aus.

Erweiterungsregel:

1. Laufzeitverhalten hinzufügen oder ändern

2. Tool in mcp_app.py registrieren

3. Metadaten in tool_catalog.py aktualisieren

4. Tests aktualisieren

5. Dokumentation aktualisieren, falls sich das öffentliche Verhalten geändert hat

Verwendung in VS Code

VS Code kann diesen Server direkt über MCP mithilfe einer mcp.json-Datei auf Workspace-Ebene starten.

Typisches Setup:

1. Öffnen Sie dieses Repository in VS Code

2. Stellen Sie sicher, dass die Abhängigkeiten mit uv sync --group dev installiert sind

3. Behalten Sie die Serverdefinition in .vscode/mcp.json bei

4. Lassen Sie den MCP-Client den Server über stdio starten

Dieses Repository enthält bereits .vscode/mcp.json für die lokale Verwendung.

Beispiel mcp.json:

{
  "servers": {
    "trailmark-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "trailmark-mcp",
        "serve",
        "--transport",
        "stdio"
      ]
    }
  }
}

Wenn Sie diesen Server aus einem größeren Multi-Projekt-Workspace verwenden, kopieren Sie dieselbe Definition in das .vscode/mcp.json des Workspace-Roots und stellen Sie sicher, dass der Befehl in einer Umgebung ausgeführt wird, in der uv und dieses Projekt verfügbar sind.