| 1 | # Agent Notes MCP |
| 2 | |
| 3 | [MCP](https://modelcontextprotocol.io)-сервер для **hot-заметок** (`agent-notes.md`) и **слоя `knowledge/`** (чтение/запись карточек и плейбуков). Версия **2.1** (Core **AIGuiders.AgentNotes.Core** 2.1.0, multi-root read-only) настраивается через **локальный TOML** (`--config`), как DBHub. |
| 4 | |
| 5 | ## Быстрый старт |
| 6 | |
| 7 | ```bash |
| 8 | git clone https://github.com/AI-Guiders/agent-notes-mcp.git |
| 9 | cd agent-notes-mcp |
| 10 | dotnet build |
| 11 | dotnet publish AgentNotesMcp.csproj -c Release -o publish |
| 12 | ``` |
| 13 | |
| 14 | Скопируй и отредактируй пример конфига: **`config/agent-notes-mcp.toml`** (пути `[knowledge.roots]`, `[workspace]`). После `publish-and-deploy.ps1` тот же файл попадает рядом с exe. |
| 15 | |
| 16 | В **`mcp.json`**: |
| 17 | |
| 18 | ```json |
| 19 | { |
| 20 | "mcpServers": { |
| 21 | "agent-notes": { |
| 22 | "command": "D:\\agent-notes-mcp\\AgentNotesMcp.exe", |
| 23 | "args": ["--config", "D:/agent-notes-mcp/agent-notes-mcp.toml"], |
| 24 | "env": {} |
| 25 | } |
| 26 | } |
| 27 | } |
| 28 | ``` |
| 29 | |
| 30 | Без **`--config`** процесс завершится с ошибкой (fail fast). Переменная **`AGENT_NOTES_CONFIG`** — альтернатива пути к TOML. |
| 31 | |
| 32 | Публичный срез KB (только чтение) — **[kb-public](https://github.com/KarataevDmitry/kb-public)**. Подробнее по тулам — **[docs/MCP-TOOLS.md](docs/MCP-TOOLS.md)**. |
| 33 | |
| 34 | ## Лицензия |
| 35 | |
| 36 | Код и документация **этого репозитория** — **MIT** ([`LICENSE`](LICENSE)). Тексты **KB** как контент — не MIT: публичный срез **[kb-public](https://github.com/KarataevDmitry/kb-public)** и [`knowledge/README.md` там](https://github.com/KarataevDmitry/kb-public/blob/main/knowledge/README.md). Сторонние пакеты — **[docs/THIRD-PARTY-NOTICES.md](docs/THIRD-PARTY-NOTICES.md)**. |
| 37 | |
| 38 | Общая логика хранения — библиотека **[AIGuiders.AgentNotes.Core](https://www.nuget.org/packages/AIGuiders.AgentNotes.Core)** 2.x ([исходники](https://github.com/AI-Guiders/AIGuiders.AgentNotes.Core)), MIT. |
| 39 | |
| 40 | ## Документация |
| 41 | |
| 42 | | Что | Где | |
| 43 | |-----|-----| |
| 44 | | Имена тулов, аргументы, примеры | **[docs/MCP-TOOLS.md](docs/MCP-TOOLS.md)** и `mcp-tools.manifest.json` | |
| 45 | | Локальный TOML (`--config`) | **[docs/adr/014-agent-notes-local-settings-toml-v1.md](docs/adr/014-agent-notes-local-settings-toml-v1.md)** | |
| 46 | | Правила для `.cursor/rules` (Integrity POST, канон KB) | **[docs/cursor-rules-examples.md](docs/cursor-rules-examples.md)** | |
| 47 | | ADR по MCP и KB | **[docs/adr/](docs/adr/)** (канон также в репо **agent-notes**, `knowledge/adr/`) | |
| 48 | | Чистая установка (новый пользователь) | Playbook: `knowledge/domains/agent-operations/playbook-knowledge-stack-clean-setup-v1.md`; шаблоны: `knowledge/templates/newcomer/` (kb-public) | |
| 49 | | Сборка и релизы (PowerShell), зеркала Git | **[docs/publishing-and-ci.md](docs/publishing-and-ci.md)** | |
| 50 | |
| 51 | ## Возможности (сжато) |
| 52 | |
| 53 | - **Заметки:** атомарная запись, ревизии в `.revisions/`, поиск, rollback. |
| 54 | - **Hot-context:** `read_hot_context`, `extract_from_archive`, `compact_hot_context`, `memory_health`, `route_context`. |
| 55 | - **Knowledge:** `read_knowledge_file`, `write_knowledge_file`, … — пути относительно `knowledge/`; корень — **`knowledge_path`** в туле или **primary root** из TOML. |
| 56 | - **Контракты:** `KB-V2-CONTRACT.md`, `coexistence-framework-v1.md` — в репозитории канона. |
| 57 | |
| 58 | Полнотекст по Markdown-дереву канона **не** в этом процессе: для поиска — **[Hybrid Codebase Index](https://github.com/KarataevDmitry/hybrid-codebase-index)**. |
| 59 | |
| 60 | ## Где лежит `agent-notes.md` |
| 61 | |
| 62 | При запущенном MCP с **`--config`**: **`{primary knowledge root}/agent-notes.md`** (см. `[knowledge]` в TOML). |
| 63 | |
| 64 | Иначе (in-proc / тесты без runtime): **`AGENT_NOTES_FILE`** → иначе **`workspace_path/.cascade-ide/agent-notes.md`**. Ревизии — рядом с каталогом файла: **`.revisions/*.md`**. |
| 65 | |
| 66 | ## Слой `knowledge/` |
| 67 | |
| 68 | - **`knowledge_path`** в вызове тула — явный корень репозитория с каталогом **`knowledge/`**. |
| 69 | - Без аргумента — **primary root** из **`--config`** (`[knowledge].primary` → `[knowledge.roots]`). |
| 70 | - **`file_path`:** только внутри `knowledge/`, без `..` и абсолютных путей. |
| 71 | |
| 72 | Пример TOML и схема: `knowledge/work/local/agent-notes.workspace.example.toml` в репозитории **agent-notes** (канон). |
| 73 | |
| 74 | ## Workspace scope map |
| 75 | |
| 76 | Секция **`workspace-scope-map-v1`** в hot-файле и файлы из **`[workspace]`** в TOML (`scope_map`, `scope_aliases`). Дефолты для нейтрального example — embedded в **AgentNotes.Core** (`agent-notes-mcp.defaults.toml`); см. **`docs/adr/008-workspace-scope-map-resolution.md`**. |
| 77 | |
| 78 | **`workspace_path`** в аргументах тула — текущий проект в Cursor (longest-prefix match по карте). |
| 79 | |
| 80 | ## Два разных «корня» |
| 81 | |
| 82 | | | Назначение | Откуда путь | |
| 83 | |---|------------|-------------| |
| 84 | | **Hot-файл** | секции, `read_hot_context`, `route_context` | primary root из **`--config`** (или `AGENT_NOTES_FILE` / `.cascade-ide` без runtime) | |
| 85 | | **`knowledge/`** | read/write knowledge | **`knowledge_path`** или primary из TOML | |
| 86 | |
| 87 | Один TOML с primary на клон **agent-notes** согласует hot-файл и **`knowledge/`**. |
| 88 | |
| 89 | ## Участие |
| 90 | |
| 91 | Issues и PR — на **GitHub**: [AI-Guiders/agent-notes-mcp](https://github.com/AI-Guiders/agent-notes-mcp). |
| 92 | |
| 93 | Обновить описание тулов из кода: |
| 94 | |
| 95 | ```bash |
| 96 | dotnet run --project tools/ExportMcpManifest -- --write |
| 97 | ``` |
| 98 | |
| 99 | (рабочий каталог — корень репозитория). |
| 100 | |