@znt/mcp 1.0.3 → 1.0.5

package/README.md

@@ -1,14 +1,14 @@
-# Znt MCP Adapter (@znt/mcp)
+# Znt MCP Adapter (@znt/mcp v1.1.0)
 
 Официальный адаптер **Model Context Protocol (MCP)** для системы локального понимания кодовых баз и графового анализа **Знаток (Znt)**.
 
-Позволяет внешним ИИ-агентам и LLM-клиентам (Claude Desktop, Antigravity IDE, Cursor, Windsurf, Zed и др.) осуществлять умный гибридный поиск по смыслу, получать оглавления файлов, строить графы вызовов и трассировать зависимости с 0ms LLM оверхедом и максимальной экономией контекстных токенов.
+Позволяет внешним ИИ-агентам и LLM-клиентам (Claude Desktop, Antigravity IDE, Cursor, Windsurf, Zed, Codex и др.) осуществлять гибридный и мультифакторный поиск по смыслу, получать семантические оглавления файлов, строить графы вызовов и трассировать зависимости с прозрачным трекингом экономии контекстных токенов.
 
 ---
 
 ## ⚡ Быстрый старт (npx)
 
-Не требуется предварительная сборка или ручная установка. Для подключения добавьте адаптер в ваш конфигурационный файл MCP (например, `~/.gemini/config/mcp_config.json` или `claude_desktop_config.json`):
+Не требуется предварительная сборка или ручная установка. Для подключения добавьте адаптер в ваш конфигурационный файл MCP (например, `~/.gemini/config/mcp_config.json`, `.cursor/mcp.json` или `claude_desktop_config.json`):
 
 ```json
 {
@@ -30,25 +30,106 @@
 
 Адаптер предоставляет 6 специализированных инструментов с автоматическим отслеживанием экономии контекста:
 
-| Инструмент | Описание |
-| :--- | :--- |
-| `znatok_semantic_search` | **Гибридный поиск (BM25 + Векторы + RRF)** по кодовой базе. Находит узлы, архитектурные роли (`controller`, `service`, `repository`), аннотации и связи. |
-| `znatok_find_similar` | **Поиск аналогов и дубликатов**. Находит схожие реализации, существующие абстракции и паттерны по фрагменту кода. |
-| `znatok_get_subgraph` | **Графовый анализ и трассировка вызовов**. Возвращает подграф зависимостей или трассировку потока данных от узла A к узлу B (`from` ➔ `to`) в формате Mermaid / JSON. |
-| `znatok_file_outline` | **Семантический атлас (оглавление) файла**. Мгновенно отдает список всех символов (функции, структуры, методы) с номерами строк и их ролями. |
-| `znatok_server_logs` | **Логи сервера Znt**. Мониторинг событий индексации и состояния графа в реальном времени. |
-| `znatok_mcp_stats` | **Статистика экономии токенов**. Показывает количество сэкономленных токенов контекста, метрики вызовов и коэффициент оптимизации (`savings_ratio`). |
+### 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"`).
+  * `hybrid` *(boolean)*: Использовать гибридный RRF поиск (BM25 + Векторы, по умолчанию `true`).
 
 ---
 
-## 🚀 Особенности работы
+### 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)*: Фильтры по архитектуре и путям файлов.
 
-1. **Единая интеграция с Znt Core API**: Все поисковые, графовые и семантические запросы к кодовой базе выполняются через HTTP API и WebSocket запущенного сервера Znt (`ZNT_API_URL`, по умолчанию `http://localhost:8080`).
-2. **Локальный Usage Tracking**: SQLite (`node:sqlite`) используется только для локального логирования метрик использования в `.znt/mcp_usage.db`, мгновенно рассчитывая объем сэкономленного контекста по сравнению с прямым чтением исходных файлов.
+---
+
+### 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"`).
+
+---
+
+### 4. `znatok_file_outline`
+* **Назначение**: Анатомический семантический атлас (оглавление) файла за 1 запрос без замусоривания контекста.
+* **Параметры**:
+  * `path` *(string, обязательный)*: Путь к целевому файлу (например `"internal/engine/server.go"`).
+  * `include_code` *(boolean)*: Включать ли фрагменты исходного кода для каждого символа.
+
+---
+
+### 5. `znatok_server_logs`
+* **Назначение**: Чтение системных логов и событий сервера Znt в реальном времени через WebSocket.
+* **Параметры**: Отсутствуют.
+
+---
+
+### 6. `znatok_mcp_stats`
+* **Назначение**: Детальная метрика работы MCP-сервера и статистика сэкономленных токенов из SQLite.
+* **Параметры**: Отсутствуют.
+
+---
+
+## 📊 Структура ответа и трекинг контекста (`_meta`)
+
+Каждый инструмент возвращает обёртку со служебным объектом `_meta`:
+
+```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"]
+  },
+  "result": [ ... ]
+}
+```
+
+---
+
+## ⚙️ Переменные окружения
+
+| Переменная | Назначение | Значение по умолчанию |
+| :--- | :--- | :--- |
+| `ZNT_API_URL` | Базовый URL запущенного сервера Znt (HTTP & WS) | `http://localhost:8080` |
+
+---
+
+## 💾 Хранение данных
+
+Статистика вызовов и экономии токенов сохраняется локально в базе данных SQLite:
+* Путь к БД: `.znt/mcp_usage.db` в корневом каталоге проекта.
 
 ---
 
 ## 📋 Системные требования
 
