@znt/mcp 1.1.0 → 2.0.1

package/AGENTS_EXAMPLE.md

@@ -0,0 +1,50 @@
+# Recommended Znt MCP workflow
+
+Этот фрагмент можно адаптировать для инструкций AI-агента проекта.
+
+## Выбор инструмента
+
+1. В начале работы вызови `setup` без параметров. Покажи пользователю
+   доступные режимы и не выбирай провайдера или передачу данных внешнему API
+   без его решения. После настройки проверь `setup_status`.
+2. Затем вызови `status`, при необходимости передав
+   абсолютный `project_path` открытого workspace. Если
+   `is_current_project=false`, вызови `scan` с тем же путём,
+   затем проверяй status до завершения scan. Если daemon уже индексирует
+   родительский каталог, вложенный workspace получает `coverage=ancestor` и
+   повторно не сканируется.
+3. Точный символ, функция, класс, CamelCase или snake_case:
+   `search` с `mode: "lexical"`.
+4. Описание поведения или архитектурного назначения:
+   `search` с `mode: "hybrid"` и подходящим boost/filter.
+5. Аналог существующей реализации:
+   `similar`.
+6. Call/dependency graph или путь между символами:
+   `graph`.
+7. Структура известного файла:
+   `outline` до чтения файла целиком.
+8. Ошибки scan/index/daemon:
+   `logs`.
+
+## Проверка результата
+
+- Graph edges и semantic roles являются сильными подсказками, но критические
+  выводы нужно сверять с исходным кодом.
+- Пустые callers/callees не доказывают отсутствие вызовов: запросите subgraph.
+- При ambiguous symbol повторите запрос с квалифицированным именем кандидата.
+- Для exhaustive или regex-поиска используйте локальный `rg` после Znt.
+- Не смешивайте точный code token и длинное смысловое описание в одном hybrid
+  query; разделите exact lexical и behavioral hybrid запросы.
+- Не используйте HTTP route как graph symbol: сначала найдите handler.
+
+## Пример последовательности
+
+```text
+1. setup и подтверждение выбранного пользователем режима
+2. project status и при необходимости scan current project
+3. lexical search по имени entrypoint
+4. file outline файла entrypoint
+5. subgraph от найденного qualified name
+6. hybrid search по недостающему поведению
+7. проверка ключевых мест по исходникам
+```

package/README.md

@@ -1,140 +1,509 @@
-# Znt MCP Adapter ([@znt/mcp](https://www.npmjs.com/package/@znt/mcp))
+# @znt/mcp
+
+Локальный Model Context Protocol server для Znt. Он публикует инструменты
+поиска и анализа кода через MCP stdio и вызывает `znt-core` напрямую через
+`znt-sdk-nodejs`.
+
+```text
+AI client / IDE
+      │ MCP over stdio
+      ▼
+znt-mcp-server (Node.js)
+      │ znt-sdk-nodejs
+      │ JSON-RPC 2.0 over Unix socket / Windows named pipe
+      ▼
+znt-core daemon
+      │
+      ▼
+indexed workspace
+```
 
