@znt/mcp 1.1.1 → 2.0.2

package/src/metrics.js

@@ -0,0 +1,121 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+const ALTERNATIVE_MULTIPLIERS = Object.freeze({
+  search: 10,
+  similar: 10,
+  graph: 25,
+  outline: 15,
+  logs: 3,
+  status: 1,
+  scan: 1,
+  stats: 1,
+});
+
+export class UsageMetrics {
+  constructor(options = {}) {
+    this.configuredFile = options.file ?? process.env.ZNT_MCP_METRICS_FILE;
+    this.metricsFile = this.configuredFile ? resolve(this.configuredFile) : undefined;
+    this.sessionStartTime = new Date().toISOString();
+    this.sessionRecords = [];
+  }
+
+  setProjectRoot(projectRoot) {
+    if (!this.configuredFile && projectRoot) this.metricsFile = join(projectRoot, ".znt", "mcp-usage.jsonl");
+  }
+
+  async record(toolName, input, output, executionMs) {
+    const inputTokens = estimateTokens(input);
+    const outputTokens = estimateTokens(output);
+    const estimatedAlternativeTokens = Math.ceil(outputTokens * (ALTERNATIVE_MULTIPLIERS[toolName] ?? 1));
+    const record = {
+      timestamp: new Date().toISOString(),
+      tool_name: toolName,
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      execution_ms: executionMs,
+      estimated_alternative_tokens: estimatedAlternativeTokens,
+      saved_tokens: Math.max(0, estimatedAlternativeTokens - outputTokens),
+    };
+    this.sessionRecords.push(record);
+    if (this.metricsFile) {
+      try {
+        await mkdir(dirname(this.metricsFile), { recursive: true });
+        await appendFile(this.metricsFile, `${JSON.stringify(record)}\n`, "utf8");
+      } catch {
+        // Metrics must never turn a successful code-intelligence call into a
+        // failed MCP tool response.
+      }
+    }
+    return record;
+  }
+
+  async snapshot() {
+    const persisted = await this.readPersistedRecords();
+    const session = summarize(this.sessionRecords);
+    const total = summarize(persisted.length ? persisted : this.sessionRecords);
+    return {
+      session_start_time: this.sessionStartTime,
+      session_calls: session.calls,
+      session_output_tokens: session.outputTokens,
+      session_saved_tokens: session.savedTokens,
+      last_call_saved_tokens: this.sessionRecords.at(-1)?.saved_tokens ?? 0,
+      total_calls: total.calls,
+      total_output_tokens: total.outputTokens,
+      estimated_alternative_tokens: total.alternativeTokens,
+      total_saved_tokens: total.savedTokens,
+      savings_ratio: total.outputTokens ? `${(total.alternativeTokens / total.outputTokens).toFixed(1)}x` : "N/A",
+      avg_execution_ms: Math.round(total.averageExecutionMs),
+      top_tools: summarizeTools(persisted.length ? persisted : this.sessionRecords),
+      recent_calls: (persisted.length ? persisted : this.sessionRecords).slice(-10).reverse(),
+      persistence: this.metricsFile ?? null,
+    };
+  }
+
+  async readPersistedRecords() {
+    if (!this.metricsFile) return [];
+    try {
+      return (await readFile(this.metricsFile, "utf8")).split("\n").filter(Boolean).flatMap((line) => {
+        try { return [JSON.parse(line)]; } catch { return []; }
+      });
+    } catch {
+      return [];
+    }
+  }
+}
+
+export function estimateTokens(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
+  return Math.ceil(text.length / 4);
+}
+
+function summarize(records) {
+  const execution = records.reduce((sum, record) => sum + Number(record.execution_ms || 0), 0);
+  return {
+    calls: records.length,
+    outputTokens: records.reduce((sum, record) => sum + Number(record.output_tokens || 0), 0),
+    alternativeTokens: records.reduce((sum, record) => sum + Number(record.estimated_alternative_tokens || 0), 0),
+    savedTokens: records.reduce((sum, record) => sum + Number(record.saved_tokens || 0), 0),
+    averageExecutionMs: records.length ? execution / records.length : 0,
+  };
+}
+
+function summarizeTools(records) {
+  const groups = new Map();
+  for (const record of records) {
+    const group = groups.get(record.tool_name) ?? [];
+    group.push(record);
+    groups.set(record.tool_name, group);
+  }
+  return [...groups.entries()].map(([toolName, toolRecords]) => {
+    const totals = summarize(toolRecords);
+    return {
+      tool_name: toolName,
+      calls: totals.calls,
+      total_output: totals.outputTokens,
+      total_alt: totals.alternativeTokens,
+      avg_ms: Math.round(totals.averageExecutionMs),
+      savings_ratio: totals.outputTokens ? Number((totals.alternativeTokens / totals.outputTokens).toFixed(1)) : 0,
+    };
+  }).sort((left, right) => right.calls - left.calls || left.tool_name.localeCompare(right.tool_name)).slice(0, 20);
+}

package/src/server.js

@@ -0,0 +1,30 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { TOOL_DEFINITIONS } from "./tool-definitions.js";
+import { ZntTools } from "./znt-tools.js";
+
+export function createZntMcpServer(options = {}) {
+  const tools = options.tools ?? new ZntTools(options);
+  const server = new Server(
+    { name: "znt-mcp-server", version: "2.0.2" },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFINITIONS }));
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => tools.call(
+    request.params.name,
+    request.params.arguments ?? {},
+    { signal: extra?.signal },
+  ));
+
+  return {
+    server,
+    tools,
+    initialize: () => tools.initialize(),
+    disconnect: () => tools.disconnect(),
+  };
+}

package/src/tool-definitions.js

