@znt/mcp 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +103 -17
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,14 +1,19 @@
1
- # Znt MCP Adapter (@znt/mcp)
1
+ # Znt MCP Adapter ([@znt/mcp](https://www.npmjs.com/package/@znt/mcp))
2
2
 
3
- Официальный адаптер **Model Context Protocol (MCP)** для системы локального понимания кодовых баз и графового анализа **Знаток (Znt)**.
3
+ Официальный адаптер **Model Context Protocol (MCP)** для системы локального понимания кодовых баз и графового анализа **[Знаток (Znt)](https://github.com/boottaa/znt)**.
4
4
 
5
- Позволяет внешним ИИ-агентам и LLM-клиентам (Claude Desktop, Antigravity IDE, Cursor, Windsurf, Zed и др.) осуществлять умный гибридный поиск по смыслу, получать оглавления файлов, строить графы вызовов и трассировать зависимости с 0ms LLM оверхедом и максимальной экономией контекстных токенов.
5
+ ## 🔗 Ссылки
6
+ * 📦 **npm пакет**: [https://www.npmjs.com/package/@znt/mcp](https://www.npmjs.com/package/@znt/mcp)
7
+ * 🚀 **Основной репозиторий Znt**: [https://github.com/boottaa/znt](https://github.com/boottaa/znt)
8
+ * 🛠 **Репозиторий MCP-адаптера**: [https://github.com/boottaa/znt_mcp](https://github.com/boottaa/znt_mcp)
9
+
10
+ Позволяет внешним ИИ-агентам и LLM-клиентам (Claude Desktop, Antigravity IDE, Cursor, Windsurf, Zed, Codex и др.) осуществлять гибридный и мультифакторный поиск по смыслу, получать семантические оглавления файлов, строить графы вызовов и трассировать зависимости с прозрачным трекингом экономии контекстных токенов.
6
11
 
7
12
  ---
8
13
 
9
14
  ## ⚡ Быстрый старт (npx)
10
15
 
11
- Не требуется предварительная сборка или ручная установка. Для подключения добавьте адаптер в ваш конфигурационный файл MCP (например, `~/.gemini/config/mcp_config.json` или `claude_desktop_config.json`):
16
+ Не требуется предварительная сборка или ручная установка. Для подключения добавьте адаптер в ваш конфигурационный файл MCP (например, `~/.gemini/config/mcp_config.json`, `.cursor/mcp.json` или `claude_desktop_config.json`):
12
17
 
13
18
  ```json
14
19
  {
@@ -30,25 +35,106 @@
30
35
 
31
36
  Адаптер предоставляет 6 специализированных инструментов с автоматическим отслеживанием экономии контекста:
32
37
 
33
- | Инструмент | Описание |
34
- | :--- | :--- |
35
- | `znatok_semantic_search` | **Гибридный поиск (BM25 + Векторы + RRF)** по кодовой базе. Находит узлы, архитектурные роли (`controller`, `service`, `repository`), аннотации и связи. |
36
- | `znatok_find_similar` | **Мультифакторный поиск аналогов и дубликатов**. Находит схожие реализации по имени символа (`target`) или описанию (`query`) на основе векторного сходства, связей в графе (Jaccard) и AST-структур. |
37
- | `znatok_get_subgraph` | **Графовый анализ и трассировка вызовов**. Возвращает подграф зависимостей или трассировку потока данных от узла A к узлу B (`from` ➔ `to`) в формате Mermaid / JSON. |
38
- | `znatok_file_outline` | **Семантический атлас (оглавление) файла**. Мгновенно отдает список всех символов (функции, структуры, методы) с номерами строк и их ролями. |
39
- | `znatok_server_logs` | **Логи сервера Znt**. Мониторинг событий индексации и состояния графа в реальном времени. |
40
- | `znatok_mcp_stats` | **Статистика экономии токенов**. Показывает количество сэкономленных токенов контекста, метрики вызовов и коэффициент оптимизации (`savings_ratio`). |
38
+ ### 1. `znatok_semantic_search`
39
+ * **Назначение**: Семантический и гибридный поиск (BM25 + Векторы + RRF) по элементам кодовой базы.
40
+ * **Параметры**:
41
+ * `query` *(string, обязательный)*: Поисковый запрос на естественном языке.
42
+ * `limit` *(number)*: Максимальное число результатов (по умолчанию `10`, макс `100`).
43
+ * `callers_level` *(number)*: Глубина графа входящих вызовов (по умолчанию `3`).
44
+ * `callees_level` *(number)*: Глубина графа исходящих вызовов (по умолчанию `3`).
45
+ * `include_code` *(boolean)*: Включать ли фрагменты исходного кода узлов.
46
+ * `max_code_lines` *(number)*: Максимум строк кода на узел (по умолчанию `30`).
47
+ * `role` *(string)*: Фильтр по архитектурной роли (`"controller"`, `"service"`, `"repository"`, `"model"`).
48
+ * `type` *(string)*: Фильтр по типу узла AST (`"function"`, `"struct"`, `"class"`, `"interface"`).
49
+ * `file_pattern` *(string)*: Маска пути файла (например `"pkg/semantic/*"` или `"*.go"`).
50
+ * `hybrid` *(boolean)*: Использовать гибридный RRF поиск (BM25 + Векторы, по умолчанию `true`).
51
+
52
+ ---
53
+
54
+ ### 2. `znatok_find_similar`
55
+ * **Назначение**: Умный мультифакторный поиск аналогов и дубликатов кода (60% векторный косинус + 30% граф вызовов Jaccard + 10% AST-роли).
56
+ * **Параметры**:
57
+ * `target` *(string)*: Имя символа, функции или класса в проекте (например `"Server.runFullScan"`). При указании вектор берется из БД напрямую **без обращения к LLM**.
58
+ * `query` *(string)*: Текстовое описание или код для поиска аналогов (используется, если `target` не задан).
59
+ * `limit` *(number)*: Максимальное число результатов (по умолчанию `10`).
60
+ * `callers_level` / `callees_level` *(number)*: Глубина связанных вызовов (по умолчанию `3`).
61
+ * `include_code` *(boolean)* / `max_code_lines` *(number)*: Параметры включения кода (по умолчанию `30` строк).
62
+ * `role` / `type` / `file_pattern` *(string)*: Фильтры по архитектуре и путям файлов.
63
+
64
+ ---
65
+
66
+ ### 3. `znatok_get_subgraph`
67
+ * **Назначение**: Построение подграфа окрестностей символа/файла или трассировка вызовов от точки `from` к точке `to`.
68
+ * **Параметры**:
69
+ * `target` *(string)*: Символ или относительный путь файла для вывода его окрестностей.
70
+ * `from` / `to` *(string)*: Точки трассировки цепочки вызовов (DFS по графу).
71
+ * `depth` *(number)*: Глубина обхода подграфа (по умолчанию `2`).
72
+ * `max_nodes` *(number)*: Максимальное количество узлов подграфа (по умолчанию `30`).
73
+ * `format` *(string)*: Формат ответа (`"mermaid"` для Markdown-диаграмм или `"json"`, по умолчанию `"mermaid"`).
74
+
75
+ ---
76
+
77
+ ### 4. `znatok_file_outline`
78
+ * **Назначение**: Анатомический семантический атлас (оглавление) файла за 1 запрос без замусоривания контекста.
79
+ * **Параметры**:
80
+ * `path` *(string, обязательный)*: Путь к целевому файлу (например `"internal/engine/server.go"`).
81
+ * `include_code` *(boolean)*: Включать ли фрагменты исходного кода для каждого символа.
82
+
83
+ ---
84
+
85
+ ### 5. `znatok_server_logs`
86
+ * **Назначение**: Чтение системных логов и событий сервера Znt в реальном времени через WebSocket.
87
+ * **Параметры**: Отсутствуют.
88
+
89
+ ---
90
+
91
+ ### 6. `znatok_mcp_stats`
92
+ * **Назначение**: Детальная метрика работы MCP-сервера и статистика сэкономленных токенов из SQLite.
93
+ * **Параметры**: Отсутствуют.
94
+
95
+ ---
96
+
97
+ ## 📊 Структура ответа и трекинг контекста (`_meta`)
98
+
99
+ Каждый инструмент возвращает обёртку со служебным объектом `_meta`:
100
+
101
+ ```json
102
+ {
103
+ "_meta": {
104
+ "tool": "znatok_semantic_search",
105
+ "response_tokens": 420,
106
+ "execution_ms": 15,
107
+ "last_call_saved_tokens": 12500,
108
+ "session_saved_tokens": 34000,
109
+ "alternative_cost": {
110
+ "tokens": 12920,
111
+ "description": "объем 3 затрагиваемых файлов целиком",
112
+ "savings_ratio": "30.8x"
113
+ },
114
+ "data_sources": ["core_api:search"]
115
+ },
116
+ "result": [ ... ]
117
+ }
118
+ ```
119
+
120
+ ---
121
+
122
+ ## ⚙️ Переменные окружения
123
+
124
+ | Переменная | Назначение | Значение по умолчанию |
125
+ | :--- | :--- | :--- |
126
+ | `ZNT_API_URL` | Базовый URL запущенного сервера Znt (HTTP & WS) | `http://localhost:8080` |
41
127
 
42
128
  ---
43
129
 
44
- ## 🚀 Особенности работы
130
+ ## 💾 Хранение данных
45
131
 
46
- 1. **Единая интеграция с Znt Core API**: Все поисковые, графовые и семантические запросы к кодовой базе выполняются через HTTP API и WebSocket запущенного сервера Znt (`ZNT_API_URL`, по умолчанию `http://localhost:8080`).
47
- 2. **Локальный Usage Tracking**: SQLite (`node:sqlite`) используется только для локального логирования метрик использования в `.znt/mcp_usage.db`, мгновенно рассчитывая объем сэкономленного контекста по сравнению с прямым чтением исходных файлов.
132
+ Статистика вызовов и экономии токенов сохраняется локально в базе данных SQLite:
133
+ * Путь к БД: `.znt/mcp_usage.db` в корневом каталоге проекта.
48
134
 
49
135
  ---
50
136
 
51
137
  ## 📋 Системные требования
52
138
 
53
- * **Node.js** версии **v22.5.0** или новее.
54
- * Индексированный проект с папкой `.znt` в корневом каталоге репозитория.
139
+ * **Node.js** версии **v22.5.0** или новее (используется встроенный модуль `node:sqlite`).
140
+ * Запущенный локальный сервер Znt (`http://localhost:8080`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@znt/mcp",
3
- "version": "1.0.4",
3
+ "version": "1.0.6",
4
4
  "description": "Model Context Protocol adapter for Znt",
5
5
  "main": "index.js",
6
6
  "type": "module",
@@ -31,4 +31,4 @@
31
31
  "@modelcontextprotocol/sdk": "^1.0.1",
32
32
  "ws": "^8.21.1"
33
33
  }
34
- }
34
+ }