@znt/mcp

Локальный Model Context Protocol server для Znt. Он публикует инструменты поиска и анализа кода через MCP stdio и вызывает znt-core напрямую через znt-sdk-nodejs.

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

Новый сервер заменяет прежнюю двойную ретрансляцию:

Было:
MCP client -> znt_mcp stdio adapter -> HTTP/SSE -> Go MCP engine -> core internals

Стало:
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, graph, logs, status, scan, stats;
• совместимые имена параметров старого MCP преобразуются в параметры SDK;
• daemon не запускается до успешного setup;
• если managed core отсутствует, server устанавливает setup-capable релиз 1.4;
• завершение MCP server разрывает только клиентское соединение и не завершает общий daemon;
• RPC/transport ошибки возвращаются как MCP tool result с isError: true;
• поддерживаются MCP cancellation и настраиваемый timeout;
• локальная статистика использования сохраняется без SQLite-зависимости.

Требования

• Node.js 18 или новее;
• доступ к GitHub для первой автоматической установки znt-core (релиз 1.4);
• доступный workspace с исходниками; при необходимости агент может запустить его первичное сканирование;
• embeddings в core для полноценного vector search (при использовании LLM/векторного режима).

MCP server не публикует download/remove. Агент может передать существующий каталог через project_path; если путь не задан, используется workspace самого MCP-процесса. Повторный scan вложенного каталога не запускается, когда его уже покрывает индекс родительского каталога. Для интерактивного управления анализом и мониторингом можно использовать znt-ui-dashboard.

Быстрый старт и запуск

Пакет опубликован в npm и готов к запуску без предварительной ручной сборки:

npx -y @znt/mcp

Или при глобальной установке:

npm install -g @znt/mcp
znt-mcp

При запуске server использует stdio для MCP-протокола. Нельзя писать диагностические сообщения в stdout: он зарезервирован для JSON-RPC. Ошибки bootstrap выводятся в stderr.

Подключение к MCP-клиентам

Для подключения к Claude Desktop, Cursor, Antigravity, VS Code или другим MCP-клиентам укажите npx -y @znt/mcp:

{
  "mcpServers": {
    "znt": {
      "command": "npx",
      "args": ["-y", "@znt/mcp"],
      "env": {
        "ZNT_PROJECT_ROOT": "/absolute/path/to/project"
      }
    }
  }
}

Если вы установили пакет глобально (npm install -g @znt/mcp), можно использовать прямую команду:

{
  "mcpServers": {
    "znt": {
      "command": "znt-mcp",
      "env": {
        "ZNT_PROJECT_ROOT": "/absolute/path/to/project"
      }
    }
  }
}

Разработка из исходников (Monorepo)

Если вы разрабатываете Znt локально в монорепозитории:

1. Соберите локальный SDK:

   cd znt-sdk-nodejs
   npm install
   npm run build

2. Установите зависимости и запустите MCP-сервер:

   cd ../znt-mcp-server
   npm install
   npm start

3. Либо запустите из корня монорепозитория:

   npm run mcp

Для локального development-запуска в клиенте укажите прямой путь к index.js:

{
  "mcpServers": {
    "znt": {
      "command": "node",
      "args": [
        "/absolute/path/to/Znt/znt-mcp-server/index.js"
      ],
      "env": {
        "ZNT_PROJECT_ROOT": "/absolute/path/to/project"
      }
    }
  }
}

Жизненный цикл 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

Настраивает провайдеры, модели и параметры Znt.

• Интерактивный режим (по умолчанию): вызов без аргументов или с interactive: true открывает локальный веб-визард (setup_url) в браузере для безопасного ввода ключей и выбора моделей. Секрет сохраняется в защищённом хранилище (macOS Keychain, Windows Credential Manager, Linux Secret Service), а в YAML пишется только token_ref.
• Автоматический / Headless режим: вызов с interactive: false позволяет настроить параметры напрямую через аргументы (mode, provider_url, model, embed_model, semantic_mode, token_env).
• Защита от сброса индекса (confirm): если Znt уже настроен (status: "ready"), повторный запуск setup без confirm: true не перезапускает core и не сбрасывает активный граф, а возвращает текущий статус с предупреждением. Для принудительного перезапуска и переконфигурирования передайте confirm: true.
• Для простого чтения текущей конфигурации без риска перезапуска ядра используйте setup_status.

