Slipbox MCP Server

Gib deinem KI-Assistenten eine aktive Rolle bei der Verwaltung deines Wissens. Slipbox ist ein MCP-Server, der jeden MCP-kompatiblen Agenten in einen Zettelkasten-Partner verwandelt – atomare Notizen erstellt, semantische Verknüpfungen bildet, aufkommende Cluster erkennt und Erkenntnisse aus deinem vorhandenen Wissen synthetisiert.

Deine Ideen hinein, strukturiertes Wissen heraus. Der Agent übernimmt Formatierung, Verknüpfung und Integration.

Neu bei der Methode? Beginne mit Introduction to the Zettelkasten Method, um das Warum hinter atomaren Notizen und vernetztem Denken zu verstehen. Um zu sehen, wie Slipbox deinen Agenten mit dieser Methode vertraut macht, lies die Server-Anweisungen, die es beim Verbinden automatisch mitliefert.

Entwickelt und getestet mit Claude. Funktioniert mit jedem MCP-Client (Claude Desktop, Claude Code, OpenCode, Copilot oder allem, was MCP spricht).

Einfache Dateien, null Lock-in. Notizen sind Markdown mit YAML-Frontmatter – lesbar in Obsidian, Foam, Logseq oder jedem Editor. Die SQLite-Datenbank ist ein Index, nicht die Quelle der Wahrheit. Lösche sie und baue sie jederzeit aus den Dateien neu auf.

• 19 MCP-Tools für Notizen, Verknüpfungen, Suche, Graphenanalyse und Cluster-Verwaltung

• 6 Workflow-Prompts (plus passende Skills), die die Zettelkasten-Methode kodieren, damit du sie nicht in jeder Sitzung neu lernst

• BM25-Volltextsuche über Titel und Inhalt per SQLite FTS5

• Cluster-Erkennung findet aufkommende Themengruppen und unterstützt Strukturnotizen

• Sieben typisierte Verknüpfungen (reference, extends, refines, contradicts, questions, supports, related)

Python 3.10+ | macOS oder Linux

Rundgang

Related MCP server: vault-master-mcp

Schnellstart

1. Installieren

pipx install slipbox-mcp
# or, with uv:
uv tool install slipbox-mcp

Dadurch wird ein slipbox-mcp-Launcher auf deinen PATH gelegt (in ~/.local/bin). Dieser einzelne Befehl ist der gesamte MCP-Server: kein Klonen, keine PYTHONPATH-Variable, kein fest codierter venv-Python-Pfad. Alles unten verwendet ihn. Um es ganz ohne Installation auszuprobieren, führt uvx slipbox-mcp den Server in einer Wegwerf-Umgebung aus.

(Du arbeitest an Slipbox selbst? Siehe Entwicklung für das Einrichten mit Klonen und editierbarer Installation.)

2. Datenverzeichnis wählen

Eine einzige Variable, SLIPBOX_BASE_DIR, konfiguriert alles: Notizen landen in <base>/data/notes und der SQLite-Index in <base>/data/db/zettelkasten.db. Der Server erstellt diese beim ersten Start mit Berechtigungen nur für den Besitzer (0700).

Richte SLIPBOX_BASE_DIR (oder die einzelnen Pfade SLIPBOX_NOTES_DIR / SLIPBOX_DATABASE_PATH weiter unten) auf ein dediziertes Datenverzeichnis, das du kontrollierst, nicht auf einen gemeinsamen oder System-Speicherort. Diese Pfade werden unverändert verwendet: Der Server verwaltet den Notizbaum und den Index darunter und behandelt das Notizverzeichnis als Quelle der Wahrheit, wenn er den Index neu aufbaut.

# Example: use any absolute path you like
/Users/yourname/.local/share/mcp/slipbox

Verwende einen vollständigen absoluten Pfad. Ein führendes ~ wird in MCP-Client-Konfigurationsdateien nicht expandiert und würde ein buchstäbliches ~-Verzeichnis erzeugen.

3. Verbinde dich mit deinem MCP-Client

Claude Code (ein Befehl, keine Dateibearbeitung):

claude mcp add slipbox \
  --env SLIPBOX_BASE_DIR=/Users/yourname/.local/share/mcp/slipbox \
  -- slipbox-mcp

