@znt/mcp 1.0.4 → 1.0.5
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.
- package/README.md +97 -16
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
|
-
# Znt MCP Adapter (@znt/mcp)
|
|
1
|
+
# Znt MCP Adapter (@znt/mcp v1.1.0)
|
|
2
2
|
|
|
3
3
|
Официальный адаптер **Model Context Protocol (MCP)** для системы локального понимания кодовых баз и графового анализа **Знаток (Znt)**.
|
|
4
4
|
|
|
5
|
-
Позволяет внешним ИИ-агентам и LLM-клиентам (Claude Desktop, Antigravity IDE, Cursor, Windsurf, Zed и др.) осуществлять
|
|
5
|
+
Позволяет внешним ИИ-агентам и LLM-клиентам (Claude Desktop, Antigravity IDE, Cursor, Windsurf, Zed, Codex и др.) осуществлять гибридный и мультифакторный поиск по смыслу, получать семантические оглавления файлов, строить графы вызовов и трассировать зависимости с прозрачным трекингом экономии контекстных токенов.
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## ⚡ Быстрый старт (npx)
|
|
10
10
|
|
|
11
|
-
Не требуется предварительная сборка или ручная установка. Для подключения добавьте адаптер в ваш конфигурационный файл MCP (например, `~/.gemini/config/mcp_config.json` или `claude_desktop_config.json`):
|
|
11
|
+
Не требуется предварительная сборка или ручная установка. Для подключения добавьте адаптер в ваш конфигурационный файл MCP (например, `~/.gemini/config/mcp_config.json`, `.cursor/mcp.json` или `claude_desktop_config.json`):
|
|
12
12
|
|
|
13
13
|
```json
|
|
14
14
|
{
|
|
@@ -30,25 +30,106 @@
|
|
|
30
30
|
|
|
31
31
|
Адаптер предоставляет 6 специализированных инструментов с автоматическим отслеживанием экономии контекста:
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
33
|
+
### 1. `znatok_semantic_search`
|
|
34
|
+
* **Назначение**: Семантический и гибридный поиск (BM25 + Векторы + RRF) по элементам кодовой базы.
|
|
35
|
+
* **Параметры**:
|
|
36
|
+
* `query` *(string, обязательный)*: Поисковый запрос на естественном языке.
|
|
37
|
+
* `limit` *(number)*: Максимальное число результатов (по умолчанию `10`, макс `100`).
|
|
38
|
+
* `callers_level` *(number)*: Глубина графа входящих вызовов (по умолчанию `3`).
|
|
39
|
+
* `callees_level` *(number)*: Глубина графа исходящих вызовов (по умолчанию `3`).
|
|
40
|
+
* `include_code` *(boolean)*: Включать ли фрагменты исходного кода узлов.
|
|
41
|
+
* `max_code_lines` *(number)*: Максимум строк кода на узел (по умолчанию `30`).
|
|
42
|
+
* `role` *(string)*: Фильтр по архитектурной роли (`"controller"`, `"service"`, `"repository"`, `"model"`).
|
|
43
|
+
* `type` *(string)*: Фильтр по типу узла AST (`"function"`, `"struct"`, `"class"`, `"interface"`).
|
|
44
|
+
* `file_pattern` *(string)*: Маска пути файла (например `"pkg/semantic/*"` или `"*.go"`).
|
|
45
|
+
* `hybrid` *(boolean)*: Использовать гибридный RRF поиск (BM25 + Векторы, по умолчанию `true`).
|
|
41
46
|
|
|
42
47
|
---
|
|
43
48
|
|
|
44
|
-
|
|
49
|
+
### 2. `znatok_find_similar`
|
|
50
|
+
* **Назначение**: Умный мультифакторный поиск аналогов и дубликатов кода (60% векторный косинус + 30% граф вызовов Jaccard + 10% AST-роли).
|
|
51
|
+
* **Параметры**:
|
|
52
|
+
* `target` *(string)*: Имя символа, функции или класса в проекте (например `"Server.runFullScan"`). При указании вектор берется из БД напрямую **без обращения к LLM**.
|
|
53
|
+
* `query` *(string)*: Текстовое описание или код для поиска аналогов (используется, если `target` не задан).
|
|
54
|
+
* `limit` *(number)*: Максимальное число результатов (по умолчанию `10`).
|
|
55
|
+
* `callers_level` / `callees_level` *(number)*: Глубина связанных вызовов (по умолчанию `3`).
|
|
56
|
+
* `include_code` *(boolean)* / `max_code_lines` *(number)*: Параметры включения кода (по умолчанию `30` строк).
|
|
57
|
+
* `role` / `type` / `file_pattern` *(string)*: Фильтры по архитектуре и путям файлов.
|
|
45
58
|
|
|
46
|
-
|
|
47
|
-
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
### 3. `znatok_get_subgraph`
|
|
62
|
+
* **Назначение**: Построение подграфа окрестностей символа/файла или трассировка вызовов от точки `from` к точке `to`.
|
|
63
|
+
* **Параметры**:
|
|
64
|
+
* `target` *(string)*: Символ или относительный путь файла для вывода его окрестностей.
|
|
65
|
+
* `from` / `to` *(string)*: Точки трассировки цепочки вызовов (DFS по графу).
|
|
66
|
+
* `depth` *(number)*: Глубина обхода подграфа (по умолчанию `2`).
|
|
67
|
+
* `max_nodes` *(number)*: Максимальное количество узлов подграфа (по умолчанию `30`).
|
|
68
|
+
* `format` *(string)*: Формат ответа (`"mermaid"` для Markdown-диаграмм или `"json"`, по умолчанию `"mermaid"`).
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
### 4. `znatok_file_outline`
|
|
73
|
+
* **Назначение**: Анатомический семантический атлас (оглавление) файла за 1 запрос без замусоривания контекста.
|
|
74
|
+
* **Параметры**:
|
|
75
|
+
* `path` *(string, обязательный)*: Путь к целевому файлу (например `"internal/engine/server.go"`).
|
|
76
|
+
* `include_code` *(boolean)*: Включать ли фрагменты исходного кода для каждого символа.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
### 5. `znatok_server_logs`
|
|
81
|
+
* **Назначение**: Чтение системных логов и событий сервера Znt в реальном времени через WebSocket.
|
|
82
|
+
* **Параметры**: Отсутствуют.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
### 6. `znatok_mcp_stats`
|
|
87
|
+
* **Назначение**: Детальная метрика работы MCP-сервера и статистика сэкономленных токенов из SQLite.
|
|
88
|
+
* **Параметры**: Отсутствуют.
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## 📊 Структура ответа и трекинг контекста (`_meta`)
|
|
93
|
+
|
|
94
|
+
Каждый инструмент возвращает обёртку со служебным объектом `_meta`:
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"_meta": {
|
|
99
|
+
"tool": "znatok_semantic_search",
|
|
100
|
+
"response_tokens": 420,
|
|
101
|
+
"execution_ms": 15,
|
|
102
|
+
"last_call_saved_tokens": 12500,
|
|
103
|
+
"session_saved_tokens": 34000,
|
|
104
|
+
"alternative_cost": {
|
|
105
|
+
"tokens": 12920,
|
|
106
|
+
"description": "объем 3 затрагиваемых файлов целиком",
|
|
107
|
+
"savings_ratio": "30.8x"
|
|
108
|
+
},
|
|
109
|
+
"data_sources": ["core_api:search"]
|
|
110
|
+
},
|
|
111
|
+
"result": [ ... ]
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## ⚙️ Переменные окружения
|
|
118
|
+
|
|
119
|
+
| Переменная | Назначение | Значение по умолчанию |
|
|
120
|
+
| :--- | :--- | :--- |
|
|
121
|
+
| `ZNT_API_URL` | Базовый URL запущенного сервера Znt (HTTP & WS) | `http://localhost:8080` |
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 💾 Хранение данных
|
|
126
|
+
|
|
127
|
+
Статистика вызовов и экономии токенов сохраняется локально в базе данных SQLite:
|
|
128
|
+
* Путь к БД: `.znt/mcp_usage.db` в корневом каталоге проекта.
|
|
48
129
|
|
|
49
130
|
---
|
|
50
131
|
|
|
51
132
|
## 📋 Системные требования
|
|
52
133
|
|
|
53
|
-
* **Node.js** версии **v22.5.0** или
|
|
54
|
-
*
|
|
134
|
+
* **Node.js** версии **v22.5.0** или новее (используется встроенный модуль `node:sqlite`).
|
|
135
|
+
* Запущенный локальный сервер Znt (`http://localhost:8080`).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@znt/mcp",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.5",
|
|
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
|
+
}
|