scratchpad-mcp

Persistenter, Token-effizienter Speicher für KI-Agenten. Ein MCP-Server, der verhindert, dass Ihre Agenten bei jedem Durchlauf dieselben Dateien erneut lesen und denselben Kontext neu laden müssen.

agent: "what changed in this file since I last read it?"
server: { diff: [...], current_version: 14 }   ← not the whole file

Warum

Agenten verschwenden Token. Sie lesen Dateien erneut, die sie bereits gesehen haben, fassen Dokumente erneut zusammen, die sie bereits verarbeitet haben, und entdecken Zustände neu, die sie bereits berechnet haben. Dieser Server bietet ihnen einen Ort, an dem sie diese Arbeit ablegen und später auf eine Weise wieder aufnehmen können, die das Modell kostengünstig verarbeiten kann.

Konkret:

• Versionierte Schreibvorgänge, damit ein Agent ein Arbeitsdokument speichern und fragen kann: „Was hat sich geändert, seit ich das zuletzt gesehen habe?“ – der Server gibt ein strukturiertes Diff anstelle des vollständigen Inhalts zurück.

• Reine Anhänge-Logs (Append-only) mit Cursor-basierter Paginierung, damit ein Agent seine eigene Aktionshistorie aufzeichnen und effizient wiedergeben kann.

• On-Demand-Zusammenfassungen für lange Dateien (>2000 geschätzte Token), generiert von Claude Haiku und pro Dateiversion zwischengespeichert, sodass wiederholte Zusammenfassungsanfragen kostenlos sind.

• Namespacing pro Agent, sodass eine Serverinstanz viele Agenten bedienen kann, ohne den Status zwischen ihnen zu vermischen.

Tools

Alle Tools akzeptieren agent_id als erstes Argument. Vorgänge sind auf diesen Agenten beschränkt – Agenten können weder die Dateien noch die Logs der anderen lesen.

Diff-Format

read_file mit since_version gibt ein JSON-Array von Chunks zurück:

{
  "diff": [
    { "op": "equal",  "lines": ["line that didn't change"] },
    { "op": "remove", "lines": ["line that was deleted"] },
    { "op": "add",    "lines": ["line that was added"] }
  ]
}

Zeilenbasiertes Diffing ist beabsichtigt – es ist das Format, das Agenten am zuverlässigsten verarbeiten können, und es ermöglicht dem Agenten, darüber nachzudenken, was sich geändert hat, anstatt die gesamte Datei neu zu verarbeiten.

Pfadregeln

Pfade müssen [a-zA-Z0-9/_.-]+ entsprechen, maximal 255 Zeichen, kein führender /, keine ..-Sequenzen. Fehler benennen die verletzte Regel.

Limits

• 1 MB pro Dateischreibvorgang

• 64 KB pro Log-Eintrag

• 10 gespeicherte Versionen pro Datei (ältere werden automatisch gelöscht)

• 100 Log-Einträge pro read_log-Seite

Installation

Erfordert Node 20+ und einen Anthropic API-Key (nur für summarize_file).

git clone <this repo>
cd scratchpad-mcp
npm install
npm run build

Dies erzeugt dist/index.js, den ausführbaren Server.

Konfiguration mit Claude Desktop

Fügen Sie dies zu %APPDATA%\Claude\claude_desktop_config.json (Windows) oder ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) hinzu:

