mcp-notes-server

Ein MCP-Server, der einem KI-Agenten einen durchsuchbaren Vault für Markdown-Notizen bereitstellt: sechs Tools für ein flaches Verzeichnis von .md-Dateien mit YAML-artigem Frontmatter.

Notizen bleiben auf der Festplatte als schlichtes Markdown erhalten. Nichts ist in einer Datenbank eingesperrt, sodass dieselben Dateien mit deinem Editor, grep und git funktionieren.

~/notes/
├── pad-thai.md
├── sourdough-starter.md
└── weekly-review.md

Tools

Installation

npm install
npm run build

Verwendung mit einem MCP-Client

Füge es zur Server-Konfiguration deines Clients hinzu — für Claude Desktop die claude_desktop_config.json:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-notes-server/dist/src/index.js", "--vault", "/absolute/path/to/notes"]
    }
  }
}

Das Vault-Verzeichnis wird in dieser Reihenfolge ermittelt: --vault <dir>, dann $NOTES_VAULT, dann ~/notes. Es wird beim Start erstellt, falls es nicht existiert.

Designhinweise

Slugs sind die Identität, und sie werden validiert. Eine Notiz liegt unter <vault>/<slug>.md, und jeder Slug wird gegen /^[a-z0-9]+(?:-[a-z0-9]+)*$/ geprüft, bevor er das Dateisystem erreicht. Genau das macht read_note({slug: "../../.ssh/id_rsa"}) unmöglich statt bloß unwahrscheinlich — eine Allowlist, kein Escaping-Durchlauf. Slugs sind zudem über Updates hinweg stabil: Die Datei bei einer Titeländerung umzubenennen würde jeden Slug ungültig machen, den das Modell noch von einem früheren Tool-Aufruf hat.

Tool-Fehler sind Daten, keine Ausnahmen. „Keine Notiz mit Slug X“ kommt als normales Tool-Ergebnis mit isError: true zurück, sodass das Modell es liest und sich selbst korrigiert. Wenn der Fehler geworfen würde, sähe der Client einen Protokollfehler, von dem sich das Modell nicht erholen kann. Echte Bugs (alles, was kein VaultError ist) werden weiterhin geworfen, damit sie laut und deutlich bleiben.

Die Suche basiert auf gewichteter Termhäufigkeit. Ein Begriff im Titel zählt dreifach und ein Begriff in einem Tag zählt doppelt, sodass die Suche nach sourdough eine Notiz über Sauerteig höher einstuft als eine, die ihn nur beiläufig erwähnt. Sie ist bewusst einfach gehalten — kein Index, der synchron gehalten werden muss, und ein Vault mit ein paar tausend Notizen wird in Millisekunden durchsucht.

Der Vault weiß nichts über MCP. src/vault.ts ist einfacher Dateisystem-Code, src/server.ts ist die MCP-Anbindung und src/index.ts ist der stdio-Einstiegspunkt. Diese Trennung ist der Grund, warum sich der Vault direkt testen lässt und der Server über einen echten MCP-Client auf einem In-Memory-Transport getestet werden kann — ohne Subprozess und ohne Mocks.

Entwicklung

npm test          # 46 tests, vitest
npm run typecheck # tsc --noEmit
npm run build     # emit to dist/

Die Tests decken den Vault direkt ab (test/vault.test.ts) und den Server End-to-End über einen echten MCP-Client auf InMemoryTransport (test/server.test.ts), sodass Tool-Schemas, Argumentvalidierung und Ergebnisstrukturen alle geprüft werden — nicht nur die dahinterliegende Logik.

Lizenz

MIT