agent-notes-mcp

agent-notes-mcp ist ein lokaler stdio-MCP-Server, mit dem MCP-Clients wie Codex persönliche Markdown-Notizen sicher durchsuchen und bearbeiten können.

Er verwendet die normale Volltextsuche über Dateinamen, YAML-Frontmatter und Markdown-Text. Eine Vektor-Datenbank oder Embedding-Modelle sind nicht erforderlich.

Hauptfunktionen

• Markdown-Notizen im konfigurierten Root suchen, auflisten und lesen

• Notizen in schreibbaren Roots erstellen, ergänzen, ersetzen und verschieben

• Konflikterkennung mit SHA-256 beim Ersetzen und Verschieben

• Sicheres Batch-Update explizit markierter Markdown-Blöcke

• Beliebige Batch-Updates, Records of Bearbeitungszeitpunkte und Activity-Log

• Keine Löschoperationen und kein Netzwerk-Listener

Zu den Zugriffsgrenzen und den Garantien beim Update siehe das Sicherheitsmodell.

Related MCP server: Notes — local markdown knowledge base

Voraussetzungen

• Python 3.14 oder höher

• uv

Installation

Bei der Installation aus einem lokalen Checkout:

uv tool install .

Bei der Installation aus dem main-Branch von GitHub:

uv tool install git+https://github.com/mitszo/agent-notes-mcp.git

Bei Verwendung eines bestimmten Commits oder Tags hängen Sie @<ref> an das Ende der URL an.

Konfiguration

Kopieren Sie das Beispiel und ersetzen Sie die Pfade durch Verzeichnisse, die Sie selbst verwalten.

mkdir -p ~/.config/agent-notes-mcp
cp config.example.toml ~/.config/agent-notes-mcp/config.toml

read_roots erlauben das Suchen und Lesen. write_roots erlauben das Suchen, Lesen und Bearbeiten und müssen innerhalb eines lesbaren Roots liegen. Beginnen Sie zunächst mit einem engen Schreib-Root wie inbox oder memos.

Registrierung in Codex

Registrieren Sie das installierte Kommando als stdio-MCP-Server.

[mcp_servers.agent_notes]
command = "agent_notes"

Wenn Sie ein Source-Checkout verwenden, geben Sie die Konfigurationsdatei explizit an.

[mcp_servers.agent_notes]
command = "uv"
args = ["run", "agent_notes", "--config", "/absolute/path/to/config.toml"]

Die ersten 5 Minuten

Öffnen Sie einen neuen Thread in Codex und bitten Sie ihn zunächst um Folgendes:

agent_notes で設定済みの root を確認し、ノートを検索できるか試してください。

Codex verwendet MCP-Tools wie list_roots, search_notes und read_note. Wenn Sie Schreibvorgänge ausprobieren möchten, bitten Sie besessen, eine neue Test-Markdown-Datei in den write_roots anzulegen, die in der Konfiguration erlaubt sind.

Möchten Sie Notizen für die Übergabe über mehrere Entwicklungsrepositories nutzen, schauen Sie sich das Beispiel für Codex-Projektkontext und das Beispiel-Skill an, das Sie kopieren und anpassen können. Diese Praxis ist optional und kein Server erzwingt weder den Ablageort noch das Format der Notizen.

Sichere Updates

Vor dem Ersetzen oder Verschieben einer vorhandenen Notiz müssen Sie die Notiz zuerst lesen und den zurückgegebenen sha256 angegeben, der als expected_sha256. Wurde der Inhalt in der Zwischenzeit geändert, verweigert der Server die Aktualisierung und überschreibt nicht.

Möchten Sie den in einer Notiz erlaubten Update-Bereich einschränken? Ja – umschließen Sie ihn mit verwalteten Blöcken.

<!-- agent-notes:managed next-actions -->
## 次の行動

- 下書きを確認する
<!-- /agent-notes:managed next-actions -->

update_managed_blocks aktualisiert nur verwaltete Blöcke, deren Struktur validiert werden konnte. batch_update_notes validiert alle vorgesehenen Änderungen, bevor es mit dem Schreiben beginnt.

Entwicklung

uv sync --all-groups
uv run pytest

Lizenz

MIT

Über dieses Projekt

Dieses Projekt verwendet Codex zur Unterstützung der Entwicklung. Die Prüfung und Entscheidungen zum Inhalt vor der Veröffentlichung liegen bei den Maintainern.