Claude Desktop (Konfigurationsdatei bearbeiten):

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

• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "slipbox": {
      "command": "slipbox-mcp",
      "env": {
        "SLIPBOX_BASE_DIR": "/Users/yourname/.local/share/mcp/slipbox"
      }
    }
  }
}

Desktop-PATH-Hinweis: Die macOS-Desktop-App erbt ~/.local/bin nicht immer in ihrem PATH, daher könnte das nackte "slipbox-mcp" nicht aufgelöst werden. Wenn der Server nicht startet, ersetze "command": "slipbox-mcp" durch den absoluten Pfad, der von which slipbox-mcp ausgegeben wird (normalerweise /Users/yourname/.local/bin/slipbox-mcp).

Andere MCP-Clients: Registriere slipbox-mcp als Serverbefehl mit SLIPBOX_BASE_DIR in dessen Umgebung. Der Befehl und die Umgebung sind überall gleich.

Setze anstelle von SLIPBOX_BASE_DIR einzelne absolute Pfade. Das optionale SLIPBOX_LOG_LEVEL ist eines von DEBUG, INFO, WARNING, ERROR.

"env": {
  "SLIPBOX_NOTES_DIR": "/Users/yourname/.local/share/mcp/slipbox/notes",
  "SLIPBOX_DATABASE_PATH": "/Users/yourname/.local/share/mcp/slipbox/data/db/zettelkasten.db",
  "SLIPBOX_LOG_LEVEL": "INFO"
}

4. Neustarten und überprüfen

Starte deinen Client neu (Claude Code lädt beim nächsten Start neu; beende Claude Desktop und öffne es erneut).

Frage deinen Agenten:

• „Erstelle eine Testnotiz über etwas“

• „Durchsuche meine slipbox nach test“

• „Finde verwaiste Notizen“

In Aktion

Das obige Bild ist die Kernschleife. Hier ist der Rest, was der Agent tut.

Proaktive Wartung

Der Agent liest die Ressource slipbox://maintenance-status zu Sitzungsbeginn und zeigt Cluster an, die organisiert werden müssen.

Volltextsuche

BM25-bewertete Suche über Notizen via slipbox_search_notes.

Wissensgraph: Zentrale Notizen

slipbox_find_central_notes zeigt die strukturellen Anker des Graphen – die Notizen, um die alles andere kreist.

Notizen-Analyse

Der Prompt analyze_note bewertet Atomarität, findet echte Verbindungen im vorhandenen Graphen, schlägt Tags vor und schreibt für Klarheit um.

Quellen-Zerlegung

Der Prompt knowledge_creation zerlegt einen Artikel in atomare Literaturnotizen mit korrekten Zitaten und Verknüpfungen.

Cluster-Erkennung

slipbox_get_cluster_report findet Gruppen gemeinsam auftretender Tags, denen eine Strukturnotiz fehlt. Bewertet nach Größe, Verwaisten-Anteil, Verknüpfungsdichte und Aktualität.

Strukturnotiz-Erstellung

slipbox_create_structure_from_cluster erstellt eine Strukturnotiz, verknüpft alle Mitgliedsnotizen und verwirft den Cluster.

Verwaiste Notizen

slipbox_find_orphaned_notes zeigt nicht integriertes Wissen – Kandidaten zum Verknüpfen oder Löschen.

Ähnliche Notizen

slipbox_find_similar_notes berechnet Ähnlichkeit aus gemeinsamen Tags, gemeinsamen Verknüpfungen und Inhaltsüberschneidungen.

Graph-Traversierung

slipbox_get_linked_notes zeigt typisierte Verknüpfungen von einer Hub-Notiz aus, gruppiert nach Verknüpfungstyp.

Wissenssynthese

Der Prompt knowledge_synthesis findet Brücken zwischen nicht verbundenen Bereichen und schlägt Synthesenotizen aus deinem vorhandenen Wissen vor.

Kein Lock-in: Einfache Dateien in Obsidian

Notizen sind einfaches Markdown. Öffne den Wissensspeicher in Obsidian und alles funktioniert – gerenderte Inhalte, Backlinks und der Wissensgraph.

