agent-notes-mcp

agent-notes-mcp — это локальный stdio MCP-сервер для безопасного поиска и редактирования личных Markdown-заметок из MCP-клиентов, таких как Codex.

Используется обычный полнотекстовый поиск по именам файлов, YAML frontmatter и телу Markdown. Векторная БД и модели эмбеддингов не требуются.

Основные функции

• поиск, перечисление и чтение Markdown-заметок в заданном корне;

• создание, дополнение, замена и перемещение заметок в корне с правом записи;

• обнаружение конфликтов с помощью SHA-256 при замене и перемещении;

• безопасное массовое обновление явно размеченных блоков Markdown;

• произвольные массовые обновления, фиксация времени обновления, activity log;

• не предоставляются операции удаления и ожидание сетевых подключений.

Границы доступа и гарантии при обновлении описаны в модели безопасности.

Related MCP server: Notes — local markdown knowledge base

Требования

• Python 3.14 и выше

• uv

Установка

При установке из локального checkout:

uv tool install .

При установке из ветки main на GitHub:

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

Если нужно использовать конкретный коммит или тег, добавьте @<ref> в конец URL.

Настройка

Скопируйте пример конфигурации и замените каждый путь на каталог, которым управляете вы.

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

read_roots разрешает поиск и чтение. write_roots разрешает поиск, чтение и редактирование и должен находиться внутри корня, доступного для чтения. Начните с узкого корня для записи, например inbox или memos.

Регистрация в Codex

Зарегистрируйте установленную команду как stdio MCP-сервер.

[mcp_servers.agent_notes]
command = "agent_notes"

Если используется исходный checkout, укажите файл конфигурации явно.

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

Первые 5 минут

Откройте новый тред в Codex и попросите сделать следующее.

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

Codex может использовать MCP-инструменты, такие как list_roots, search_notes, read_note. Когда попробуете запись, попросите создать новый тестовый Markdown-файл внутри узкого write_roots, разрешённого в настройках.

Если вы используете заметки для передачи контекста между несколькими репозиториями разработки, обратитесь к примеру проектного контекста для Codex и примеру навыка, который можно скопировать и адаптировать. Это применение необязательно; сервер не навязывает размещение или формат заметок.

Безопасные обновления

Перед заменой или перемещением существующей заметки прочитайте её и укажите полученный sha256 как expected_sha256. Если за это время содержимое изменилось, сервер не выполнит перезапись и отклонит обновление.

Чтобы ограничить область, в которой разрешено обновление, заключите её в управляемые блоки.

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

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

update_managed_blocks обновляет только те управляемые блоки, структура которых прошла проверку. batch_update_notes сначала проверяет все обновления затронутых заметок и только затем начинает запись.

Разработка

uv sync --all-groups
uv run pytest

Лицензия

MIT

О разработке

Этот проект использует Codex в качестве помощника при разработке. Проверку содержимого и решения перед публикацией выполняет мейнтейнер.