ADR 014 (MCP): Локальные настройки — TOML по --config (релиз 2.0)

Статус: Proposed
Дата: 2026-05-16
Обновлено: 2026-05-16 — breaking MCP 2.0: обязательный --config, Tomlyn, без legacy env/META JSON.

Канонический текст (KB): knowledge/adr/013-agent-notes-mcp-local-settings-toml-v1.md (репо agent-notes), в т.ч. R7 — major 2.0.

Связанные ADR

Резюме

• MCP 2.0: один локальный TOML по --config в mcp.json (как DBHub), без walk-up и без AGENT_NOTES_CANON_PATH.
• Секции: [knowledge], [workspace], [status]; version = 1 в файле — схема TOML, не semver продукта.
• Breaking: canon_path → knowledge_path; embedded defaults + merge Tomlyn.
• До релиза 1.x — env + META JSON; после — только TOML.

Контекст для разработчиков MCP

Как DBHub (--config path/to/config.toml в mcp.json), без автопоиска по workspace:

"agent-notes": {
  "command": "D:\\agent-notes-mcp\\AgentNotesMcp.exe",
  "args": ["--config", "D:/path/agent-notes-mcp.local.toml"],
  "env": {}
}

Локальный TOML (version = 1 в файле): [knowledge], [workspace], [status]. Появляется только в MCP 2.0. До релиза 1.x — env + META JSON, без TOML.

Полная схема и список breaking — KB ADR 013 (R3, R7).

Реализация (целевая)

Приоритет пути к конфигу (2.0)

1. CLI --config (абсолютный путь рекомендуется)
2. Env AGENT_NOTES_CONFIG — тесты / хосты без args
3. Иначе — ошибка запуска с текстом «нужен --config» (legacy AGENT_NOTES_* не в supported path 2.0)

Walk-up: не реализуем (KB ADR 013).

Приоритет (1.x, до 2.0)

Как сейчас: env AGENT_NOTES_*, META JSON — без изменений до тега 2.0.0.

Поведение при ошибке config

Tomlyn

В AgentNotes.Core; тесты с --config на fixture в AgentNotesMcp.Tests.

2.0: [workspace] вместо META JSON; [knowledge] для корней; ToolCatalog — knowledge_path; LocalSettings / резолвер без имён Canon* в новом API (допустимы private alias на переходе внутри PR).

Миграция 1.x → 2.0 (чеклист)

1. Собрать/скачать agent-notes-mcp 2.0.x.
2. Создать TOML из knowledge/work/local/agent-notes.workspace.example.toml (схема файла version = 1).
3. В mcp.json: "args": ["--config", "<abs path>"], "env": {}.
4. В правилах и playbook: canon_path → knowledge_path.
5. Удалить knowledge/META/mcp-resolve-paths-v1.json из primary KB (после проверки путей в [workspace]).

Техдолг и приборка в коде (релиз 2.0)

Сейчас логика в agent-notes-core + тонкий AgentNotesMcp; имена застряли на эпохе env + META JSON. 2.0 — единственный разумный момент для переименований и выкидывания legacy (не тащить «canon» в новый TOML-loader).

Публичный контракт MCP (breaking)

AgentNotes.Core

Дубликаты .cs в корне agent-notes-mcp — удалены при выносе Core (зеркало больше не в репо).

AgentNotesMcp

Связанные репозитории (не блокер MCP, но тот же major по смыслу)

• Cascade IDE (McpAgentNotesService, IdeMcpCommandExecutor): параметр canon_path в JSON команд — обновить при поднятии ссылки на Core 2.0.
• Cursor rules / KB playbook: canon_path в текстах.
• agent-notes KB: удалить knowledge/META/mcp-resolve-paths-v1.json после кода.

Что не переименовывать в 2.0 (осознанно)

• Имена файлов в репо (agent-notes.md, каталог knowledge/) — без изменений.
• ADR 012 title «multi-canon» — исторический документ; в новом коде не продлевать термин.

[[knowledge.read_only]] — схема в 2.0, маршрутизация позже

Смысл и роли корней — KB 012-multi-canon-workspace-resolution-v1.md (исторически «secondary canon»). В TOML это не то же самое, что [knowledge.roots]:

Пример (опционально в --config; в шаблоне config/agent-notes-mcp.toml — закомментирован):

[[knowledge.read_only]]
id = "group"
path = "D:/clones/AI-Guiders/kb"

Релиз 2.0.0 (фактически в коде):

До multi-KB секцию можно не заполнять — поведение как с одним primary. Обязательный минимум конфига: [knowledge] + [workspace] (или embedded defaults для [workspace]).

Следующий шаг (2.1, ADR 015): резолв knowledge_root_id → primary (user) или read-only (group); write_* только в primary; status read_only_routing_enabled. Фаза 2: overlay group в route_context.

Критерии принятия

• mcp.json с --config → тот же primary KB root, что раньше через AGENT_NOTES_CANON_PATH.
• Информационная версия сборки начинается с 2.0.
• env: {} достаточно при полном TOML.
• Unit-тесты: valid fixture; missing file + --config → fail fast.

Открытые вопросы (MCP)

1. Относительный --config от cwd — разрешить с warning или только absolute (рекомендация KB: absolute).