| Параметр | Тип | По умолчанию | Описание | |---|---|---:|---| | confirm | boolean | false | Подтверждение перезапуска core и инвалидации активного графа | | interactive | boolean | true | Открыть интерактивный веб-визард в браузере | | mode | enum | — | bm25 (без LLM), ollama (локально), openapi (OpenRouter/OpenAI) | | provider_url | string | — | URL API провайдера (для openapi / ollama) | | model | string | — | Имя генеративной модели | | embed_model | string | — | Имя модели эмбеддингов (none для отключения вектора) | | semantic_mode | enum | fast | fast (быстрый AST-анализ) или llm (генерация описаний через LLM) | | description_language| string | ru | Язык описаний компонентов | | token_env | string | — | Имя переменной окружения с токеном (секреты не передаются в аргументах) | | credential_source | enum | keyring | keyring (системная связка ключей) или env | | exclude | array | — | Массив glob-паттернов исключений файлов/папок | | check_provider | boolean | true | Проверить доступность провайдера при настройке |

setup_status

Проверяет Core, YAML и credential. С check_provider: true дополнительно проверяет endpoint и настроенные модели. Значение секрета не возвращается.

Ключевые поля ответа:

• config_managed (boolean): true, если конфигурация управляется MCP-сервером, или false, если выбран внешний файл конфигурации через ZNT_CONFIG.
• model: имя генеративной LLM-модели. Если выбран semantic_mode: "fast" (локальные эвристики AST без вызовов LLM) и модель не задана, поле возвращает "not_required (fast mode)".

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.

Примеры:

{
  "query": "SemanticService.SearchWithOptions",
  "mode": "lexical",
  "type_boost": "function",
  "include_code": true
}

{
  "query": "как строится индекс после сканирования",
  "mode": "hybrid",
  "role_boost": "service",
  "limit": 10
}

Практика выбора режима:

• точный CamelCase/snake_case идентификатор — lexical;
• поведение или архитектурный смысл — hybrid;
• гипотетическое имя или чистая семантическая близость — vector.

graph

Поддерживает локальный BFS-граф и трассировку пути.

Локальное окружение:

{
  "from": "SemanticService.SearchWithOptions",
  "depth": 2,
  "edge_types": "call,implements,inherits",
  "format": "text"
}

Трассировка:

{
  "from": "Server.ExecuteSearch",
  "to": "SemanticStore.SearchFTS5",
  "depth": 2,
  "format": "mermaid"
}

| Параметр | Тип | По умолчанию | Описание | |---|---|---:|---| | from | string | обязателен | Квалифицированное имя символа или путь к файлу | | to | string | — | Целевой символ (для режима трассировки прямого пути from ➔ to) | | depth | integer | 1 | Глубина BFS-обхода (от 1 до 100) | | format | enum | text | Формат ответа: text, json, mermaid | | edge_types | string | — | Фильтр типов связей через запятую (contains, call, inherits, implements) | | direction | enum | down | Направление обхода в локальном режиме: down (callees), up (callers), both |

Допустимые edge_types: contains, call, inherits, implements. Допустимые форматы: text, json, mermaid. Для неоднозначного короткого имени core возвращает кандидатов; повторите запрос с квалифицированным name.

Дополнительные параметры направления:

• direction ("down" | "up" | "both", по умолчанию "down"): в локальном режиме задает направление обхода вызовов:
  • "down" (по умолчанию): исследует только исходящие вызовы (дерево вызовов / callees), исключая комбинаторный взрыв тестами и сторонними клиентами на depth >= 2;
  • "up": исследует иерархию вызывающих (callers / кто вызывает данный символ);
  • "both": двунаправленный обход (одновременно callers и callees).