-Официальный адаптер **Model Context Protocol (MCP)** для системы локального понимания кодовых баз и графового анализа **[Знаток (Znt)](https://github.com/boottaa/znt)**.
+Новый сервер заменяет прежнюю двойную ретрансляцию:
 
-## 🔗 Ссылки
-* 📦 **npm пакет**: [https://www.npmjs.com/package/@znt/mcp](https://www.npmjs.com/package/@znt/mcp)
-* 🚀 **Основной репозиторий Znt**: [https://github.com/boottaa/znt](https://github.com/boottaa/znt)
-* 🛠 **Репозиторий MCP-адаптера**: [https://github.com/boottaa/znt_mcp](https://github.com/boottaa/znt_mcp)
+```text
+Было:
+MCP client -> znt_mcp stdio adapter -> HTTP/SSE -> Go MCP engine -> core internals
 
-Позволяет внешним ИИ-агентам и LLM-клиентам (Claude Desktop, Antigravity IDE, Cursor, Windsurf, Zed, Codex и др.) осуществлять гибридный и мультифакторный поиск по смыслу, получать семантические оглавления файлов, строить графы вызовов и трассировать зависимости с прозрачным трекингом экономии контекстных токенов.
+Стало:
+MCP client -> znt-mcp-server stdio -> znt-sdk-nodejs -> znt-core IPC
+```
 
----
+Go-файл `internal/engine/mcp_engine.go` и HTTP-сервер для MCP больше не нужны в
+runtime нового пакета. Источником контракта core является SDK.
+
+## Основные свойства
+
+- Node.js 18+;
+- официальный MCP stdio transport;
+- одно переиспользуемое IPC-соединение;
+- Unix socket на Linux/macOS и named pipe на Windows;
+- десять публичных tools: `setup`, `setup_status`, `search`, `similar`, `graph`,
+  `outline`, `logs`, `status`, `scan`, `stats`;
+- совместимые имена параметров старого MCP преобразуются в параметры SDK;
+- daemon не запускается до успешного setup;
+- если managed core отсутствует, server устанавливает setup-capable релиз `1.1`;
+- завершение MCP server разрывает только клиентское соединение и не завершает
+  общий daemon;
+- RPC/transport ошибки возвращаются как MCP tool result с `isError: true`;
+- поддерживаются MCP cancellation и настраиваемый timeout;
+- локальная статистика использования сохраняется без SQLite-зависимости.
+
+## Требования
+
+- Node.js 18 или новее;
+- собранный `../znt-sdk-nodejs`;
+- доступ к GitHub для первой автоматической установки `znt-core`;
+- доступный workspace с исходниками; при необходимости агент может запустить
+  его первичное сканирование;
+- embeddings в core для полноценного vector search и `findSimilar()`.
+
+MCP server не публикует download/remove. Агент может передать существующий
+каталог через `project_path`; если путь не задан, используется workspace самого
+MCP-процесса. Повторный scan вложенного каталога не запускается, когда его уже
+покрывает индекс родительского каталога. Для интерактивного управления анализом
+и мониторингом можно использовать `znt-ui-dashboard`.
+
+## Установка
+
+Сначала соберите локальный SDK:
+
+```bash
+cd znt-sdk-nodejs
+npm install
+npm run build
+```
 
-## ⚡ Быстрый старт (npx)
+Затем установите зависимости MCP server:
+
+```bash
+cd ../znt-mcp-server
+npm install
+```
+
+## Запуск
+
+В каталоге пакета:
+
+```bash
+npm start
+```
 
-Не требуется предварительная сборка или ручная установка. Для подключения добавьте адаптер в ваш конфигурационный файл MCP (например, `~/.gemini/config/mcp_config.json`, `.cursor/mcp.json` или `claude_desktop_config.json`):
+Из корня monorepo:
+
+```bash
+npm run mcp
+```
+
+При обычном запуске server использует stdio для MCP-протокола. Нельзя писать
+диагностические сообщения в stdout: он зарезервирован для JSON-RPC. Ошибки
+bootstrap выводятся в stderr.
+
+## Подключение MCP-клиента
+
+Обобщённая конфигурация для клиента, поддерживающего локальные stdio servers:
 
 ```json
 {
   "mcpServers": {
-    "znt-mcp": {
+    "znt": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/Znt/znt-mcp-server/index.js"
+      ],
+      "env": {
+        "ZNT_PROJECT_ROOT": "/absolute/path/to/project"
+      }
+    }
+  }
+}
+```
+
+Для опубликованного npm-пакета вместо полного пути можно будет использовать
+`npx`:
+
+```json
+{
+  "mcpServers": {
+    "znt": {
       "command": "npx",
       "args": ["-y", "@znt/mcp"],
       "env": {
-        "ZNT_API_URL": "http://localhost:8080"
+        "ZNT_PROJECT_ROOT": "/absolute/path/to/project"
       }
     }
   }
 }
 ```
 
----
+При глобальной установке доступна bin-команда `znt-mcp`.
+
+## Жизненный цикл core
+
+При bootstrap server не запускает daemon и не сканирует проект:
+
+1. `setup_status` проверяет наличие бинарника и YAML.
+2. `setup` при необходимости устанавливает Core и получает встроенные YAML-дефолты.
+3. MCP сохраняет выбранный `config.yaml` рядом с управляемым бинарником.
+4. После валидации первый рабочий tool запускает daemon с этим конфигом.
+5. `scan` до успешного setup возвращает `setup_required`.
+
+SDK скачивает бинарник только из официальных GitHub Releases `znt-app/core` и
+проверяет SHA-256 из release manifest. Стандартные каталоги:
+
+| Платформа | Каталог |
+|---|---|
+| Linux | `$XDG_DATA_HOME/znt/bin` или `~/.local/share/znt/bin` |
+| macOS | `~/Library/Application Support/Znt/bin` |
+| Windows | `%LOCALAPPDATA%\\Znt\\bin` |
+
+Рабочий YAML находится в этом же каталоге под именем `config.yaml`. Явный
+`ZNT_CONFIG` имеет приоритет и считается внешним: MCP проверяет, но не
+перезаписывает его.
+
+При остановке MCP server вызывается только `client.disconnect()`. Это важно,
+потому что один daemon может одновременно использоваться Dashboard и другими
+SDK-клиентами.
+
+## Переменные окружения
+
+| Переменная | Назначение |
+|---|---|
+| `ZNT_ENDPOINT` | Unix socket или Windows named pipe |
+| `ZNT_CORE_HOME` | Пользовательский каталог установки core |
+| `ZNT_CORE_BINARY` | Полный путь к development-бинарнику |
+| `ZNT_CONFIG` | Конфигурация, передаваемая при запуске daemon |
+| `ZNT_CORE_CWD` | Рабочий каталог запускаемого daemon |
+| `ZNT_RUNTIME_DIR` | Runtime-файлы core |
+| `ZNT_PROJECT_ROOT` | Текущий проект MCP; по умолчанию `process.cwd()` |
+| `ZNT_MCP_REQUEST_TIMEOUT_MS` | Timeout одного SDK-вызова, по умолчанию 30000 ms |
+| `ZNT_MCP_METRICS_FILE` | Путь к JSONL-файлу MCP metrics |
+
+Если `ZNT_ENDPOINT` не задан, SDK использует:
+
+- Linux/macOS: `~/.znt/znt.sock`;
+- Windows: `\\.\pipe\znt-core`.
+
+`ZNT_PROJECT_ROOT` задаёт проект по умолчанию для IDE, которая запускает MCP
+server не из корня открытого проекта. `status` и
+`scan` также принимают необязательный `project_path`: абсолютный
+путь либо путь относительно `ZNT_PROJECT_ROOT`. Приоритет выбора:
+`project_path` → `ZNT_PROJECT_ROOT` → `cwd`.
+
+## Tools
+
+### `setup`
+
+Без параметров возвращает состояние и рекомендации: BM25, Ollama или
+OpenAI-compatible provider. С выбранным `mode` создаёт и проверяет managed
+`config.yaml`. API-ключ запрещено передавать аргументом tool.
+
+Для keyring MCP возвращает одноразовый loopback `setup_url`: пользователь
+вводит ключ напрямую в локальную форму, после чего Core сохраняет его в
+Windows Credential Manager, macOS Keychain или Linux Secret Service. В YAML
+остаётся только `token_ref`.
+
+### `setup_status`
+
+Проверяет Core, YAML и credential. С `check_provider: true` дополнительно
+проверяет endpoint и настроенные модели. Значение секрета не возвращается.
+
+### `search`
+
+Ищет компоненты в semantic index.
+
+| Параметр | Тип | По умолчанию | Описание |
+|---|---|---:|---|
+| `query` | string | обязателен | Имя символа или описание поведения |
+| `mode` | enum | `hybrid` | `lexical`, `vector`, `hybrid` |
+| `limit` | integer | `10` | Количество результатов |
+| `callers_level` | integer | `0` | Глубина входящих связей |
+| `callees_level` | integer | `0` | Глубина исходящих связей |
+| `compact` | boolean | `false` | Исключить граф связей |
+| `include_code` | boolean | `false` | Включить тело AST-узла |
+| `max_code_lines` | integer | `30` | Максимум строк кода |
+| `role_boost` | string | — | Мягкий boost роли |
+| `type_boost` | string | — | Мягкий boost AST-типа |
+| `file_pattern` | string | — | Фильтр пути |
+
+Старые имена `role_boost`, `type_boost`, `file_pattern` преобразуются в SDK
+поля `role`, `type`, `file_path`.
+
+Примеры:
+
+```json
+{
+  "query": "SemanticService.SearchWithOptions",
+  "mode": "lexical",
+  "type_boost": "function",
+  "include_code": true
+}
+```
+
+```json
+{
+  "query": "как строится индекс после сканирования",
+  "mode": "hybrid",
+  "role_boost": "service",
+  "limit": 10
+}
+```
+
+Практика выбора режима:
+
+- точный CamelCase/snake_case идентификатор — `lexical`;
+- поведение или архитектурный смысл — `hybrid`;
+- гипотетическое имя или чистая семантическая близость — `vector`.
+
+### `similar`
+
+Ищет аналоги и возможные дубликаты. Требуется хотя бы один параметр `target`
+или `query`.
+
+```json
+{
+  "target": "SemanticService.SearchWithOptions",
+  "limit": 10,
+  "edge_types": "call,implements",
+  "include_code": true
+}
+```
+
+Дополнительные параметры: `role_boost`, `type_boost`, `file_pattern`,
+`max_code_lines`. Инструмент зависит от embeddings; пустой результат без
+embedding не означает, что lexical symbol отсутствует.
 
-## 🛠 Доступные инструменты (MCP Tools)
+### `graph`
 
-Адаптер предоставляет 6 специализированных инструментов с автоматическим отслеживанием экономии контекста:
+Поддерживает локальный BFS-граф и трассировку пути.
 
-### 1. `znatok_semantic_search`
-* **Назначение**: Семантический и гибридный поиск (BM25 + Векторы + RRF) по элементам кодовой базы.
-* **Параметры**:
-  * `query` *(string, обязательный)*: Поисковый запрос на естественном языке.
-  * `limit` *(number)*: Максимальное число результатов (по умолчанию `10`, макс `100`).
-  * `callers_level` *(number)*: Глубина графа входящих вызовов (по умолчанию `3`).
-  * `callees_level` *(number)*: Глубина графа исходящих вызовов (по умолчанию `3`).
-  * `include_code` *(boolean)*: Включать ли фрагменты исходного кода узлов.
-  * `max_code_lines` *(number)*: Максимум строк кода на узел (по умолчанию `30`).
-  * `role` *(string)*: Фильтр по архитектурной роли (`"controller"`, `"service"`, `"repository"`, `"model"`).
-  * `type` *(string)*: Фильтр по типу узла AST (`"function"`, `"struct"`, `"class"`, `"interface"`).
-  * `file_pattern` *(string)*: Маска пути файла (например `"pkg/semantic/*"` или `"*.go"`).
-  * `mode` *(string)*: Режим поиска: `"hybrid"` (RRF гибридный), `"lexical"` (точный BM25/FTS5), `"vector"` (чисто векторный). По умолчанию `"hybrid"`.
+Локальное окружение:
 
----
+```json
+{
+  "from": "SemanticService.SearchWithOptions",
+  "depth": 2,
+  "edge_types": "call,implements,inherits",
+  "format": "text"
+}
+```
 
-### 2. `znatok_find_similar`
-* **Назначение**: Умный мультифакторный поиск аналогов и дубликатов кода (60% векторный косинус + 30% граф вызовов Jaccard + 10% AST-роли).
-* **Параметры**:
-  * `target` *(string)*: Имя символа, функции или класса в проекте (например `"Server.runFullScan"`). При указании вектор берется из БД напрямую **без обращения к LLM**.
-  * `query` *(string)*: Текстовое описание или код для поиска аналогов (используется, если `target` не задан).
-  * `limit` *(number)*: Максимальное число результатов (по умолчанию `10`).
-  * `callers_level` / `callees_level` *(number)*: Глубина связанных вызовов (по умолчанию `3`).
-  * `include_code` *(boolean)* / `max_code_lines` *(number)*: Параметры включения кода (по умолчанию `30` строк).
-  * `role` / `type` / `file_pattern` *(string)*: Фильтры по архитектуре и путям файлов.
+Трассировка:
 
----
+```json
+{
+  "from": "Server.ExecuteSearch",
+  "to": "SemanticStore.SearchFTS5",
+  "depth": 2,
+  "format": "mermaid"
+}
+```
 
-### 3. `znatok_get_subgraph`
-* **Назначение**: Построение подграфа окрестностей символа/файла или трассировка вызовов от точки `from` к точке `to`.
-* **Параметры**:
-  * `target` *(string)*: Символ или относительный путь файла для вывода его окрестностей.
-  * `from` / `to` *(string)*: Точки трассировки цепочки вызовов (DFS по графу).
-  * `depth` *(number)*: Глубина обхода подграфа (по умолчанию `2`).
-  * `max_nodes` *(number)*: Максимальное количество узлов подграфа (по умолчанию `30`).
-  * `format` *(string)*: Формат ответа (`"mermaid"` для Markdown-диаграмм или `"json"`, по умолчанию `"mermaid"`).
+Допустимые `edge_types`: `contains`, `call`, `inherits`, `implements`.
+Допустимые форматы: `text`, `json`, `mermaid`. Для неоднозначного короткого
+имени core возвращает кандидатов; повторите запрос с квалифицированным `name`.
 
----
+### `outline`
 
-### 4. `znatok_file_outline`
-* **Назначение**: Анатомический семантический атлас (оглавление) файла за 1 запрос без замусоривания контекста.
-* **Параметры**:
-  * `path` *(string, обязательный)*: Путь к целевому файлу (например `"internal/engine/server.go"`).
-  * `include_code` *(boolean)*: Включать ли фрагменты исходного кода для каждого символа.
+Возвращает полное top-level оглавление проиндексированного файла:
 
----
+```json
+{
+  "path": "internal/engine/queries.go",
+  "include_code": true
+}
+```
 
-### 5. `znatok_server_logs`
-* **Назначение**: Чтение системных логов и событий сервера Znt в реальном времени через WebSocket.
-* **Параметры**: Отсутствуют.
+MCP сохраняет старое имя параметра `path`, затем преобразует его в SDK
+`file_path`. Используйте outline перед чтением большого файла.
 
----
+### `logs`
 
-### 6. `znatok_mcp_stats`
-* **Назначение**: Детальная метрика работы MCP-сервера и статистика сэкономленных токенов из SQLite.
-* **Параметры**: Отсутствуют.
+Без параметров возвращает текущий snapshot кольцевого буфера core:
 
----
+```json
+{}
+```
 
-## 📊 Структура ответа и трекинг контекста (`_meta`)
+Для следующего delta-запроса передайте оба значения из ответа:
 
-Каждый инструмент возвращает обёртку со служебным объектом `_meta`:
+```json
+{
+  "stream_id": "stream_1234_...",
+  "after_id": 42
+}
+```
+
+Если continuity потеряна, core возвращает `truncated: true` и полный доступный
+snapshot.
+
+### `status`
+
+Проверяет, совпадает ли текущий MCP workspace с проектом, загруженным в daemon:
+
+```json
+{
+  "project_path": "/workspace/current"
+}
+```
+
+`project_path` необязателен. Каталог должен существовать. Символические ссылки
+разворачиваются через `realpath`.
+
+Источник истины — `status().project_root`. `info()` содержит версию,
+capabilities, конфигурацию и языки, но не содержит активный project root.
+
+Ответ включает:
 
 ```json
 {
-  "_meta": {
-    "tool": "znatok_semantic_search",
-    "response_tokens": 420,
-    "execution_ms": 15,
-    "last_call_saved_tokens": 12500,
-    "session_saved_tokens": 34000,
-    "alternative_cost": {
-      "tokens": 12920,
-      "description": "объем 3 затрагиваемых файлов целиком",
-      "savings_ratio": "30.8x"
-    },
-    "data_sources": ["core_api:search"]
+  "current_project": "/workspace/current",
+  "daemon_project": "/workspace/loaded",
+  "is_current_project": false,
+  "is_exact_project": false,
+  "coverage": "none",
+  "daemon_status": "Monitoring",
+  "has_index": false,
+  "stats": {
+    "files": 76,
+    "declarations": 249,
+    "functions": 75,
+    "members": 111,
+    "dependencies": 336,
+    "edges": 495
   },
-  "result": [ ... ]
+  "scan": {}
 }
 ```
 
----
+`coverage` принимает `exact`, `ancestor` или `none`. Если daemon индексирует
+`/workspace`, запрос для `/workspace/src/features` получает `ancestor` и
+считается покрытым существующим индексом. `stats` относятся к `daemon_project`.
+`has_index` становится true, когда запрошенный путь покрыт индексом и daemon
+сообщает ненулевое количество файлов.
+
+### `scan`
 
-## ⚙️ Переменные окружения
+Безопасно переключает daemon на текущий MCP workspace:
+
+```json
+{
+  "project_path": "/workspace/current",
+  "language": "auto"
+}
+```
+
+`project_path` необязателен и разрешает агенту явно указать открытый проект.
+Относительные значения вычисляются от `ZNT_PROJECT_ROOT`.
+
+Алгоритм:
+
+1. получает `status().project_root`;
+2. проверяет и канонизирует выбранный каталог через `realpath`;
+3. если daemon индексирует этот каталог либо его родителя, возвращает
+   `started: false` (`already_current_project` или `already_covered`);
+4. если другой scan уже выполняется, возвращает `scan_in_progress` и не
+   переключает daemon;
+5. иначе вызывает SDK `scan()` для выбранного каталога;
+6. всегда передаёт `restart: false`, сохраняя существующий `.znt` индекс;
+7. немедленно возвращает `scan_id`; прогресс проверяется через
+   `status`.
+
+Если daemon прямо сейчас сканирует другой проект, core может вернуть `Busy`.
+Нужно дождаться терминального scan status и повторить вызов.
+
+### `stats`
+
+Возвращает session/total calls, приблизительный объём ответа, оценку экономии,
+среднее время, top tools и последние вызовы.
+
+```json
+{}
+```
+
+После получения `status.project_root` статистика дописывается в
+`<workspace>/.znt/mcp-usage.jsonl`. Путь можно переопределить через
+`ZNT_MCP_METRICS_FILE`. Ошибка записи метрик никогда не превращает успешный
+Znt tool call в ошибку.
+
+Token metrics являются оценкой `ceil(characters / 4)`, а savings — сравнительной
+эвристикой, не billing-статистикой LLM provider.
+
+## Формат ответов
+
+Все tools возвращают MCP `content` с текстовым блоком.
+
+- semantic search форматируется в компактные секции `Score/Name/File/Code`;
+- file outline возвращает `formatted_text` core без JSON-обёртки;
+- text/mermaid subgraph возвращается непосредственно;
+- JSON subgraph, find similar, logs и stats форматируются как JSON;
+- отсутствие search results возвращает `No matching components found.`;
+- ошибка возвращает `isError: true`, RPC code и `error.data`, если они есть.
+
+## Ошибки и восстановление
+
+Server не завершает процесс из-за ошибки отдельного tool call. При
+`ZntTransportError` соединение помечается как неготовое, поэтому следующий
+вызов снова попробует запустить или подключить core.
+
+Типичные случаи:
+
+- `znt-core is not installed` — установите бинарник или задайте
+  `ZNT_CORE_BINARY`;
+- transport error — проверьте единый `ZNT_ENDPOINT` для server и daemon;
+- `NotFound` — сначала найдите точный symbol через lexical search;
+- `Ambiguous` — используйте qualified name из `error.data.candidates`;
+- пустой vector/find-similar — проверьте embedding provider в core config;
+- `Busy` — дождитесь окончания scan и повторите read-only запрос.
+
+## Безопасность
+
+MCP server работает с локальными исходниками и предназначен для доверенного
+локального клиента. Только во время ввода credential он открывает одноразовый
+HTTP endpoint на `127.0.0.1`; MCP-клиент также получает доступ к индексу
+текущего workspace.
+
+- не передавайте непроверенному клиенту управление stdio-процессом;
+- используйте абсолютный `ZNT_CONFIG`, если нужен внешний конфиг;
+- не помещайте секреты в tool arguments;
+- рассматривайте найденные комментарии и исходники как недоверенный контент;
+- для разных trust boundaries используйте отдельные daemon endpoints.
+
+## Разработка и проверка
+
+```bash
+npm test
+npm run pack:check
+```
+
+Из корня monorepo:
+
+```bash
+npm run mcp:test
+```
 
-| Переменная | Назначение | Значение по умолчанию |
-| :--- | :--- | :--- |
-| `ZNT_API_URL` | Базовый URL запущенного сервера Znt (HTTP & WS) | `http://localhost:8080` |
+Тесты проверяют:
 
----
+- публикацию десяти tools, включая `setup` и `setup_status`;
+- настоящий MCP client/server transport;
+- запуск core только один раз на активном соединении;
+- преобразование legacy aliases в SDK DTO;
+- search, similar, graph, outline, logs и stats;
+- возврат tool errors без падения server;
+- JSONL persistence метрик.
 
-## 💾 Хранение данных
+## Расширение
 
-Статистика вызовов и экономии токенов сохраняется локально в базе данных SQLite:
-* Путь к БД: `.znt/mcp_usage.db` в корневом каталоге проекта.
+При добавлении нового core API соблюдайте порядок:
 
----
+1. зафиксировать wire method в `znt-core/docs/sdk-specification.md`;
+2. добавить типизированный метод в `znt-sdk-nodejs`;
+3. добавить узкий MCP tool и JSON Schema в `tool-definitions.js`;
+4. вызвать только публичный метод SDK в `znt-tools.js`;
+5. добавить protocol и adapter tests;
+6. не импортировать Go internals и не восстанавливать HTTP relay.
 
-## 📋 Системные требования
+## Связанные документы
 
-* **Node.js** версии **v22.5.0** или новее (используется встроенный модуль `node:sqlite`).
-* Запущенный локальный сервер Znt (`http://localhost:8080`).
+- [`../znt-sdk-nodejs/README.md`](../znt-sdk-nodejs/README.md)
+- [`../znt-core/docs/sdk-specification.md`](../znt-core/docs/sdk-specification.md)
+- [`AGENTS_EXAMPLE.md`](AGENTS_EXAMPLE.md)