Für einen Graphen, der die typisierten Verknüpfungen in Farbe darstellt (supports, extends, refines, ...) statt Obsidians untypisiertem integrierten Graphen, installiere das Begleit-Plugin Slipbox Semantic Graph – eine kraftbasierte Ansicht mit lesbaren Titeln und farbcodierten semantischen Verknüpfungstypen. Installiere es manuell aus der 0.1.0-Version: Kopiere main.js, manifest.json und styles.css in <vault>/.obsidian/plugins/slipbox-graph/ und aktiviere es dann unter Einstellungen → Community-Plugins. (Sobald es in das offizielle Verzeichnis aufgenommen wurde, kannst du es auch über Einstellungen → Community-Plugins → Durchsuchen → Suche nach "Slipbox Semantic Graph" installieren.) Es liest dieselben Frontmatter-id- und ## Links-Abschnitte, die der Server schreibt, daher ist keine zusätzliche Konfiguration erforderlich. Öffne die Ansicht mit dem Befehl Open semantic graph (Befehlspalette) oder dem git-fork-Symbol im Menüband.

Die Legende oben ordnet jeder Farbe einen Verknüpfungstyp zu (extends, refines, supports, contradicts, questions, related). Fokussiere eine Strukturnotiz und ihre Konstellation erscheint. Hier ist Contract Testing Knowledge Map mit den umkreisenden Mitgliedsnotizen:

Optional: Automatische Cluster-Erkennung

Die Cluster-Analyse scannt alle Notizen und berechnet Ähnlichkeitswerte. Wenn du sie täglich (6 Uhr) ausführst, werden Ergebnisse vorab berechnet, sodass slipbox_get_cluster_report() sofort zurückkehrt. Ohne Zeitplanung läuft die Cluster-Erkennung bei Bedarf, was bei großen Sammlungen langsamer ist.

Führe sie manuell nach Massenimporten, größeren Umstrukturierungen oder wenn du sofortige Ergebnisse möchtest, aus.

Cluster-Erkennung installieren (macOS)

chmod +x scripts/install-cluster-detection.sh
./scripts/install-cluster-detection.sh

Der Installer erkennt deinen Python-/venv-Pfad, erzeugt die LaunchAgent-Plist und lädt sie.

Manueller Test (Dateiüberwacher)

source .venv/bin/activate
python scripts/detect_clusters.py

Ausgabe gespeichert unter ~/.local/share/mcp/slipbox/cluster-analysis.json.

Cluster-Erkennung deinstallieren

./scripts/install-cluster-detection.sh --uninstall

Optional: macOS-Dateiüberwacher für automatische Indexierung

Der MCP-Server unterhält einen Datenbankindex für schnelles Suchen. Wenn du Notizen in Obsidian (oder einem anderen Editor) bearbeitest, wird die Datenbank veraltet, bis du slipbox_rebuild_index ausführst.

Der Dateiüberwacher läuft als Hintergrund-Daemon, überwacht dein Notizverzeichnis und baut den Index automatisch neu auf, wenn sich .md-Dateien ändern.

Verwende ihn, wenn du häufig Notizen in Obsidian bearbeitest und gleichzeitig Claude nutzt.

Dateiüberwacher installieren (macOS)

chmod +x scripts/install-file-watcher.sh
./scripts/install-file-watcher.sh

Der Installer erkennt deinen Python-/venv-Pfad, installiert bei Bedarf watchdog und lädt den LaunchAgent. Er startet bei der Anmeldung und wird bei Absturz neu gestartet.

Manueller Test

source .venv/bin/activate
python scripts/watch_notes.py

Bearbeite eine Notizdatei. Du solltest "rebuilding index..." in der Ausgabe des Überwachers sehen.

Status prüfen

launchctl list | grep slipbox.watcher

# View logs

tail -f ~/.local/share/mcp/slipbox/watcher.log

Dateiüberwacher deinstallieren

./scripts/install-file-watcher.sh --uninstall

Empfohlener System-Prompt

Slipbox bringt automatisch eine Grundkonfiguration mit: Jeder Client erhält bei der Verbindung die Server-Anweisungen, die abdecken, wie man die Werkzeuge richtig nutzt – Notiztypen, Verknüpfungssemantik, Qualitätsstandards und Kern-Workflows wie die Suche vor dem Erstellen. Diese fügst du nicht selbst hinzu.

