Archive MCP Server

Ein MCP-Server, der die Datensätze und Aufbewahrungslogik des Enterprise Data Archival & Records Management System jedem MCP-Client zugänglich macht — Claude Code, Claude Desktop, Cursor oder einem eigenen Client — über stdio.

Statt durch das React-Dashboard zu klicken, um "Was können wir im Finanzbereich archivieren?" zu beantworten, fragst du das Modell, und es ruft diese Tools auf.

Tools

Related MCP server: EndpointRead-MCP

Ressourcen

Anforderungen

Python 3.10+ und MCP SDK 2.x. Das v2 SDK hat FastMCP in MCPServer umbenannt und es nach mcp.server.mcpserver verschoben; dieser Code zielt auf v2. Datenzugriff über SQLAlchemy 2.x, mit psycopg2 für PostgreSQL.

Einrichtung

python -m venv .venv
source .venv/bin/activate          # macOS/Linux
.venv\Scripts\activate             # Windows

python -m pip install -r requirements.txt
python seed_db.py                  # builds the local demo database
python server.py --selftest        # sanity check, no MCP client needed

Dann verifiziere es über eine echte MCP-Sitzung:

python verify_mcp.py

Datenbank auswählen

Der Server liest DATABASE_URL (aus der Umgebung oder aus einer .env-Datei — siehe .env.example):

archive.db enthält synthetische Datensätze, sodass der Server — und --selftest — für jeden laufen, der dieses Repo ohne Anmeldedaten klont. Es ist keine andere Codebasis: seed_db.py erstellt das gleiche Fünf-Tabellen-Schema, das auch die Produktionsdatenbank verwendet (active_records, archived_records, retention_policy, audit_logs, documents), sodass jede Abfrage in server.py unverändert gegen beide läuft.

Commite niemals eine echte DATABASE_URL. .env ist gitignored; .env.example ist die committete Vorlage.

Verbindung zu Claude Code

Vom Projektverzeichnis aus:

claude mcp add --scope project archive-system -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py
claude mcp list

--scope project schreibt eine committbare .mcp.json in das Projektverzeichnis, sodass jeder, der das Repo klont, den Server erhält. Starte claude, genehmige den Projekt-Server, wenn du dazu aufgefordert wirst, und prüfe /mcp — archive-system sollte Verbunden mit 6 Tools anzeigen. Dann frage:

Welche IT-Abteilungsdatensätze sind zur Archivierung überfällig?

Wenn er nicht startet, führe claude --debug=mcp aus und lies das Log unter ~/.claude/debug/.

Verbindung zu Claude Desktop

Füge dies zu claude_desktop_config.json hinzu:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "archive-system": {
      "command": "D:\\Python\\project\\archive-mcp\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Python\\project\\archive-mcp\\server.py"]
    }
  }
}

Richte command auf das Python der venv aus, nicht auf nacktes python — der Host erbt nicht den PATH deiner Shell oder deine aktivierte virtuelle Umgebung. Unter Windows müssen beide Pfade doppelte Backslashes enthalten.

Starte über das Tray-Symbol neu — Beenden, nicht den Fenster-Schließen-Button — sonst läuft die App mit der alten Konfiguration weiter.

Hinweis für den Microsoft Store (MSIX)-Build unter Windows: Dessen Konfiguration liegt nicht unter %APPDATA%, sondern im eigenen Verzeichnis des Pakets, %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\. Es startet lokale stdio-Server normal. Versuche nicht, das über logs\mcp.log zu bestätigen — diese Datei kann leer und unberührt bleiben, während alles funktioniert. Prüfe stattdessen den Prozess; der Server läuft als Kindprozess von Claude Desktop:

Get-CimInstance Win32_Process -Filter "Name like '%python%'" |
  Where-Object { $_.CommandLine -like "*archive-mcp*" }

Designhinweise

