@znt/mcp 1.1.1 → 2.0.1

package/src/znt-tools.js

@@ -0,0 +1,555 @@
+import {
+  ZntClient,
+  ZntCoreNotInstalledError,
+  ZntRpcError,
+  ZntTransportError,
+  credentialReference,
+  getSetupStatus,
+  mergeConfig,
+  resolveManagedConfigPath,
+  setupManagedConfig,
+} from "@znt/sdk-nodejs";
+import { access, chmod, copyFile, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { parse, stringify } from "yaml";
+
+import { CredentialSetupServer } from "./credential-setup.js";
+import { UsageMetrics } from "./metrics.js";
+import { TOOL_NAMES } from "./tool-definitions.js";
+
+const ZNT_CORE_VERSION = "1.2";
+
+export class ZntTools {
+  constructor(options = {}) {
+    const explicitConfig = options.configPath ?? process.env.ZNT_CONFIG;
+    this.customCoreBinary = options.coreBinaryPath ?? process.env.ZNT_CORE_BINARY;
+    this.configPath = resolve(explicitConfig ?? resolveManagedConfigPath(options.coreBinaryPath));
+    this.managedConfig = options.managedConfig ?? (explicitConfig === undefined);
+    this.client = options.client ?? new ZntClient({
+      configPath: this.configPath,
+      ...(options.coreBinaryPath ? { coreBinaryPath: options.coreBinaryPath } : {}),
+    });
+    if (typeof this.client.setupManagedConfig !== "function") {
+      this.client.setupManagedConfig = (opts) => setupManagedConfig(opts, {
+        configPath: this.configPath,
+        coreBinaryPath: this.customCoreBinary,
+        client: this.client,
+      });
+    }
+    if (typeof this.client.getSetupStatus !== "function") {
+      this.client.getSetupStatus = (opts) => getSetupStatus(opts, {
+        configPath: this.configPath,
+        coreBinaryPath: this.customCoreBinary,
+        client: this.client,
+      });
+    }
+    this.metrics = options.metrics ?? new UsageMetrics();
+    this.requestTimeoutMs = options.requestTimeoutMs ?? envPositiveInteger("ZNT_MCP_REQUEST_TIMEOUT_MS", 30_000);
+    this.projectRoot = resolve(options.projectRoot ?? process.env.ZNT_PROJECT_ROOT ?? process.cwd());
+    this.coreVersion = options.coreVersion ?? ZNT_CORE_VERSION;
+    this.coreReady = false;
+    this.startPromise = undefined;
+    this.scanPromise = undefined;
+    this.setupGate = options.setupGate ?? (options.client === undefined);
+    this.setupReady = options.setupReady ?? false;
+    this.credentialSetup = options.credentialSetup ?? new CredentialSetupServer();
+  }
+
+  async initialize() {
+    return this.setupStatus(false);
+  }
+
+  disconnect() {
+    this.client.disconnect();
+    void this.credentialSetup.close();
+    this.coreReady = false;
+  }
+
+  async call(toolName, args = {}, options = {}) {
+    if (!TOOL_NAMES.has(toolName)) return errorResult(`Unknown tool: ${toolName}`);
+    const startedAt = performance.now();
+    try {
+      if (toolName === "setup") {
+        const data = await this.setup(args, options.signal);
+        await this.metrics.record(toolName, {}, data, Math.round(performance.now() - startedAt));
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      }
+      if (toolName === "setup_status") {
+        const data = await this.setupStatus(args.check_provider === true, options.signal);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      }
+      if (toolName === "stats") {
+        const data = await this.metrics.snapshot();
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      }
+      if (this.setupGate && !this.setupReady) {
+        const setup = await this.setupStatus(true, options.signal);
+        if (setup.status !== "ready") {
+          return {
+            content: [{
+              type: "text", text: JSON.stringify({
+                ...setup,
+                setup_status: setup.status,
+                status: "setup_required",
+                next_tool: "setup",
+              }, null, 2)
+            }]
+          };
+        }
+        this.setupReady = true;
+      }
+      await this.ensureCore();
+      const data = await this.execute(toolName, args, options.signal);
+      const text = formatToolOutput(toolName, data, args);
+      await this.metrics.record(toolName, args, data, Math.round(performance.now() - startedAt));
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      if (error instanceof ZntTransportError) this.coreReady = false;
+      return errorResult(formatError(toolName, error));
+    }
+  }
+
+  async ensureCore() {
+    if (this.coreReady) return;
+    if (!this.startPromise) {
+      this.startPromise = this.startCoreWithInstall().then(async () => {
+        this.coreReady = true;
+        try {
+          const status = await this.client.status({ timeoutMs: 2_000 });
+          this.metrics.setProjectRoot(status.project_root);
+        } catch {
+          // Project metrics become persistent once a project root is available;
+          // failure to read status does not invalidate a working daemon.
+        }
+      }).finally(() => {
+        this.startPromise = undefined;
+      });
+    }
+    await this.startPromise;
+  }
+
+  async startCoreWithInstall() {
+    try {
+      await this.client.startCore();
+    } catch (error) {
+      if (!(error instanceof ZntCoreNotInstalledError)) throw error;
+      await this.client.downloadCore({ version: this.coreVersion });
+      await this.client.startCore();
+    }
+  }
+
+  async ensureCoreBinary() {
+    const expectedVersion = this.customCoreBinary ? undefined : this.coreVersion;
+    if (await this.client.isCoreInstalled(expectedVersion)) return;
+    await this.client.downloadCore({ version: this.coreVersion });
+  }
+
+  async setupStatus(checkProvider = false, signal) {
+    const status = await this.client.getSetupStatus({ configPath: this.configPath, checkProvider, signal });
+    return {
+      ...status,
+      config_managed_by_mcp: this.managedConfig,
+    };
+  }
+
+  async setup(args = {}, signal) {
+    await this.ensureCoreBinary();
+    if (!this.managedConfig) {
+      const status = await this.setupStatus(args.check_provider !== false, signal);
+      return {
+        ...status,
+        externally_managed: true,
+        message: status.status === "ready"
+          ? "The configuration selected by ZNT_CONFIG is valid and was not modified."
+          : "The configuration selected by ZNT_CONFIG must be updated by its owner; MCP will not overwrite it.",
+      };
+    }
+
+    // Interactive wizard mode: invoked with no configuration arguments or explicitly requesting interactive UI
+    const hasExplicitSettings = [
+      "mode",
+      "provider_url",
+      "model",
+      "embed_model",
+      "semantic_mode",
+      "description_language",
+      "exclude",
+      "languages",
+      "api_key",
+      "clear_api_key",
+    ].some((key) => args[key] !== undefined);
+
+    if (!hasExplicitSettings || args.interactive === true) {
+      return this.openSetupWizard(args, signal);
+    }
+
+    return this.applySetupConfig(args, signal);
+  }
+
+  async openSetupWizard(args = {}, signal) {
+    let existing = {};
+    try {
+      existing = parse(await readFile(this.configPath, "utf8")) ?? {};
+    } catch {
+      // Configuration does not exist yet
+    }
+
+    const defaults = parse(await this.client.getDefaultConfig());
+    const merged = mergeConfig(defaults, existing);
+
+    let currentStatus = {};
+    try {
+      currentStatus = await this.client.getSetupStatus({ configPath: this.configPath, checkProvider: false });
+    } catch {
+      // Ignore if status query fails during initial setup
+    }
+
+    const initialData = {
+      mode: existing?.llm?.provider === "ollama" ? "ollama" : (existing?.llm?.provider === "" ? "bm25" : (existing?.llm?.provider || "openapi")),
+      provider_url: existing?.llm?.url || (existing?.llm?.provider === "ollama" ? "http://localhost:11434" : "https://openrouter.ai/api/v1"),
+      model: existing?.llm?.model || "",
+      embed_model: existing?.llm?.embed_model || "bge-m3",
+      semantic_mode: existing?.semantic?.mode || "fast",
+      description_language: existing?.semantic?.description_language || merged?.semantic?.description_language || "ru",
+      exclude: existing?.exclude || merged?.exclude || [],
+      languages: existing?.languages || merged?.languages || {},
+      has_credential: Boolean(currentStatus?.has_credential),
+      credential_source: currentStatus?.credential_source,
+      token_ref: currentStatus?.token_ref,
+      token_env: currentStatus?.token_env,
+    };
+
+    const setupUrl = await this.credentialSetup.open({
+      provider: initialData.provider_url,
+      initialData,
+      onSetup: async (payload) => {
+        await this.applySetupConfig({
+          mode: payload.mode,
+          provider_url: payload.provider_url,
+          model: payload.model,
+          embed_model: payload.embed_model,
+          semantic_mode: payload.semantic_mode,
+          description_language: payload.description_language,
+          exclude: payload.exclude,
+          languages: payload.languages,
+          ...(payload.api_key ? { api_key: payload.api_key } : {}),
+          ...(payload.clear_api_key ? { clear_api_key: true } : {}),
+        }, signal);
+      },
+    });
+
+    const statusForResponse = currentStatus?.status ? currentStatus : await this.setupStatus(false, signal);
+    return {
+      status: "wizard_opened",
+      config_path: this.configPath,
+      setup_url: setupUrl,
+      instruction: "Opened setup wizard in browser. Configure provider, models, and project settings in the wizard.",
+      recommendations: statusForResponse.recommendations,
+    };
+  }
+
+  async applySetupConfig(args = {}, signal) {
+    await this.stopCoreForConfigChange();
+    this.setupReady = false;
+
+    let previousStatus;
+    try {
+      previousStatus = await this.client.getSetupStatus({ configPath: this.configPath, checkProvider: false });
+    } catch {
+      // Ignore
+    }
+
+    const hasExistingCredential = Boolean(
+      previousStatus?.has_credential &&
+      previousStatus?.status === "ready" &&
+      (!args.provider_url || args.provider_url === previousStatus?.provider_url) &&
+      !args.clear_api_key
+    );
+
+    const mode = args.mode ?? previousStatus?.mode ?? "openapi";
+    const isInteractiveOpenapi = mode === "openapi" && !args.api_key && args.credential_source !== "env" && !hasExistingCredential;
+
+    const status = await this.client.setupManagedConfig({
+      ...args,
+      config_path: this.configPath,
+      check_provider: isInteractiveOpenapi ? false : (args.check_provider !== false),
+    });
+
+    if (isInteractiveOpenapi || status.status === "credential_required") {
+      const providerUrl = args.provider_url ?? status.provider_url ?? "https://api.openai.com/v1";
+      const reference = credentialReference(providerUrl);
+      const setupUrl = await this.credentialSetup.open({
+        provider: providerUrl,
+        onCredential: async (credential) => {
+          if (typeof this.client.storeSecret === "function") {
+            await this.client.storeSecret(reference, credential);
+          }
+          if (typeof this.client.validateConfig === "function") {
+            await this.client.validateConfig(this.configPath, { checkProvider: true });
+          }
+          this.setupReady = true;
+        },
+      });
+      return {
+        status: "credential_required",
+        config_path: this.configPath,
+        credential_source: "keyring",
+        setup_url: setupUrl,
+        next: "Open setup_url, save the API key, then call setup_status with check_provider=true.",
+      };
+    }
+
+    this.setupReady = status.status === "ready";
+    return {
+      ...status,
+      config_managed_by_mcp: this.managedConfig,
+      scan_required: this.setupReady,
+    };
+  }
+
+
+  async stopCoreForConfigChange() {
+    if (typeof this.client.stopCore !== "function") return;
+    try {
+      await this.client.stopCore({ timeoutMs: 2_000 });
+    } catch (error) {
+      if (!(error instanceof ZntTransportError)) throw error;
+    } finally {
+      this.coreReady = false;
+    }
+  }
+
+  async execute(toolName, args, signal) {
+    const requestOptions = { timeoutMs: this.requestTimeoutMs, signal };
+    switch (toolName) {
+      case "search":
+        return this.client.semanticSearch(normalizeSearchArgs(args), requestOptions);
+      case "similar":
+        return this.client.findSimilar(normalizeSimilarArgs(args), requestOptions);
+      case "graph":
+        return this.client.getSubgraph(copyDefined(args, ["from", "to", "depth", "format", "edge_types"]), requestOptions);
+      case "outline":
+        return this.client.fileOutline({ file_path: args.path, include_code: args.include_code }, requestOptions);
+      case "logs":
+        return this.client.logs(copyDefined(args, ["stream_id", "after_id"]), requestOptions);
+      case "status":
+        return this.projectStatus(args, requestOptions);
+      case "scan":
+        return this.scanProject(args, requestOptions);
+      case "stats": {
+        try {
+          const status = await this.client.status({ timeoutMs: 2_000, signal });
+          this.metrics.setProjectRoot(status.project_root);
+        } catch {
+          // Session metrics remain available even without a workspace root.
+        }
+        return this.metrics.snapshot();
+      }
+      default:
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  }
+
+  async projectStatus(args, requestOptions) {
+    const targetProject = await this.resolveProjectPath(args.project_path);
+    const [status, scan] = await Promise.all([
+      this.client.status(requestOptions),
+      this.client.scanStatus(requestOptions),
+    ]);
+    const daemonProject = status.project_root || null;
+    const comparableDaemonProject = await canonicalizeExistingPath(daemonProject);
+    const isExactProject = samePath(targetProject, comparableDaemonProject);
+    const isCurrentProject = pathContains(comparableDaemonProject, targetProject);
+    return {
+      current_project: targetProject,
+      daemon_project: daemonProject,
+      is_current_project: isCurrentProject,
+      is_exact_project: isExactProject,
+      coverage: isExactProject ? "exact" : isCurrentProject ? "ancestor" : "none",
+      daemon_status: status.status,
+      has_index: isCurrentProject && Number(status.files || 0) > 0,
+      stats: {
+        files: Number(status.files || 0),
+        declarations: Number(status.declarations || 0),
+        functions: Number(status.functions || 0),
+        members: Number(status.members || 0),
+        dependencies: Number(status.dependencies || 0),
+        edges: Number(status.edges || 0),
+      },
+      scan,
+    };
+  }
+
+  async scanProject(args, requestOptions) {
+    if (this.scanPromise) {
+      return {
+        started: false,
+        reason: "scan_request_in_progress",
+        current_project: await this.resolveProjectPath(args.project_path),
+      };
+    }
+
+    this.scanPromise = this.performScanProject(args, requestOptions);
+    try {
+      return await this.scanPromise;
+    } finally {
+      this.scanPromise = undefined;
+    }
+  }
+
+  async performScanProject(args, requestOptions) {
+    const targetProject = await this.resolveProjectPath(args.project_path);
+    const [before, progress] = await Promise.all([
+      this.client.status(requestOptions),
+      this.client.scanStatus(requestOptions),
+    ]);
+    const daemonProject = before.project_root || null;
+    const comparableDaemonProject = await canonicalizeExistingPath(daemonProject);
+    if (pathContains(comparableDaemonProject, targetProject)) {
+      const exact = samePath(targetProject, comparableDaemonProject);
+      return {
+        started: false,
+        reason: exact ? "already_current_project" : "already_covered",
+        current_project: targetProject,
+        daemon_project: daemonProject,
+        daemon_status: before.status,
+        coverage: exact ? "exact" : "ancestor",
+      };
+    }
+
+    if (progress.status === "scanning") {
+      return {
+        started: false,
+        reason: "scan_in_progress",
+        current_project: targetProject,
+        daemon_project: daemonProject,
+        daemon_status: before.status,
+        scan: progress,
+      };
+    }
+
+    const scan = await this.client.scan({
+      file_path: targetProject,
+      language: args.language ?? "auto",
+      restart: false,
+    }, requestOptions);
+    this.metrics.setProjectRoot(targetProject);
+    return {
+      started: true,
+      previous_project: daemonProject,
+      current_project: targetProject,
+      scan,
+      next: "Call status until scan.status is completed or error.",
+    };
+  }
+
+  async resolveProjectPath(projectPath) {
+    if (projectPath === undefined) return this.projectRoot;
+    const candidate = resolve(this.projectRoot, projectPath);
+    let details;
+    try {
+      details = await stat(candidate);
+    } catch (error) {
+      throw new Error(`Project path is not accessible: ${candidate} (${error.message})`);
+    }
+    if (!details.isDirectory()) throw new Error(`Project path is not a directory: ${candidate}`);
+    return realpath(candidate);
+  }
+}
+
+function normalizeSearchArgs(args) {
+  return copyDefined({
+    ...args,
+    type: args.type_boost,
+    role: args.role_boost,
+    file_path: args.file_pattern,
+  }, ["query", "mode", "limit", "callers_level", "callees_level", "compact", "include_code", "max_code_lines", "type", "role", "file_path"]);
+}
+
+function normalizeSimilarArgs(args) {
+  return copyDefined({
+    ...args,
+    type: args.type_boost,
+    role: args.role_boost,
+    file_path: args.file_pattern,
+  }, ["target", "query", "limit", "include_code", "max_code_lines", "type", "role", "file_path", "edge_types"]);
+}
+
+function copyDefined(source, keys) {
+  return Object.fromEntries(keys.filter((key) => source[key] !== undefined).map((key) => [key, source[key]]));
+}
+
+function formatToolOutput(toolName, data, args) {
+  if (toolName === "search") return formatSearchResults(data, args.compact);
+  if (toolName === "outline") return data.formatted_text || JSON.stringify(data, null, 2);
+  if (toolName === "graph" && data.format === "text") return data.text || "No graph edges found.";
+  if (toolName === "graph" && data.format === "mermaid") return data.mermaid || "No graph edges found.";
+  return JSON.stringify(data, null, 2);
+}
+
+function formatSearchResults(results, compact) {
+  if (!Array.isArray(results) || !results.length) return "No matching components found.";
+  return results.map((result) => {
+    const lines = [
+      `[Score: ${Number(result.score || 0).toFixed(2)}] ${result.name} (${result.type})`,
+      result.role ? `Role: ${result.role}` : "",
+      `File: ${result.file} L:${result.start_line}-${result.end_line}`,
+      compact && result.summary ? `Summary: ${result.summary}` : "",
+      !compact && result.description ? `Description: ${result.description}` : "",
+      !compact ? formatRelations("Callers", result.callers) : "",
+      !compact ? formatRelations("Callees", result.callees) : "",
+      result.code ? `Code:\n${result.code}` : "",
+    ].filter(Boolean);
+    return `${lines.join("\n")}\n---`;
+  }).join("\n");
+}
+
+function formatRelations(label, relations) {
+  if (!Array.isArray(relations) || !relations.length) return "";
+  return `${label}: ${relations.map((item) => item.name).join(", ")}`;
+}
+
+function formatError(toolName, error) {
+  if (error instanceof ZntRpcError) {
+    const data = error.data === undefined ? "" : `\n${JSON.stringify(error.data, null, 2)}`;
+    return `Error executing ${toolName}: znt-core RPC ${error.code}: ${error.message}${data}`;
+  }
+  return `Error executing ${toolName}: ${error?.message ?? String(error)}`;
+}
+
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+function envPositiveInteger(name, fallback) {
+  const value = Number(process.env[name]);
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+function samePath(left, right) {
+  if (!left || !right) return false;
+  const normalize = (value) => {
+    const normalized = resolve(value);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+  };
+  return normalize(left) === normalize(right);
+}
+
+function pathContains(parent, candidate) {
+  if (!parent || !candidate) return false;
+  const normalize = (value) => {
+    const normalized = resolve(value);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+  };
+  const pathFromParent = relative(normalize(parent), normalize(candidate));
+  return pathFromParent === "" || (!pathFromParent.startsWith("..") && !isAbsolute(pathFromParent));
+}
+
+async function canonicalizeExistingPath(value) {
+  if (!value) return null;
+  try {
+    return await realpath(resolve(value));
+  } catch {
+    return resolve(value);
+  }
+}