docs/SYSTEM_PROMPT.md ist die Opt-in-Ebene darüber: die Autonomie- und Initiativ-Richtlinien, die ein Server nicht von sich aus beanspruchen sollte. Füge sie den Einstellungen deines Agenten oder dem System-Prompt hinzu, um Folgendes zu aktivieren:

• Automatische Wissenserfassung während Gesprächen

• Erkennung aufkommender Cluster beim Gesprächsstart

Werkzeug-Referenz

Kern-Notizoperationen

Verknüpfen

Suche & Entdeckung

Cluster-Analyse

Wartung

Referenz der Prompts

MCP-Prompts sind wiederverwendbare Workflow-Vorlagen, die die Zettelkasten-Methode kodieren, damit du sie nicht in jeder Sitzung neu erklären musst.

So rufst du sie auf: Slash-Befehle und Skills

Jeder Workflow wird auf zwei Arten ausgeliefert:

• MCP-Prompts: werden vom laufenden Server bereitgestellt.

• Skills: eigenständige Bündel (skills/<name>/), die denselben Workflow ausführen und eine Auslösung über natürliche Sprache ermöglichen.

Fünf der sechs Skills werden aus denselben PROMPT_*-Vorlagen generiert, die auch der Server verwendet (src/slipbox_mcp/server/descriptions.py), und CI schlägt fehl, wenn die eingecheckten skills/ von diesen Vorlagen abweichen. Der sechste, cluster-maintenance, wird direkt in scripts/build_skills.py verfasst, weil sein MCP-Prompt eine zur Laufzeit gerenderte Statusmeldung und kein wiederverwendbarer Workflow ist.

Slash-Befehle sind der zuverlässige Weg. Claude Code zeigt MCP-Prompts als /mcp__<server>__<prompt> an; tippe /mcp__slipbox-mcp__ für die Auswahl:

/mcp__slipbox-mcp__knowledge_creation
/mcp__slipbox-mcp__knowledge_exploration
/mcp__slipbox-mcp__knowledge_synthesis
/mcp__slipbox-mcp__knowledge_creation_batch
/mcp__slipbox-mcp__analyze_note
/mcp__slipbox-mcp__cluster_maintenance

(Installierte Skills stellen außerdem eigene Slash-Befehle über ihren Verzeichnisnamen bereit, z. B. /slipbox-analyze-note.)

Natürliche Sprache funktioniert, sobald der passende Skill installiert ist. Beschreibe einfach, was du möchtest:

Analyze this note for my slipbox: [paste note]

Add this to my slipbox: [paste article]

Synthesize my notes on attention and memory.

Die Auslösung über Prosa hängt davon ab, dass der Skill installiert ist und deine Formulierung zu seiner Beschreibung passt; falls es nicht funktioniert, nutze den Slash-Befehl. Die Aufforderung an das Modell, den „analyze_note“-Prompt namentlich zu verwenden, funktioniert nicht. Das Modell kann einen MCP-Prompt nicht namentlich aufrufen. Verwende einen Slash-Befehl oder lass einen Skill über natürliche Sprache auslösen.

Skills installieren

Claude Code findet Skills in .claude/skills/ (pro Projekt) oder ~/.claude/skills/ (global), nicht in einem einfachen skills/-Verzeichnis auf oberster Ebene. Verlinke oder kopiere die gewünschten Skills in einen Erkennungspfad (z. B. für dieses Projekt):

mkdir -p .claude/skills
ln -s ../../skills/slipbox-analyze-note .claude/skills/slipbox-analyze-note
# ...or copy the directories, or symlink all six

Claude Desktop benötigt jeden Skill als .skill-Bündel. Erstelle sie, dann lade sie hoch:

python scripts/build_skills.py     # writes dist/*.skill

Gehe zu Einstellungen → Skills → Skill hochladen und wähle die Bündel aus dist/ aus, die du möchtest. Jeder wird sowohl als Slash-Befehl als auch als Auslöser für natürliche Sprache installiert.

Nachdem du eine Prompt-Vorlage in descriptions.py bearbeitet hast, führe den Build erneut aus, um die Skills neu zu generieren.

Verknüpfungstypen

Notiztypen