• stdio-Transport, weil der Client den Server als Unterprozess auf derselben Maschine startet. Ein HTTP-Transport wäre sinnvoll, wenn der Server remote liefe und mehrere Clients bediente.

• Eine Nahtstelle für die Speicherung. _connect() gibt eine SQLAlchemy-Engine zurück und ist die einzige Stelle, die weiß, was die Datenbank ist. Abfragen verwenden benannte Bindeparameter (:department), die dialektneutral sind, sodass SQLite und PostgreSQL einen gemeinsamen Abfragesatz teilen statt zwei.

• pool_pre_ping=True, weil ein serverloses PostgreSQL (Neon und ähnliche) die Leerlauf-Compute suspendiert und ein MCP-Server zwischen Fragen im Leerlauf sitzt. Ohne dies schlägt die erste Frage nach einer ruhigen Phase auf einer veralteten gepoolten Verbindung fehl.

• Die Berechtigung wird in Python berechnet, nicht in SQL. PostgreSQL-INTERVAL-Arithmetik hat kein SQLite-Äquivalent, und der Vergleich an einer Stelle zu halten, hält die beiden Backends ehrlich. Bei ein paar tausend aktiven Zeilen ist der Aufwand nicht wert, optimiert zu werden.

• Das Alter wird ab joining_date gemessen. created_at ist der Bulk-Load-Zeitstempel und für jede Zeile identisch, sodass eine darauf basierende Aufbewahrung nie etwas Berechtigtes finden würde. joining_date ist ein Datum auf Mitarbeiterebene, das als Dokumentdatum dient — das Schema enthält kein Dokumentdatum, was eine echte Lücke ist, die es wert ist, upstream geschlossen zu werden.

• Der Archivierungszustand ist eine Tabelle, kein Flag. Ein Datensatz lebt in active_records oder in archived_records, und die IDs sind über den Wechsel hinweg stabil, sodass get_record beide prüft. Die Spalte status ist der Beschäftigungsstatus und steht in keinem Zusammenhang.

• Tools sind als schreibgeschützt annotiert. Jedes trägt ToolAnnotations(read_only_hint=True, destructive_hint=False), sodass ein Client einen sicheren Aufruf von einem zustandsändernden unterscheiden kann, bevor er ausgeführt wird.

• Tools sind auch tatsächlich schreibgeschützt. Archivierung ist destruktiv und richtlinienbasiert; archival_candidates meldet bewusst, was archiviert werden könnte, und überlässt die Entscheidung dem bestehenden geplanten Job. Ein destruktives Tool einem Modell auszusetzen, ist eine Entscheidung, die zuerst einen Bestätigungspfad erfordert.

• Docstrings sind die API. Das Modell wählt Tools anhand des Docstrings und der Typannotationen aus, daher sind die gültigen Abteilungen und Dokumenttypen dort aufgelistet. Eine veraltete Aufzählung ist schlimmer als keine: Das Modell übergibt einen plausibel aussehenden Wert wie Legal, erhält ein leeres Ergebnis und meldet, dass es nichts zu archivieren gibt.

• Eine Definition von „berechtigt“, in beide Richtungen verwendet. _verdict altert einen Datensatz gegen seine Aufbewahrungsfrist; _eligible_on invertiert dies, um das Datum zu erhalten, an dem ein Datensatz diese Frist überschreitet, und danach gruppiert retention_forecast. Sie müssen exakt übereinstimmen, sonst kann ein Datensatz am selben Tag als bevorstehend in der Prognose und als überfällig in archival_candidates erscheinen. Die Inverse auf die naheliegende Weise zu schreiben (joining + timedelta(days=years * 365.25)) bricht dies, weil date + timedelta nur ganze Tage behält und die .75 stillschweigend verwirft.

• Die Ausgabe ist formatierter Text, keine rohen JSON-Dumps, sodass das Modell sie ohne Neuformatierung an einen Benutzer zurückzitieren kann.