@znt/mcp 1.0.1

package/README.md

@@ -0,0 +1,55 @@
+# Znt MCP Adapter (@znt/mcp)
+
+Официальный адаптер **Model Context Protocol (MCP)** для системы локального понимания кодовых баз и графового анализа **Знаток (Znt)**.
+
+Позволяет внешним ИИ-агентам и LLM-клиентам (Claude Desktop, Antigravity IDE, Cursor, Windsurf, Zed и др.) осуществлять умный гибридный поиск по смыслу, получать оглавления файлов, строить графы вызовов и трассировать зависимости с 0ms LLM оверхедом и максимальной экономией контекстных токенов.
+
+---
+
+## ⚡ Быстрый старт (npx)
+
+Не требуется предварительная сборка или ручная установка. Для подключения добавьте адаптер в ваш конфигурационный файл MCP (например, `~/.gemini/config/mcp_config.json` или `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "znt-mcp": {
+      "command": "npx",
+      "args": ["-y", "@znt/mcp"],
+      "env": {
+        "ZNT_API_URL": "http://localhost:8080"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🛠 Доступные инструменты (MCP Tools)
+
+Адаптер предоставляет 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. **Прямой доступ к SQLite БД**: Адаптер напрямую читает локальные базы данных `.znt/graph.db` и `.znt/analysis.db` через встроенный модуль `node:sqlite`, обеспечивая микросекундный отклик.
+2. **Интеграция с Znt Core API**: Для векторного семантического поиска и генеративного теггирования адаптер взаимодействует с HTTP API сервера Znt (`ZNT_API_URL`).
+3. **Usage Tracking**: Каждая операция логируется в `.znt/mcp_usage.db`, рассчитывая объем сэкономленного контекста по сравнению с прямым прочтением исходных файлов.
+
+---
+
+## 📋 Системные требования
+
+* **Node.js** версии **v22.5.0** или новее.
+* Индексированный проект с папкой `.znt` в корневом каталоге репозитория.

package/index.js

@@ -0,0 +1,680 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError
+} from '@modelcontextprotocol/sdk/types.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+
+// ─── Helper: find Znt state/database folder ─────────────────────
+function findZntDir() {
+  let currentDir = process.cwd();
+  while (currentDir) {
+    const candidate = path.join(currentDir, '.znt');
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+    const parent = path.dirname(currentDir);
+    if (parent === currentDir) {
+      break;
+    }
+    currentDir = parent;
+  }
+
+  // Fallback: check relative to the script location (parent of znt_mcp folder)
+  try {
+    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+    const projectRoot = path.resolve(scriptDir, '..');
+    const candidate = path.join(projectRoot, '.znt');
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+  } catch (err) {
+    // Ignore error
+  }
+
+  return path.resolve(process.cwd(), '.znt');
+}
+
+function toRelativePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return filePath;
+  const projectRoot = path.dirname(findZntDir());
+  if (filePath.startsWith(projectRoot)) {
+    const rel = path.relative(projectRoot, filePath);
+    return rel ? rel : filePath;
+  }
+  return filePath;
+}
+
+// ─── Helper: Source snippet ──────────────────────────────────────
+function getSourceSnippet(filePath, startLine, endLine) {
+  try {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(path.dirname(findZntDir()), filePath);
+    if (!fs.existsSync(absolutePath)) return `File not found: ${filePath}`;
+    const lines = fs.readFileSync(absolutePath, 'utf8').split('\n');
+    const start = Math.max(1, startLine) - 1;
+    const end = Math.min(lines.length, endLine);
+    return lines.slice(start, end).join('\n');
+  } catch (err) {
+    return `Error reading file: ${err.message}`;
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════
+//  Usage Tracking & Metrics State
+// ═════════════════════════════════════════════════════════════════
+
+const sessionStartTime = new Date().toISOString();
+let sessionOutputTokens = 0;
+let sessionSavedTokens = 0;
+let sessionCallsCount = 0;
+let lastCallSavedTokens = 0;
+
+/**
+ * Opens (or creates) the MCP usage tracking SQLite database.
+ * Stored alongside graph.db in .znt/mcp_usage.db
+ */
+function getUsageDb() {
+  const zntDir = findZntDir();
+  const usageDbPath = path.join(zntDir, 'mcp_usage.db');
+  try {
+    const db = new DatabaseSync(usageDbPath);
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS mcp_usage_log (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp TEXT NOT NULL,
+        tool_name TEXT NOT NULL,
+        input_tokens INTEGER DEFAULT 0,
+        output_tokens INTEGER DEFAULT 0,
+        execution_ms INTEGER DEFAULT 0,
+        estimated_alt_tokens INTEGER DEFAULT 0,
+        cache_hit INTEGER DEFAULT 0
+      )
+    `);
+    return db;
+  } catch (err) {
+    console.error('Failed to open usage tracking database:', err);
+    return null;
+  }
+}
+
+/**
+ * Rough token estimation: ~4 chars per token.
+ */
+function estimateTokens(text) {
+  if (!text) return 0;
+  const str = typeof text === 'string' ? text : JSON.stringify(text);
+  return Math.ceil(str.length / 4);
+}
+
+/**
+ * Helper to compute total file tokens for unique file paths on disk
+ */
+function getFilesTotalTokens(filePaths) {
+  if (!Array.isArray(filePaths) || filePaths.length === 0) return 0;
+  const projectRoot = path.dirname(findZntDir());
+  const uniquePaths = new Set();
+  let totalBytes = 0;
+
+  for (const fp of filePaths) {
+    if (!fp || typeof fp !== 'string') continue;
+    const absPath = path.isAbsolute(fp) ? fp : path.resolve(projectRoot, fp);
+    if (!uniquePaths.has(absPath) && fs.existsSync(absPath)) {
+      uniquePaths.add(absPath);
+      try {
+        const stat = fs.statSync(absPath);
+        if (stat.isFile()) {
+          totalBytes += stat.size;
+        }
+      } catch (err) {
+        // Ignore stat error
+      }
+    }
+  }
+
+  return Math.ceil(totalBytes / 4);
+}
+
+/**
+ * Extract all involved file paths from tool results or metadata
+ */
+function extractInvolvedFiles(toolName, data, meta) {
+  const files = [];
+  if (meta && meta.targetFile) {
+    files.push(meta.targetFile);
+  }
+  if (!data) return files;
+
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      if (item && typeof item === 'object') {
+        if (item.file) files.push(item.file);
+        if (item.file_path) files.push(item.file_path);
+        if (item.filePath) files.push(item.filePath);
+      }
+    }
+  } else if (typeof data === 'object') {
+    if (data.file) files.push(data.file);
+    if (data.file_path) files.push(data.file_path);
+    if (data.filePath) files.push(data.filePath);
+
+    if (Array.isArray(data.result)) {
+      for (const item of data.result) {
+        if (item && typeof item === 'object') {
+          if (item.file) files.push(item.file);
+          if (item.file_path) files.push(item.file_path);
+          if (item.filePath) files.push(item.filePath);
+        }
+      }
+    }
+    if (Array.isArray(data.nodes)) {
+      for (const node of data.nodes) {
+        if (node && typeof node === 'object') {
+          if (node.file) files.push(node.file);
+          if (node.file_path) files.push(node.file_path);
+          if (node.filePath) files.push(node.filePath);
+        }
+      }
+    }
+  }
+  return files;
+}
+
+/**
+ * Alternative-cost multiplier table for active tools (fallback).
+ */
+const ALT_COST_MAP = {
+  znatok_semantic_search: { description: 'поиск по векторам и лексике + контекст', multiplier: 10 },
+  znatok_find_similar:    { description: 'поиск семантически похожих элементов',     multiplier: 10 },
+  znatok_get_subgraph:    { description: 'трассировка и подграф вызовов в 1 запрос',  multiplier: 25 },
+  znatok_file_outline:    { description: 'полный анатомический оглавление-атлас файла', multiplier: 15 },
+  znatok_server_logs:     { description: 'ручное подключение к WebSocket',           multiplier: 3 },
+  znatok_mcp_stats:       { description: 'данные доступны только через MCP',         multiplier: 1 },
+};
+
+function estimateAlternativeCost(toolName, outputTokens, data, meta) {
+  const involvedFiles = extractInvolvedFiles(toolName, data, meta);
+  const fileTokens = getFilesTotalTokens(involvedFiles);
+
+  if (fileTokens > 0) {
+    const ratio = outputTokens > 0 ? (fileTokens / outputTokens).toFixed(1) : '1.0';
+    return {
+      tokens: fileTokens,
+      description: `объем ${involvedFiles.length} затрагиваемых файлов целиком`,
+      savings_ratio: `${ratio}x`
+    };
+  }
+
+  const alt = ALT_COST_MAP[toolName];
+  if (!alt) return { tokens: outputTokens, description: 'сопоставимо с прямым подходом', savings_ratio: '1.0x' };
+
+  return {
+    tokens: Math.ceil(outputTokens * alt.multiplier),
+    description: alt.description,
+    savings_ratio: `${alt.multiplier}.0x`
+  };
+}
+
+function logUsage(toolName, inputTokens, outputTokens, executionMs, alternativeTokens, cacheHit = false) {
+  let usageDb = null;
+  try {
+    usageDb = getUsageDb();
+    if (!usageDb) return;
+    usageDb.prepare(`
+      INSERT INTO mcp_usage_log (timestamp, tool_name, input_tokens, output_tokens, execution_ms, estimated_alt_tokens, cache_hit)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(new Date().toISOString(), toolName, inputTokens, outputTokens, executionMs, alternativeTokens, cacheHit ? 1 : 0);
+  } catch (err) {
+    console.error('Failed to log usage:', err);
+  } finally {
+    if (usageDb) try { usageDb.close(); } catch (e) {}
+  }
+}
+
+function mcpResponse(toolName, data, meta = {}) {
+  const resultText = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+  const outputTokens = estimateTokens(resultText);
+  const inputTokens = meta.inputTokens || 0;
+  const executionMs = meta.executionMs || 0;
+  const altCost = estimateAlternativeCost(toolName, outputTokens, data, meta);
+
+  const callSavedTokens = Math.max(0, altCost.tokens - outputTokens);
+  lastCallSavedTokens = callSavedTokens;
+  sessionOutputTokens += outputTokens;
+  sessionSavedTokens += callSavedTokens;
+  sessionCallsCount += 1;
+
+  logUsage(toolName, inputTokens, outputTokens, executionMs, altCost.tokens, meta.cacheHit || false);
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        _meta: {
+          tool: toolName,
+          response_tokens: outputTokens,
+          execution_ms: executionMs,
+          last_call_saved_tokens: callSavedTokens,
+          session_saved_tokens: sessionSavedTokens,
+          alternative_cost: altCost,
+          data_sources: meta.sources || []
+        },
+        result: data
+      }, null, 2)
+    }]
+  };
+}
+
+
+// ═════════════════════════════════════════════════════════════════
+//  Server Initialization
+// ═════════════════════════════════════════════════════════════════
+
+const server = new Server(
+  { name: 'znt-mcp-server', version: '1.1.0' },
+  { capabilities: { tools: {} } }
+);
+
+// ─── Register Tools (ListTools) ──────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'znatok_semantic_search',
+        description: 'Выполняет векторный семантический поиск элементов кода (функций, классов, модулей) по естественному языку и описанию их назначения в проекте. Позволяет находить узлы графа и их взаимосвязи ("где вызывается" и "где вызывают") с возможностью глубокой детализации. Возвращает совпадения с коэффициентами сходства (score), аннотациями, относительным путем к файлу и графом вызовов.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Поисковый запрос на естественном языке (например: "обработка HTTP запросов в сервере")' },
+            limit: { type: 'number', description: 'Максимальное количество результатов поиска (по умолчанию 10)' },
+            callers_level: { type: 'number', description: 'Глубина вложенности графа входящих вызовов ("где вызывается"), по умолчанию 3' },
+            callees_level: { type: 'number', description: 'Глубина вложенности графа исходящих вызовов ("где вызывают"), по умолчанию 3' },
+            include_code: { type: 'boolean', description: 'Включать ли исходный код (фрагмент узла) в результаты поиска' },
+            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']
+        },
+      },
+      {
+        name: 'znatok_find_similar',
+        description: 'Ищет элементы кода в базе знаний проекта, которые являются семантически близкими по назначению к заданному фрагменту текста или сигнатуре. Помогает находить дубликаты, аналогичные методы или связанные абстракции. Возвращает список объектов с относительными путями файлов и структурой графа.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Текстовый фрагмент или описание функции/класса для поиска аналогов' },
+            limit: { type: 'number', description: 'Максимальное количество возвращаемых элементов (по умолчанию 10)' },
+            callers_level: { type: 'number', description: 'Глубина вложенности входящего графа вызовов ("где вызывается"), по умолчанию 3' },
+            callees_level: { type: 'number', description: 'Глубина вложенности исходящего графа вызовов ("где вызывают"), по умолчанию 3' },
+            include_code: { type: 'boolean', description: 'Включать ли исходный код (фрагмент узла) в результаты поиска' },
+            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']
+        },
+      },
+      {
+        name: 'znatok_get_subgraph',
+        description: 'Возвращает ориентированный подграф (в формате Mermaid или JSON) вокруг заданного символа/файла (target) или вычисляет трассу вызовов между двумя точками (from -> to). Позволяет быстро визуализировать и исследовать архитектуру компонентов, цепочки вызовов и зависимости за 1 запрос без использования LLM.',
+        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)' },
+            max_nodes: { type: 'number', description: 'Максимальное количество узлов подграфа (по умолчанию 30)' },
+            format: { type: 'string', description: 'Формат ответа: "mermaid" для диаграммы в Markdown или "json" (по умолчанию "mermaid")' }
+          }
+        },
+      },
+      {
+        name: 'znatok_file_outline',
+        description: 'Возвращает полную семантическую карту-атлас (оглавление) файла: 100% объявленных символов (функций, методов, структур, классов, интерфейсов), упорядоченных по номеру строки (start_line ASC), с их архитектурными ролями, диапазонами строк и семантическими описаниями. Позволяет мгновенно понять анатомию любого большого файла за 1 запрос без замусоривания контекста.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Относительный или абсолютный путь к целевому файлу (например: "internal/engine/server.go")' },
+            include_code: { type: 'boolean', description: 'Включать ли фрагменты/сигнатуры исходного кода для каждого символа' }
+          },
+          required: ['path']
+        },
+      },
+      {
+        name: 'znatok_server_logs',
+        description: 'Считывает последние события и системные логи сервера Znt в реальном времени через WebSocket. Используется для диагностики состояния индексации проекта, отслеживания прогресса анализа и отладки работы фоновых процессов.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'znatok_mcp_stats',
+        description: 'Возвращает подробную метрику и статистику работы MCP-сервера Znt: общее число вызовов, количество потраченных и сэкономленных токенов, коэффициент оптимизации (savings_ratio), среднее время выполнения запросов в миллисекундах и топ самых активных инструментов.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+    ],
+  };
+});
+
+// ─── Helper for HTTP requests to Znt Core API ────────────────────
+async function callZntApi(endpoint, method = 'GET', body = null) {
+  const apiUrl = process.env.ZNT_API_URL || 'http://localhost:8080';
+  const url = `${apiUrl}${endpoint}`;
+  const options = {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : {},
+  };
+  if (body) {
+    options.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(url, options);
+  if (!response.ok) {
+    throw new Error(`API call failed: ${response.status} ${response.statusText}`);
+  }
+
+  if (response.headers.get('content-type')?.includes('text/event-stream')) {
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    let accumulated = '';
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      accumulated += decoder.decode(value, { stream: true });
+      const lines = accumulated.split('\n');
+      accumulated = lines.pop();
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          try {
+            const data = JSON.parse(line.slice(6));
+            if (data.type === 'token') {
+              text += data.content;
+            } else if (data.type === 'error') {
+              throw new Error(data.content);
+            }
+          } catch (err) {
+            if (!err.message.includes('JSON')) {
+              throw err;
+            }
+          }
+        }
+      }
+    }
+    return { content: text };
+  }
+
+  return response.json();
+}
+
+// ═════════════════════════════════════════════════════════════════
+//  Tool Calls Router
+// ═════════════════════════════════════════════════════════════════
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const startTime = Date.now();
+  const toolName = request.params.name;
+  const inputTokens = estimateTokens(JSON.stringify(request.params.arguments || {}));
+
+  try {
+    let result;
+    let sources = [];
+
+    switch (toolName) {
+      case 'znatok_find_similar':
+      case 'znatok_semantic_search': {
+        const query = request.params.arguments?.query || request.params.arguments?.text;
+        if (!query) {
+          result = '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 hybrid = request.params.arguments?.hybrid !== false;
+
+        const apiParams = new URLSearchParams({
+          q: query,
+          limit: limit.toString(),
+          callers_level: callersLevel.toString(),
+          callees_level: calleesLevel.toString(),
+          include_code: includeCode.toString(),
+          max_code_lines: maxCodeLines.toString(),
+          hybrid: hybrid.toString(),
+        });
+        if (role) apiParams.set('role', role);
+        if (nodeType) apiParams.set('type', nodeType);
+        if (filePattern) apiParams.set('file_pattern', filePattern);
+
+        const rawResults = await callZntApi(`/api/search?${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:search'];
+        break;
+      }
+
+      case 'znatok_get_subgraph': {
+        const target = request.params.arguments?.target || '';
+        const from = request.params.arguments?.from || '';
+        const to = request.params.arguments?.to || '';
+        const depth = parseInt(request.params.arguments?.depth, 10) || 2;
+        const maxNodes = parseInt(request.params.arguments?.max_nodes, 10) || 30;
+        const format = request.params.arguments?.format || 'mermaid';
+
+        const queryParams = new URLSearchParams();
+        if (target) queryParams.set('target', target);
+        if (from) queryParams.set('from', from);
+        if (to) queryParams.set('to', to);
+        queryParams.set('depth', depth.toString());
+        queryParams.set('max_nodes', maxNodes.toString());
+        if (format) queryParams.set('format', format);
+
+        const resData = await callZntApi(`/api/graph/subgraph?${queryParams.toString()}`);
+        result = resData;
+        sources = ['core_api:subgraph'];
+        break;
+      }
+
+      case 'znatok_file_outline': {
+        const filePath = request.params.arguments?.path || request.params.arguments?.target_path || request.params.arguments?.file || request.params.arguments?.file_path || '';
+        if (!filePath) {
+          result = 'Path parameter is required.';
+          break;
+        }
+        const includeCode = Boolean(request.params.arguments?.include_code);
+
+        const queryParams = new URLSearchParams({
+          path: filePath,
+          include_code: includeCode.toString(),
+        });
+
+        const resData = await callZntApi(`/api/file/outline?${queryParams.toString()}`);
+        result = resData;
+        sources = ['core_api:file_outline'];
+        break;
+      }
+
+      case 'znatok_server_logs': {
+        const wsUrl = (process.env.ZNT_API_URL || 'http://localhost:8080').replace(/^http/, 'ws') + '/ws';
+        let WebSocketClient = globalThis.WebSocket;
+        if (!WebSocketClient) {
+          try {
+            WebSocketClient = (await import('ws')).default;
+          } catch (err) {
+            // ignore
+          }
+        }
+
+        if (!WebSocketClient) {
+          result = 'WebSocket client is not available in current Node environment.';
+          sources = ['core_api:websocket'];
+          break;
+        }
+
+        const logs = await new Promise((resolve) => {
+          const timeout = setTimeout(() => resolve('Log retrieval timed out.'), 3000);
+          let resolved = false;
+          const ws = new WebSocketClient(wsUrl);
+
+          ws.onopen = () => {};
+          ws.onmessage = (event) => {
+            if (resolved) return;
+            try {
+              const msg = JSON.parse(event.data);
+              if (msg.type === 'initial_state') {
+                clearTimeout(timeout);
+                resolved = true;
+                ws.close();
+                resolve(msg.logs || []);
+              }
+            } catch (err) {}
+          };
+
+          ws.onerror = (err) => {
+            if (!resolved) {
+              clearTimeout(timeout);
+              resolved = true;
+              resolve(`WebSocket Connection Error: ${err.message}`);
+            }
+          };
+        });
+
+        result = logs;
+        sources = ['core_api:websocket'];
+        break;
+      }
+
+      case 'znatok_mcp_stats': {
+        let usageDb = null;
+        try {
+          usageDb = getUsageDb();
+          if (!usageDb) { result = 'Usage tracking database not available.'; break; }
+
+          const totalCalls = usageDb.prepare('SELECT count(*) as count FROM mcp_usage_log').get().count;
+          const totalOutputTokens = usageDb.prepare('SELECT COALESCE(sum(output_tokens), 0) as total FROM mcp_usage_log').get().total;
+          const totalAltTokens = usageDb.prepare('SELECT COALESCE(sum(estimated_alt_tokens), 0) as total FROM mcp_usage_log').get().total;
+          const avgExecutionMs = usageDb.prepare('SELECT COALESCE(avg(execution_ms), 0) as avg FROM mcp_usage_log').get().avg;
+
+          const topTools = usageDb.prepare(`
+            SELECT tool_name, 
+                   count(*) as calls, 
+                   sum(output_tokens) as total_output, 
+                   sum(estimated_alt_tokens) as total_alt,
+                   CAST(avg(execution_ms) AS INTEGER) as avg_ms,
+                   CASE WHEN sum(output_tokens) > 0 
+                     THEN ROUND(CAST(sum(estimated_alt_tokens) AS REAL) / sum(output_tokens), 1) 
+                     ELSE 0 END as savings_ratio
+            FROM mcp_usage_log 
+            GROUP BY tool_name 
+            ORDER BY calls DESC 
+            LIMIT 20
+          `).all();
+
+          const recentCalls = usageDb.prepare(`
+            SELECT timestamp, tool_name, output_tokens, estimated_alt_tokens, execution_ms
+            FROM mcp_usage_log 
+            ORDER BY id DESC 
+            LIMIT 10
+          `).all();
+
+          result = {
+            last_call_saved_tokens: lastCallSavedTokens,
+            session_saved_tokens: sessionSavedTokens,
+            session_output_tokens: sessionOutputTokens,
+            session_calls: sessionCallsCount,
+            session_start_time: sessionStartTime,
+            total_calls: totalCalls,
+            total_output_tokens: totalOutputTokens,
+            estimated_alternative_tokens: totalAltTokens,
+            total_saved_tokens: Math.max(0, totalAltTokens - totalOutputTokens),
+            savings_ratio: totalOutputTokens > 0 ? `${(totalAltTokens / totalOutputTokens).toFixed(1)}x` : 'N/A',
+            avg_execution_ms: Math.round(avgExecutionMs),
+            top_tools: topTools,
+            recent_calls: recentCalls
+          };
+          sources = ['mcp_usage.db'];
+        } catch (err) {
+          result = `Error fetching stats: ${err.message}`;
+        } finally {
+          if (usageDb) try { usageDb.close(); } catch (e) {}
+        }
+        break;
+      }
+
+      default:
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${toolName}`);
+    }
+
+    // ── Wrap result with _meta and log usage ──
+    return mcpResponse(toolName, result, {
+      executionMs: Date.now() - startTime,
+      inputTokens,
+      sources
+    });
+
+  } catch (err) {
+    if (err instanceof McpError) throw err;
+
+    // Log the failed call too
+    const executionMs = Date.now() - startTime;
+    logUsage(toolName, inputTokens, 0, executionMs, 0, false);
+
+    return {
+      content: [{ type: 'text', text: `Error executing tool ${toolName}: ${err.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ═════════════════════════════════════════════════════════════════
+//  Run server using StdioTransport
+// ═════════════════════════════════════════════════════════════════
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Znt MCP Server v1.1.0 running on stdio (with usage tracking)');
+}
+
+main().catch((error) => {
+  console.error('Fatal error running server:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@znt/mcp",
+  "version": "1.0.1",
+  "description": "Model Context Protocol adapter for Znt",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "znt-mcp": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "ws": "^8.21.1",
+    "yaml": "^2.4.5"
+  }
+}