Struktur- vs. Hub-Notiz: Eine Strukturnotiz organisiert einen Cluster von permanenten Notizen zu einem einzelnen Thema. Sie ist eine kuratierte Karte eine Ebene über den Notizen selbst. Eine Hub-Notiz arbeitet noch eine Ebene höher: Sie verlinkt auf Strukturnotizen (und gelegentlich auf wichtige permanente Notizen) über eine gesamte Wissensdomäne. Während eine Strukturnotiz die Frage „Was weiß ich über X?“ beantwortet, beantwortet eine Hub-Notiz die Frage „Wie ist mein Wissen über diese gesamte Domäne organisiert?“ Die meisten Zettelkästen benötigen nur eine Handvoll Hub-Notizen.

Dateiformat

Notizen werden als Markdown-Dateien mit YAML-Frontmatter gespeichert:

---
id: "20251217T172432480464000"
title: "Poetry Revision Principles"
type: structure
tags:
  - poetry
  - revision
  - craft
created: "2025-12-17T17:24:32"
updated: "2025-12-17T17:24:32"
---

# Poetry Revision Principles

Content here...

## Links

- reference [[20250728T125429845760000]] Member of structure

Du kannst diese Dateien direkt in einem beliebigen Texteditor oder in Obsidian bearbeiten. Führe slipbox_rebuild_index nach externen Bearbeitungen aus.

Aktualisierung

Nach dem Ziehen neuer Versionen starte Claude Desktop neu. Wenn die Versionshinweise Datenbankänderungen erwähnen, führe slipbox_rebuild_index einmal aus, um deine vorhandene Datenbank auf den neuesten Stand zu bringen.

Aktualisierung auf FTS5-Suche (jede Version nach dem FTS5-Release): Der Volltextsuchindex wird automatisch erstellt, wenn der Server mit einer neuen Datenbank startet. Bei vorhandenen Datenbanken wird die FTS5-Tabelle beim ersten Start erstellt, bleibt aber leer, bis du Folgendes ausführst:

slipbox_rebuild_index

Dies befüllt den BM25-Index aus deinen vorhandenen Notizen. Suchergebnisse werden erst nach diesem Schritt nach Relevanz sortiert.

Fehlerbehebung

Server wird in Claude Desktop nicht geladen

1. Bestätige, dass der Launcher auflösbar ist: which slipbox-mcp sollte einen Pfad ausgeben (normalerweise ~/.local/bin/slipbox-mcp).

2. Wenn es in deinem Terminal auflösbar ist, Desktop es aber trotzdem nicht starten kann, sieht die GUI-App ~/.local/bin nicht in ihrem PATH. Ersetze "command": "slipbox-mcp" durch den absoluten Pfad aus Schritt 1.

3. Prüfe die Claude-Desktop-Protokolle auf Fehler.

slipbox-mcp: command not found

Das Konsolenskript wurde nicht installiert oder ist nicht im PATH. Installiere es neu mit pipx install --editable . --force und überprüfe es dann mit which slipbox-mcp. Wenn das bin-Verzeichnis von pipx im PATH fehlt, führe pipx ensurepath aus und starte deine Shell neu.

Notizverzeichnis zeigt wörtlich auf ~/...

Wenn dein Notizverzeichnis relativ zum CWD bei ./~/... landet, hast du ~ in der JSON-Konfiguration verwendet. Claude Desktop expandiert ~ nicht. Ersetze es durch den vollständigen absoluten Pfad.

Suche liefert keine Ergebnisse

1. Der FTS5-Index ist möglicherweise nicht befüllt. Führe slipbox_rebuild_index einmal aus, um vorhandene Notizen zu indizieren.

2. Wenn du Notizen kürzlich außerhalb von Claude bearbeitet hast, ist der Index möglicherweise veraltet. Führe slipbox_rebuild_index aus.

slipbox_list_notes_by_date liefert leere Ergebnisse

Wenn start_date später als end_date liegt, werden keine Notizen gefunden und ein leeres Ergebnis zurückgegeben. Das ist erwartetes Verhalten, kein Fehler.

Datenbank nicht synchron

Wenn Notizen außerhalb des MCP-Servers bearbeitet wurden:

slipbox_rebuild_index

Cluster-Erkennung läuft nicht

launchctl list | grep slipbox.cluster-detection
# Should show: - 0 com.slipbox.cluster-detection