-* **Node.js** версии **v22.5.0** или новее.
-* Индексированный проект с папкой `.znt` в корневом каталоге репозитория.
+* **Node.js** версии **v22.5.0** или новее (используется встроенный модуль `node:sqlite`).
+* Запущенный локальный сервер Znt (`http://localhost:8080`).

package/index.js

@@ -307,11 +307,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'znatok_find_similar',
-        description: 'Ищет элементы кода в базе знаний проекта, которые являются семантически близкими по назначению к заданному фрагменту текста или сигнатуре. Помогает находить дубликаты, аналогичные методы или связанные абстракции. Возвращает список объектов с относительными путями файлов и структурой графа.',
+        description: 'Ищет аналогичные элементы кода и дубликаты на основе комбинированного мультифакторного анализа (векторное косинусное сходство, графовые соседи Jaccard и совпадение типов AST/ролей). Позволяет передавать как имя существующего символа (target), так и фрагмент текста/кода (query).',
         inputSchema: {
           type: 'object',
           properties: {
-            query: { type: 'string', description: 'Текстовый фрагмент или описание функции/класса для поиска аналогов' },
+            target: { type: 'string', description: 'Имя существующего символа, функции или класса в проекте для поиска аналогов (например: "Server.runFullScan"). Если указано, вектор берется напрямую из БД без запроса к LLM.' },
+            query: { type: 'string', description: 'Текстовый фрагмент или описание функции/класса для поиска аналогов (используется, если target не задан)' },
             limit: { type: 'number', description: 'Максимальное количество возвращаемых элементов (по умолчанию 10)' },
             callers_level: { type: 'number', description: 'Глубина вложенности входящего графа вызовов ("где вызывается"), по умолчанию 3' },
             callees_level: { type: 'number', description: 'Глубина вложенности исходящего графа вызовов ("где вызывают"), по умолчанию 3' },
@@ -319,22 +320,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             max_code_lines: { type: 'number', description: 'Максимальное количество строк исходного кода (по умолчанию 30)' },
             role: { type: 'string', description: 'Фильтр по архитектурной роли компонента (например: "controller", "repository", "service", "model")' },
             type: { type: 'string', description: 'Фильтр по типу узла AST (например: "function", "struct", "class", "interface")' },
-            file_pattern: { type: 'string', description: 'Шаблон/маска пути файла для фильтрации (например: "pkg/semantic/*" или "*.go")' },
-            hybrid: { type: 'boolean', description: 'Использовать гибридный поиск (RRF: BM25/Лексика + Векторы, по умолчанию true)' }
-          },
-          required: ['query']
+            file_pattern: { type: 'string', description: 'Шаблон/маска пути файла для фильтрации (например: "pkg/semantic/*" или "*.go")' }
+          }
         },
       },
       {
         name: 'znatok_get_subgraph',
-        description: 'Возвращает ориентированный подграф (в формате Mermaid или JSON) вокруг заданного символа/файла (target) или вычисляет трассу вызовов между двумя точками (from -> to). Позволяет быстро визуализировать и исследовать архитектуру компонентов, цепочки вызовов и зависимости за 1 запрос без использования LLM.',
+        description: 'Возвращает ориентированный подграф (в формате Mermaid или JSON) вокруг заданного символа/файла (target) или ищет цепочку вызовов между двумя точками (from + to). Режим target: строит окрестности символа на заданную глубину. Режим трассировки (from + to): DFS запускается от `to` вверх по входящим рёбрам и ищет пути, в которых встречается `from`. Ограничение: если from вызывает to не напрямую, а через промежуточный узел, рёбра могут не отобразиться — в таком случае edges будет пустым и вернутся два изолированных узла.',
         inputSchema: {
           type: 'object',
           properties: {
-            target: { type: 'string', description: 'Имя символа, функции, класса или относительный путь файла для построения подграфа окрестностей (например: "SemanticService" или "server.go")' },
-            from: { type: 'string', description: 'Стартовый символ/функция для поиска трассы вызовов (например: "main" или "handleSearch")' },
-            to: { type: 'string', description: 'Конечный символ/функция для поиска трассы вызовов (например: "GetNodeContent")' },
-            depth: { type: 'number', description: 'Глубина обхода подграфа (по умолчанию 2)' },
+            target: { type: 'string', description: 'Имя символа, функции, класса или относительный путь файла для построения подграфа окрестностей (например: "SemanticService" или "server.go"). Используется только если from/to не заданы.' },
+            from: { type: 'string', description: 'Фильтр: символ/функция, которая должна встречаться в путях вызовов, найденных от `to`. Алгоритм ищет пути где from предшествует to по цепочке. Требует совместного указания с `to`.' },
+            to: { type: 'string', description: 'Точка старта трассировки — символ/функция, от которой DFS идёт вверх по входящим рёбрам (PredecessorMap). Именно `to` является началом обхода, а не концом. Требует совместного указания с `from`.' },
+            depth: { type: 'number', description: 'Глубина обхода подграфа (по умолчанию 2). В режиме трассировки используется как depth*2.' },
             max_nodes: { type: 'number', description: 'Максимальное количество узлов подграфа (по умолчанию 30)' },
             format: { type: 'string', description: 'Формат ответа: "mermaid" для диаграммы в Markdown или "json" (по умолчанию "mermaid")' }
           }
@@ -437,7 +436,59 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     let sources = [];
 
     switch (toolName) {
-      case 'znatok_find_similar':
+      case 'znatok_find_similar': {
+        const target = request.params.arguments?.target || request.params.arguments?.target_symbol || '';
+        const query = request.params.arguments?.query || request.params.arguments?.text || '';
+        if (!target && !query) {
+          result = 'Either target or query parameter is required.';
+          break;
+        }
+        const limit = Math.min(Math.max(1, parseInt(request.params.arguments?.limit, 10) || 10), 100);
+        const callersLevel = Math.min(Math.max(0, parseInt(request.params.arguments?.callers_level ?? request.params.arguments?.caller_level, 10) ?? 3), 10);
+        const calleesLevel = Math.min(Math.max(0, parseInt(request.params.arguments?.callees_level ?? request.params.arguments?.callee_level, 10) ?? 3), 10);
+        const includeCode = Boolean(request.params.arguments?.include_code);
+        const maxCodeLines = parseInt(request.params.arguments?.max_code_lines, 10) || 30;
+        const role = request.params.arguments?.role || '';
+        const nodeType = request.params.arguments?.type || '';
+        const filePattern = request.params.arguments?.file_pattern || '';
+
+        const apiParams = new URLSearchParams({
+          limit: limit.toString(),
+          callers_level: callersLevel.toString(),
+          callees_level: calleesLevel.toString(),
+          include_code: includeCode.toString(),
+          max_code_lines: maxCodeLines.toString(),
+        });
+        if (target) apiParams.set('target', target);
+        if (query) apiParams.set('q', query);
+        if (role) apiParams.set('role', role);
+        if (nodeType) apiParams.set('type', nodeType);
+        if (filePattern) apiParams.set('file_pattern', filePattern);
+
+        const rawResults = await callZntApi(`/api/find_similar?${apiParams.toString()}`);
+        let processed = Array.isArray(rawResults) ? rawResults.map(item => {
+          const relFile = toRelativePath(item.file || item.file_path || item.filePath);
+          const resItem = {
+            ...item,
+            file: relFile
+          };
+          if (includeCode && !resItem.code && resItem.file && resItem.start_line && resItem.end_line) {
+            let endLine = resItem.end_line;
+            if (maxCodeLines > 0 && (endLine - resItem.start_line + 1) > maxCodeLines) {
+              endLine = resItem.start_line + maxCodeLines - 1;
+            }
+            resItem.code = getSourceSnippet(resItem.file, resItem.start_line, endLine);
+          }
+          return resItem;
+        }) : rawResults;
+        if (Array.isArray(processed)) {
+          processed = processed.slice(0, limit);
+        }
+        result = processed;
+        sources = ['core_api:find_similar'];
+        break;
+      }
+
       case 'znatok_semantic_search': {
         const query = request.params.arguments?.query || request.params.arguments?.text;
         if (!query) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znt/mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Model Context Protocol adapter for Znt",
   "main": "index.js",
   "type": "module",
@@ -31,4 +31,4 @@
     "@modelcontextprotocol/sdk": "^1.0.1",
     "ws": "^8.21.1"
   }
-}
+}