💡 Чистый граф проекта: MCP автоматически отсекает методы стандартных библиотек и вендоров (JDK, Go stdlib, Spring boilerplate: HashMap, put, get, ok), поэтому граф содержит только реальный код проекта.

logs

Без параметров возвращает текущий snapshot кольцевого буфера core:

{}

Для следующего delta-запроса передайте оба значения из ответа:

{
  "stream_id": "stream_1234_...",
  "after_id": 42
}

Если continuity потеряна, core возвращает truncated: true и полный доступный snapshot.

status

Проверяет, совпадает ли текущий MCP workspace с проектом, загруженным в daemon:

{
  "project_path": "/workspace/current"
}

project_path необязателен. Каталог должен существовать. Символические ссылки разворачиваются через realpath.

Источник истины — status().project_root. info() содержит версию, capabilities, конфигурацию и языки, но не содержит активный project root.

Ответ включает:

{
  "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
  },
  "scan": {}
}

coverage принимает exact, ancestor или none. Если daemon индексирует /workspace, запрос для /workspace/src/features получает ancestor и считается покрытым существующим индексом. stats относятся к daemon_project. has_index становится true, когда запрошенный путь покрыт индексом и daemon сообщает ненулевое количество файлов.

scan

Безопасно переключает daemon на текущий MCP workspace:

{
  "project_path": "/workspace/current"
}

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

Возвращает реальную инженерную телеметрию использования инструментов MCP: количество вызовов (session и lifetime), время непрерывной работы (uptime_seconds), задержку (avg_ms, min_ms, max_ms), объём сгенерированных токенов в ответах (avg_output_tokens, total_output_tokens) и историю последних вызовов.

{}

Пример ответа:

{
  "session_start_time": "2026-09-19T11:26:17.898Z",
  "uptime_seconds": 181200,
  "session_calls": 14,
  "lifetime_calls": 14,
  "total_output_tokens": 5701,
  "avg_execution_ms": 80,
  "top_tools": [
    {
      "tool_name": "search",
      "calls": 4,
      "avg_ms": 28,
      "min_latency_ms": 15,
      "max_latency_ms": 62,
      "total_output_tokens": 1776,
      "avg_output_tokens": 444
    },
    {
      "tool_name": "graph",
      "calls": 4,
      "avg_ms": 59,
      "min_latency_ms": 50,
      "max_latency_ms": 79,
      "total_output_tokens": 669,
      "avg_output_tokens": 167
    }
  ],
  "recent_calls": [
    {
      "timestamp": "2026-09-19T13:46:04.138Z",
      "tool_name": "scan",
      "input_tokens": 11,
      "output_tokens": 48,
      "execution_ms": 9
    }
  ],
  "persistence": "/workspace/.znt/mcp-usage.jsonl"
}

После получения status.project_root статистика дописывается в <workspace>/.znt/mcp-usage.jsonl. Путь можно переопределить через ZNT_MCP_METRICS_FILE. Ошибка записи метрик никогда не превращает успешный Znt tool call в ошибку.

Метрики токенов рассчитываются как ceil(characters / 4) от реального вывода инструментов. Сервер не использует искусственные коэффициенты экономии токенов.

Формат ответов

Все tools возвращают MCP content с текстовым блоком.

• semantic search форматируется в компактные секции Score/Name/File/Code;
• text/mermaid subgraph возвращается непосредственно;
• JSON subgraph, 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 search — проверьте 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.

Разработка и проверка

npm test
npm run pack:check

Из корня monorepo:

npm run mcp:test

Тесты проверяют:

• публикацию восьми tools, включая setup и setup_status;
• настоящий MCP client/server transport;
• запуск core только один раз на активном соединении;
• преобразование legacy aliases в SDK DTO;
• search, graph, logs и stats;
• возврат tool errors без падения server;
• JSONL persistence метрик.

Расширение

При добавлении нового 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.

Связанные документы

• Примеры инструкций для AI-агентов: AGENTS_EXAMPLE.md
• Клиентский SDK: @znt/sdk-nodejs
• Репозиторий проекта Znt: GitHub