# Check logs

cat /tmp/slipbox-clusters.log

# Reinstall if needed

./scripts/install-cluster-detection.sh --uninstall
./scripts/install-cluster-detection.sh

Dateiüberwachung läuft nicht

launchctl list | grep slipbox.watcher
# Should show: - 0 com.slipbox.watcher

# Check logs

cat ~/.local/share/mcp/slipbox/watcher.log

# Reinstall if needed

./scripts/install-file-watcher.sh --uninstall
./scripts/install-file-watcher.sh

Aktualisierung von ZETTELKASTEN_*-Umgebungsvariablen

Wenn du zuvor ZETTELKASTEN_NOTES_DIR, ZETTELKASTEN_DATABASE_PATH oder andere ZETTELKASTEN_*-Variablen verwendet hast, werden diese nicht mehr gelesen. Benenne sie in ihre SLIPBOX_*-Entsprechungen um:

Der Server protokolliert eine Warnung, wenn alte Namen erkannt werden, migriert sie aber nicht automatisch.

Pfad des Cluster-Berichts ist nicht konfigurierbar

Der Cluster-Analysebericht wird unabhängig von SLIPBOX_BASE_DIR oder SLIPBOX_NOTES_DIR immer nach ~/.local/share/mcp/slipbox/cluster-analysis.json geschrieben. Wenn du nicht standardmäßige Pfade verwendest, liegt der Cluster-Bericht trotzdem am Standardort.

Installationsskripte sind nur für macOS

Die Skripte scripts/install-cluster-detection.sh und scripts/install-file-watcher.sh verwenden launchctl und ~/Library/LaunchAgents/, die es nur unter macOS gibt. Unter Linux musst du entsprechende systemd-Units oder Cron-Jobs manuell erstellen. Siehe die manuellen Testbefehle in den jeweiligen README-Abschnitten, um zu überprüfen, ob die zugrunde liegenden Python-Skripte auf deiner Plattform funktionieren.

Standardpfade sind relativ zum Arbeitsverzeichnis

Wenn SLIPBOX_NOTES_DIR und SLIPBOX_DATABASE_PATH nicht gesetzt sind, verwendet der Server standardmäßig data/notes und data/db/zettelkasten.db relativ zum aktuellen Arbeitsverzeichnis. Bei der Ausführung über Claude Desktop entspricht das CWD möglicherweise nicht deiner Erwartung. Setze in claude_desktop_config.json immer absolute Pfade, um dies zu vermeiden.

Entwicklung

Einrichtung

git clone https://github.com/jamesfishwick/slipbox-mcp.git
cd slipbox-mcp
uv venv && uv pip install -e ".[dev]"

Testen

Das Projekt hat drei Teststufen:

# Default: runs unit + contract tests (CI runs this)

pytest

# Run everything except LLM evals

pytest tests/ evals/tool_contracts/

# Run LLM evals (requires claude CLI authenticated)

pytest evals/llm/ -v

# Run LLM evals with a specific model

EVAL_MODEL=sonnet pytest evals/llm/ -v

# Lint

ruff check src/ evals/

Unit-Tests decken die interne Logik ab – Dienste, Repository, Modelle, Parsing.

Tool-Vertragstests überprüfen das Ausgabeformat der MCP-Tools, das die LLM sieht – parsebare Struktur, Verkettung (create -> search -> get) und hilfreiche Fehlermeldungen. Sie sind deterministisch und rufen keine LLM auf.

LLM-Evaluierungen senden Prompts über die claude-CLI an eine LLM, wobei der MCP-Server verbunden ist, und bewerten dann die Ergebnisse, indem sie den Datenbankzustand prüfen (erstellte Notizen, gesetzte Verknüpfungen, angewendete Tags). Sie testen, ob die LLM die Tools angesichts der Tool-Beschreibungen tatsächlich korrekt verwendet.

CI/CD

Branch-Schutz: Direkte Pushes auf main sind blockiert. Alle Änderungen laufen über PRs.

Die LLM-Eval-Suite ist teuer (~$3-5, ~10 Min.) und selbstgehostet, läuft also nie automatisch. Ein pfadbasierter Auslöser kann eine echte Prompt-Änderung nicht von einer kosmetischen Neuformatierung unterscheiden. Führen Sie sie bewusst aus, wenn Sie die Semantik von Prompts oder Tool-Beschreibungen ändern:

• Fügen Sie das run-llm-evals-Label zum PR hinzu. Sie läuft und läuft bei jedem Push erneut, solange das Label vorhanden ist.

• Oder lösen Sie sie manuell über den Tab „Actions“ aus (workflow_dispatch).

• Oder führen Sie sie lokal ohne den Runner aus: pytest evals/llm/ -v.

Ohne Label oder manuelle Auslösung wird der Job übersprungen (kein Runner wird zugewiesen, keine Kosten).

Anpassen des Eval-Setups

Wenn Sie keinen selbstgehosteten Runner möchten: Entfernen Sie .github/workflows/llm-evals.yml und führen Sie pytest evals/llm/ -v lokal aus, bevor Sie Prompt-Änderungen mergen.

Wenn Sie LLM-Evals bei jedem PR automatisch möchten: Fügen Sie einen pull_request-Auslöser mit dem entsprechenden paths:-Filter hinzu und entfernen Sie das Label-Gate im if: des Jobs. Rechnen Sie aber mit unbeabsichtigten Auslösungen durch reine Formatierungsänderungen.

So ändern Sie das Standard-Eval-Modell: Setzen Sie EVAL_MODEL in Ihrer Umgebung oder in der Workflow-Datei. Standard ist haiku aus Geschwindigkeits-/Kostengründen.

So richten Sie einen selbstgehosteten Runner ein:

# Get a registration token

gh api repos/OWNER/REPO/actions/runners/registration-token -X POST -q '.token'

# Download and configure

mkdir -p ~/.github-runners/slipbox-mcp && cd ~/.github-runners/slipbox-mcp
curl -sL -o actions-runner.tar.gz https://github.com/actions/runner/releases/latest/download/actions-runner-osx-arm64-2.325.0.tar.gz
tar xzf actions-runner.tar.gz
./config.sh --url https://github.com/OWNER/REPO --token <TOKEN> --unattended
nohup ./run.sh &

Veröffentlichung auf PyPI

Releases sind automatisiert. Der Release-Workflow (.github/workflows/release.yml) führt bei jedem Push auf main release-please aus und veröffentlicht über PyPI Trusted Publishing (OIDC, sodass kein API-Token in den Repo-Secrets gespeichert wird).

Der Ablauf (Sie bearbeiten niemals eine Version von Hand oder pushen einen Tag):

1. Landen Sie Änderungen auf main mit Conventional Commit-Nachrichten (feat: → Minor-Bump, fix: → Patch, feat!:/BREAKING CHANGE: → Major). Die Commit-Hooks des Repos erzwingen diese Form bereits.

2. release-please hält einen dauerhaften „Release-PR“ offen, der den nächsten Versionssprung (in src/slipbox_mcp/__init__.py) und die aus diesen Commits abgeleiteten CHANGELOG.md-Einträge ansammelt.

3. Wenn Sie bereit sind zu veröffentlichen, mergen Sie den Release-PR. Das taggt das Release (v<version>) und baut im selben Workflow-Lauf das sdist + Wheel, führt twine check aus und veröffentlicht auf PyPI.

Ein Release zu erstellen ist also ein Klick: Mergen Sie den PR des Bots. Sonst nichts.

Commit-Typen bestimmen die Version. Geben Sie sie also genau an. Der Versionssprung wird mechanisch aus den Conventional-Commit-Präfixen seit dem letzten Release berechnet, nicht aus der Größe der Änderung. Reservieren Sie feat:/fix: für Änderungen am ausgelieferten Paket; verwenden Sie für alles andere die nicht veröffentlichenden Typen:

Ein Stapel mit nur nicht veröffentlichenden Commits erzeugt überhaupt keinen Release-PR. Der Titel des Squash-Merges ist der Commit, den release-please liest, also zählt das Präfix des PR-Titels. Beschriften Sie ihn nach dem, was das Paket gewinnt, nicht nach dem aufgewendeten Aufwand.

Einmalige Einrichtung (für dieses Repo bereits erledigt, für Forks dokumentiert):

