atlas-introspect-mcp

Ein MCP-Server, der es ATLAS erlaubt, sich selbst zu betrachten – und zu bearbeiten:

Warum es über die HTTP-API läuft

Chatverlauf, Arbeitsbereiche und Prompts liegen alle in einer DuckDB-Datei (data/chat_history.db). DuckDB ist Single-Writer und der ATLAS-Prozess hält diesen Schreib-Lock für seine gesamte Lebensdauer – ein zweiter Prozess, der die Datei öffnet, auch nur lesend, scheitert mit einem Lock-Konflikt. Deshalb fragt dieser Server ATLAS über Loopback-HTTP ab. Das bedeutet auch, dass die Benutzerzuordnung von ATLAS durchgesetzt wird und nicht hier neu implementiert wird.

Nur mcp.json und prompts/*.md werden direkt angefasst; ATLAS hat für beides keine API.

Ein separater Prozess zu sein, macht den Rückruf an ATLAS sicher: ATLAS wartet auf die stdio-Antwort dieses Servers, während seine eigene Ereignisschleife frei bleibt, um die Anfrage zu bedienen. Ein In-Process-Werkzeug, das dasselbe tut, würde in einen Deadlock geraten.

Related MCP server: Atlas MCP Server

Identität

Jede Abfrage ist auf einen Benutzer beschränkt und wird als X-User-Email gesendet. Mit DEBUG_MODE=true respektiert ATLAS diesen Header; ist er aus, ist der Header das, was der Auth-Proxy geliefert hätte, also funktioniert dasselbe Flag in beiden Fällen. Der Standard ist test@test.com – der Testbenutzer, auf den ATLAS im Debug-Modus zurückfällt, und daher der Besitzer der über die UI auf diesem Host erstellten Konversationen.

Installation

git clone https://github.com/garland3/atlas-introspect-mcp
cd atlas-introspect-mcp
uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python

Standalone-Check (mit laufendem ATLAS):

.venv/bin/atlas-introspect-mcp --list-tools
.venv/bin/python -c "
import asyncio; from fastmcp import Client
from fastmcp.client.transports import StdioTransport
async def m():
    async with Client(StdioTransport(command='.venv/bin/atlas-introspect-mcp', args=['--stdio'])) as c:
        print(await c.call_tool('atlas_status', {}))
asyncio.run(m())"

Bei ATLAS registrieren

Fügen Sie zu Ihrer ATLAS-config/mcp.json hinzu (absolute Pfade – der Befehl wird im PATH des Dienstmanagers gesucht, nicht in dem Ihrer Shell), und starten Sie dann ATLAS neu:

"atlas_introspect": {
  "command": [
    "/abs/path/to/atlas-introspect-mcp/.venv/bin/atlas-introspect-mcp",
    "--stdio",
    "--atlas-url", "http://127.0.0.1:8090",
    "--user", "test@test.com"
  ],
  "cwd": "/abs/path/to/atlas-introspect-mcp",
  "transport": "stdio",
  "groups": ["users"],
  "description": "Introspect and configure this ATLAS instance: browse chat history, read/edit config/mcp.json, manage workspaces and custom prompts.",
  "short_description": "ATLAS self-introspection",
  "compliance_level": "Public"
}

Fügen Sie "--read-only" zum Befehl hinzu, um eine reine Ansichtsversion zu erhalten; jedes mutierende Werkzeug verweigert dann die Ausführung, anstatt zu schreiben.

Ports: stdio benötigt keinen. --transport http verwendet standardmäßig 8101. Es verweigert Port 8080 grundsätzlich – auf einem Host mit k3s leitet klipper-lb 8080 an Traefik weiter, auch auf 127.0.0.1, sodass ein dort gebundener Server nichts empfängt und jede Anfrage als leere 500 zurückkommt, ohne eine Zeile in Ihrem Log.

Konfiguration

Jedes Flag hat eine Entsprechung als Umgebungsvariable.

Werkzeuge

Konversationen (nur lesen) – list_conversations, search_conversations, get_conversation, list_conversation_tags

config/mcp.json – get_mcp_config, upsert_mcp_server, delete_mcp_server, replace_mcp_config

Arbeitsbereiche – list_workspaces, create_workspace, update_workspace, delete_workspace

Benutzerdefinierte Prompts – list_custom_prompts, get_custom_prompt, create_custom_prompt, update_custom_prompt, delete_custom_prompt

Prompt-Dateien auf der Festplatte – list_prompt_files, read_prompt_file, write_prompt_file

Status – atlas_status

Fallstricke

• mcp.json-Änderungen sind nicht live. ATLAS startet stdio-Server beim Start. Jedes Schreibwerkzeug sagt das in seinem Ergebnis; wenden Sie es mit systemctl --user restart atlas oder ./redeploy.sh --no-pull an.

• Das Bearbeiten Ihres eigenen Eintrags funktioniert, wird aber erst beim Neustart wirksam – dann bedeutet ein defekter Eintrag, dass dieser Server verschwunden ist und Sie ihn nicht von ATLAS aus reparieren können. Sicherungen landen neben der Datei als mcp.json.bak-<stamp>.

• upsert_mcp_server ersetzt einen Eintrag vollständig, es führt keine Zusammenführung durch. Lesen Sie ihn zuerst, ändern Sie ihn, senden Sie das Ganze zurück. Gleiches gilt für eine Workspace-config und den content eines Prompts.

• Konversationswerkzeuge sind von Natur aus schreibgeschützt. Es gibt Lösch-Endpunkte in ATLAS; sie werden hier bewusst nicht bereitgestellt.

• write_prompt_file ändert jeden Chat in der Instanz. Es sichert zuerst und wird, wie mcp.json, beim nächsten Neustart wirksam.

Tests

.venv/bin/pytest

Sie decken die Dateibearbeitungs- und Validierungslogik (atomares Schreiben, Sicherung, Verweigerung von Verzeichniswechseln, Lint-Warnungen, Nur-Lesen-Modus) gegen ein temporäres Verzeichnis ab – kein laufendes ATLAS erforderlich.