@@ -0,0 +1,143 @@
+const searchProperties = {
+  query: { type: "string", minLength: 1, description: "Natural-language intent or an exact code symbol to find." },
+  mode: { type: "string", enum: ["hybrid", "lexical", "vector"], default: "hybrid", description: "Use lexical for exact identifiers, hybrid for intent, and vector for conceptual similarity." },
+  limit: { type: "integer", minimum: 1, maximum: 100, default: 10 },
+  callers_level: { type: "integer", minimum: 0, maximum: 10, default: 0 },
+  callees_level: { type: "integer", minimum: 0, maximum: 10, default: 0 },
+  compact: { type: "boolean", default: false, description: "Omit caller/callee graphs and return the compact result shape." },
+  include_code: { type: "boolean", default: false },
+  max_code_lines: { type: "integer", minimum: 1, maximum: 10000, default: 30 },
+  role_boost: { type: "string", minLength: 1, description: "Soft ranking boost for an architectural role." },
+  type_boost: { type: "string", minLength: 1, description: "Soft ranking boost for an AST type." },
+  file_pattern: { type: "string", minLength: 1, description: "Glob-like file path filter." },
+};
+
+export const TOOL_DEFINITIONS = Object.freeze([
+  {
+    name: "setup",
+    description: "Run this before scanning. Invoking with no arguments opens an interactive browser setup wizard to configure providers, API keys, models, and project settings. You can also pass mode to configure directly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        interactive: { type: "boolean", default: true, description: "Whether to open the browser setup wizard." },
+        mode: { type: "string", enum: ["bm25", "ollama", "openapi"], description: "BM25 uses no LLM or embeddings; ollama is local; openapi supports OpenRouter and compatible providers." },
+        provider_url: { type: "string", minLength: 1 },
+        model: { type: "string", minLength: 1, description: "Generation model name." },
+        embed_model: { type: "string", minLength: 1, description: "Embedding model name, or none to disable vector search." },
+        credential_source: { type: "string", enum: ["keyring", "env"], default: "keyring" },
+        token_env: { type: "string", pattern: "^[A-Za-z_][A-Za-z0-9_]*$", description: "Environment variable name only; never put its value here." },
+        semantic_mode: { type: "string", enum: ["fast", "llm"] },
+        description_language: { type: "string", minLength: 2, maxLength: 16 },
+        exclude: { type: "array", items: { type: "string", minLength: 1 }, uniqueItems: true },
+        check_provider: { type: "boolean", default: true },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "setup_status",
+    description: "Inspect whether Core, YAML configuration, credentials, and optionally the configured provider are ready. Never returns credential values.",
+    inputSchema: {
+      type: "object",
+      properties: { check_provider: { type: "boolean", default: false } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "search",
+    description: "Search indexed code after setup and scan. Prefer lexical for exact identifiers, hybrid for behavior, and vector for conceptual names.",
+    inputSchema: { type: "object", properties: searchProperties, required: ["query"], additionalProperties: false },
+  },
+  {
+    name: "similar",
+    description: "Find implementations, patterns, or potential duplicates similar to an indexed symbol or a text/code query. Requires embeddings.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", minLength: 1, description: "Existing symbol, qualified name, or file::symbol reference." },
+        query: { type: "string", minLength: 1, description: "Text or code used as the similarity reference or to rerank target results." },
+        limit: { type: "integer", minimum: 1, maximum: 100, default: 10 },
+        include_code: { type: "boolean", default: false },
+        max_code_lines: { type: "integer", minimum: 1, maximum: 10000, default: 30 },
+        role_boost: { type: "string", minLength: 1 },
+        type_boost: { type: "string", minLength: 1 },
+        file_pattern: { type: "string", minLength: 1 },
+        edge_types: { type: "string", description: "Comma-separated contains,call,inherits,implements values." },
+      },
+      anyOf: [{ required: ["target"] }, { required: ["query"] }],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "graph",
+    description: "Build a local dependency/call graph around `from`, or trace a path from `from` to `to`. Use qualified symbol names when a short name is ambiguous.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", minLength: 1 },
+        to: { type: "string", minLength: 1 },
+        depth: { type: "integer", minimum: 1, maximum: 100, default: 1 },
+        format: { type: "string", enum: ["text", "json", "mermaid"], default: "text" },
+        edge_types: { type: "string", description: "Comma-separated contains,call,inherits,implements values." },
+      },
+      required: ["from"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "outline",
+    description: "Return the complete indexed top-level outline of a source file before reading the whole file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", minLength: 1, description: "Absolute or workspace-relative file path." },
+        include_code: { type: "boolean", default: false },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "logs",
+    description: "Read the znt-core in-memory activity log snapshot or a cursor-based delta.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stream_id: { type: "string", minLength: 1 },
+        after_id: { type: "integer", minimum: 0 },
+      },
+      dependentRequired: { stream_id: ["after_id"], after_id: ["stream_id"] },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "status",
+    description: "Check whether znt-core already indexes the requested project or one of its ancestor directories, and return daemon, index, and scan status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_path: { type: "string", minLength: 1, description: "Optional absolute project directory or a path relative to ZNT_PROJECT_ROOT. Defaults to ZNT_PROJECT_ROOT or cwd." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "scan",
+    description: "Scan a project only after setup is valid. If setup_required is returned, call setup before retrying.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_path: { type: "string", minLength: 1, description: "Optional absolute project directory or a path relative to ZNT_PROJECT_ROOT. Defaults to ZNT_PROJECT_ROOT or cwd." },
+        language: { type: "string", minLength: 1, default: "auto", description: "Parser name from info.languages, or auto." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "stats",
+    description: "Return session and persisted usage estimates for this Znt MCP server.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+]);
+
+export const TOOL_NAMES = new Set(TOOL_DEFINITIONS.map((tool) => tool.name));