1. Registrieren Sie auf PyPI einen Pending Trusted Publisher für das Projekt slipbox-mcp: Owner: jamesfishwick · Repository: slipbox-mcp · Workflow: release.yml · Environment: release. Alle vier müssen exakt übereinstimmen.

2. Erstellen Sie in GitHub eine Umgebung namens release (Settings → Environments). Wenn Sie ihre Deployment-Refs einschränken, fügen Sie eine Tag-Regel v* hinzu (eine Branch-Regel mit demselben Namen passt nicht auf den Tag).

Die Version ist genau einmal definiert, in src/slipbox_mcp/__init__.py (release-please erhöht sie; der Marker # x-release-please-version teilt mit, welche Zeile gemeint ist). pyproject.toml (dynamic = ["version"]) und server_version des Servers lesen beide daraus, sodass nichts synchron gehalten werden muss; der Tag, den release-please erstellt, stimmt konstruktionsbedingt immer mit der Paketversion überein.

Um einen Build ohne Veröffentlichung zu proben, führen Sie ihn von Hand aus: python -m build && twine check dist/* (und twine upload --repository testpypi dist/* mit einem TestPyPI-Token, um den Upload als Trockenlauf auszuführen).

Gemeinsame Prompt-Konstanten

Alle Tool-Beschreibungen und Prompt-Vorlagen liegen in src/slipbox_mcp/server/descriptions.py. Sowohl der MCP-Server als auch die Eval-Tests importieren aus dieser einzigen maßgeblichen Quelle. Wenn Sie einen Prompt ändern, testen die Evals, ob das LLM mit der neuen Formulierung weiterhin korrekt funktioniert.

Debug-Logging

SLIPBOX_LOG_LEVEL=DEBUG python -c "from slipbox_mcp.main import main; main()"

CLI-Tool

Der Befehl slipbox bietet Terminalzugriff für mechanische Vorgänge:

slipbox status          # Overview of notes, tags, orphans, pending clusters
slipbox search <query>  # Find notes by text
slipbox clusters        # Show pending structure note candidates
slipbox orphans         # List unconnected notes
slipbox rebuild         # Rebuild index (add --clusters to refresh cluster analysis)
slipbox export <id>     # Export note markdown to stdout
slipbox tags            # List all tags with usage counts

Installation: pipx install --editable . (fügt slipbox zu Ihrem PATH hinzu)

Experimentell: Slipbox als Agenten-Gedächtnis

Eine ungetestete Hypothese, keine empfohlene Einrichtung. Alles oben Genannte hilft einem Agenten, Ihr Wissen zu verwalten. Das kehrt es um: Der Agent nutzt eine Slipbox als sein eigenes persistentes Gedächtnis über Sitzungen hinweg, anstelle von nativem Speicher oder einer Regeldatei.

Das Modell hat kein Gedächtnis zwischen Sitzungen, also ist die Slipbox der einzige Kanal, den eine Sitzung für die nächste hinterlässt. Es schreibt Briefings für einen kalten Nachfolger (einen Fehler und warum, eine wiederkehrende Einschränkung, eine Korrektur, eine mühsam errungene Tatsache), taggt sie mit agent-memory und durchsucht dieses Tag, bevor es handelt. Die Wette ist, dass ein vernetztes Gedächtnis eine flache Regeldatei schlägt, weil man es durch Traversal abruft.

Drei Dinge sollten Sie zuerst wissen: Die Namespace-Isolation ist eine Tag-Konvention, nicht erzwungen, also führen Sie es gegen eine separate Slipbox-Instanz aus; „memory“ ist eine irreführende Bezeichnung, da nichts außer den Notizen selbst bestehen bleibt; und die Wachstums-Disziplin ist der unbewiesene Teil, also rechnen Sie beim ersten Lauf mit Ausuferung. Vollständige Ausarbeitung und Einschränkungen: Slipbox as Agent Self-Memory.

Dokumentation

Mitwirken

Siehe CONTRIBUTING.md für Einrichtungsanweisungen, Codestandards und wie Sie Änderungen einreichen.

Roadmap

Siehe ROADMAP.md für geplante Funktionen und die zukünftige Ausrichtung.

Sponsor

Wenn Ihnen slipbox-mcp nützlich ist, erwägen Sie, das Projekt zu sponsern.

Lizenz

MIT