{
  "mcpServers": {
    "scratchpad": {
      "command": "node",
      "args": ["C:\\path\\to\\scratchpad-mcp\\dist\\index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

ANTHROPIC_API_KEY ist nur erforderlich, wenn Sie summarize_file aufrufen möchten. Die anderen sieben Tools funktionieren auch ohne diesen.

Optional: Setzen Sie SCRATCHPAD_DB_PATH, um den SQLite-Speicherort zu überschreiben. Standardmäßig scratchpad.db im Projektstammverzeichnis.

Starten Sie Claude Desktop neu. Der Server sollte in der Liste der MCP-Server mit 8 Tools erscheinen.

Sicherheitsmodell – bitte vor dem Hosten lesen

agent_id ist ein Klartext-Tool-Parameter. Es gibt keine Authentifizierung: Ein Aufrufer kann behaupten, jede beliebige agent_id zu sein, und der Server wird ihr vertrauen. Dies ist für V1 beabsichtigt und funktioniert gut für die vorgesehene Bereitstellungsform, nämlich:

• Ein Benutzer pro Serverprozess. Der Agent und die SQLite-Datei teilen sich eine Vertrauensgrenze. Beispiele: Claude Desktop-Installation, Smithery-lokale Installation, Apify Actor-Ausführung pro Benutzer (Apify erstellt standardmäßig einen neuen Container mit einer neuen Datenbankdatei pro Ausführung).

Es ist nicht sicher für:

• Multi-Tenant-Standby-Modus, bei dem ein Serverprozess mehrere nicht vertrauenswürdige Aufrufer bedient, die dieselbe SQLite-Datei lesen und schreiben. Jeder kann die agent_id eines anderen Aufrufers übergeben und dessen Daten lesen oder überschreiben.

Wenn Sie Multi-Tenant wünschen, leiten Sie die agent_id in einer Wrapper-Schicht vom API-Key des Aufrufers ab (dies ist der Plan für V2) oder führen Sie einen Prozess pro Tenant aus.

Tiefenverteidigung, die bereits vorhanden ist

• Alles SQL ist parametrisiert – keine Injektion über Pfad, agent_id oder Präfix möglich.

• Die Pfadvalidierung lehnt .., führende /, Leerzeichen und jedes Zeichen außerhalb von [a-zA-Z0-9/_.-] ab.

• Der Präfix-Abgleich von list_files verwendet SUBSTR-Gleichheit (nicht LIKE), sodass die SQL-Platzhalter _ und % niemals angewendet werden und der Abgleich zwischen Groß- und Kleinschreibung unterscheidet.

• Größenbeschränkungen pro Aufruf (1 MB / Datei, 64 KB / Log-Eintrag).

• Kontingente pro Agent (1000 Dateien, 100k Log-Einträge, 100 MB insgesamt), damit ein außer Kontrolle geratener Agent bei einer gehosteten Bereitstellung nicht den gemeinsamen Speicherplatz erschöpfen kann.

• Fehler geben nur err.message zurück – keine Stack-Traces, keine SQLite-Pfade, keine API-Keys.

Wer bezahlt für summarize_file?

Der Aufrufer. Immer.

• Lokale Installation (Smithery, Claude Desktop, mcp.so): Der Benutzer stellt seinen eigenen ANTHROPIC_API_KEY in seiner Konfiguration bereit. Sein Computer, sein Key, seine Rechnung.

• Apify gehostet: Jede Actor-Ausführung liest anthropicApiKey aus ihrer Eingabe pro Ausführung. Ein .actor/entrypoint.sh-Launcher ordnet dies der Umgebung zu, bevor der Server gestartet wird. Jeder Aufrufer bezahlt Anthropic für seine eigenen Zusammenfassungen; der Actor-Herausgeber erhebt nur die Gebühr pro Aufruf von Apify.

Wenn Sie dies forken und hosten möchten, kodieren Sie keinen API-Key fest in das Dockerfile, die Apify Actor-Umgebung oder eine Konfiguration, die öffentlich versendet wird. Die anderen sieben Tools funktionieren ohne Key, daher ist es eine sichere Standardeinstellung, ihn nicht festzulegen.

Wie die Speicherung funktioniert

Eine einzelne SQLite-Datei enthält alles:

• files – eine Zeile pro (agent_id, path), verfolgt die aktuelle Version.

• file_versions – vollständiger Inhalt pro Version, begrenzt auf die 10 neuesten pro Datei. Das Löschen erfolgt bei jedem write_file.

• log_entries – reine Anhänge-Einträge, werden nie geändert.

• summaries – Zusammenfassungs-Cache pro Datei, wird bei Versionskonflikten ungültig.

• agent_usage – Vorgangszähler pro Agent für get_usage_stats.

Die Versionierung speichert den vollständigen Inhalt pro Version (keine Deltas), da Schreibvorgänge schnell sein müssen und Lesevorgänge eindeutig sein müssen. Diffs werden beim Lesen berechnet, indem die beiden Versionen durch zeilenweises Diffing verglichen werden – die Kosten trägt der Aufrufer, der das Diff anfordert, nicht jeder Schreiber.

Roadmap

• [ ] Apify-Paketierung für Pay-per-Call-Abrechnung.

• [ ] Ableitung der agent_id vom API-Key anstatt sie als Parameter zu akzeptieren.

• [ ] Postgres-Backend (das SQLite-Schema ist portabel; dies ist ein Verbindungswechsel, keine Neuschreibung).

• [ ] Ratenbegrenzung pro Agent.

• [ ] Strukturiertes Logging für Betriebstransparenz.

Lizenz

MIT – siehe LICENSE.