threenative-engine-mcp 0.2.2 → 0.2.4

package/README.md

@@ -30,3 +30,16 @@ The first that exists wins, so the manifest can never drift from the engine the
 
 A project copy committed at scaffold time is therefore inert whenever the package is installed:
 the two never need re-syncing by hand.
+
+## The call log
+
+Every tool call appends one JSON line to `.threenative/engine-mcp.log` in the launch directory, so
+a finished session's searches can be read back:
+
+```json
+{"time":"2026-09-14T20:20:00.000Z","results":["MultiMesh3D"],"scope":"mechanic","situation":"spawn many identical props","tool":"engine_search_capabilities","verdict":"matched"}
+```
+
+A rejected call is logged with its `error`, which is where an agent asked for something the engine
+could not answer. `THREENATIVE_ENGINE_MCP_LOG` names another file, or `off` to disable the log. A
+log that cannot be written reports once on stderr and never fails a tool call.

package/dist/index.d.ts

@@ -11,6 +11,8 @@ interface ICapabilityEntry {
     readonly constraints: readonly string[];
     readonly overrides?: readonly string[];
     readonly requires?: readonly string[];
+    /** Absent unless something on this entry is deprecated; each string names what, and what to use. */
+    readonly deprecated?: readonly string[];
 }
 interface INotOwnedCapability {
     readonly id: string;
@@ -65,7 +67,14 @@ declare function defaultManifestPath(cwd?: string): string;
 declare function loadCapabilityManifest(file?: string): ICapabilityManifest;
 declare function capabilitySituationTokens(value: string): string[];
 declare function searchCapabilities(situation: string, manifestFile?: string, scope?: "mechanic" | "request"): ICapabilitySearchResponse;
-declare function capabilityDetail(symbol: string, manifestFile?: string): ICapabilityDetail;
+/**
+ * Every manifest entry named `symbol` (optionally in one `importPath`); throws when there is none.
+ * Two packages can export one name (`createThreeObject` from raw-unreal and ueformat), so a lookup
+ * by name alone must return both — answering with the first hides the second from detail.
+ */
+declare function capabilityDetails(symbol: string, manifestFile?: string, importPath?: string): readonly ICapabilityDetail[];
+/** One capability's detail; code callers must name `importPath` when the symbol is shared. */
+declare function capabilityDetail(symbol: string, manifestFile?: string, importPath?: string): ICapabilityDetail;
 declare function toolDefinitions(): readonly IEngineTool[];
 /**
  * Handles one raw stdin line and returns the JSON-RPC response to write, or `undefined` when the
@@ -75,4 +84,4 @@ declare function toolDefinitions(): readonly IEngineTool[];
 declare function handleLine(line: string, manifestFile: string): string | undefined;
 declare function runServer(manifestFile?: string): void;
 
-export { ENGINE_MCP_TOOL_NAMES, type ICapabilityDetail, type ICapabilityEntry, type ICapabilityManifest, type ICapabilitySearchResponse, type ICapabilitySearchResult, type IEngineTool, type INotOwnedCapability, RELEVANCE_FLOOR, capabilityDetail, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };
+export { ENGINE_MCP_TOOL_NAMES, type ICapabilityDetail, type ICapabilityEntry, type ICapabilityManifest, type ICapabilitySearchResponse, type ICapabilitySearchResult, type IEngineTool, type INotOwnedCapability, RELEVANCE_FLOOR, capabilityDetail, capabilityDetails, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync, readFileSync, existsSync } from 'fs';
+import { realpathSync, readFileSync, existsSync, mkdirSync, appendFileSync } from 'fs';
 import path from 'path';
 import { createInterface } from 'readline';
 import { fileURLToPath } from 'url';
@@ -131,14 +131,13 @@ function defaultManifestPath(cwd = process.cwd()) {
   const override = process.env.THREENATIVE_CAPABILITIES_MANIFEST;
   if (override !== void 0 && override.trim().length > 0) return path.resolve(cwd, override);
   for (let directory = path.resolve(cwd); ; directory = path.dirname(directory)) {
-    const installed = path.join(
-      directory,
-      "node_modules",
-      "@threenative",
-      "core",
-      "capabilities.json"
-    );
-    if (existsSync(installed)) return installed;
+    const nodeModules = path.join(directory, "node_modules");
+    const installed = path.join(nodeModules, "@threenative", "core", "capabilities.json");
+    if (existsSync(installed)) {
+      const relative = path.relative(realpathSync(directory), realpathSync(nodeModules));
+      if (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+        return installed;
+    }
     const parent = path.dirname(directory);
     if (parent === directory) break;
   }
@@ -156,6 +155,9 @@ function manifestError(file, reason) {
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
 function validateManifest(value, file) {
   if (!isRecord(value) || value.version !== 2 || !Array.isArray(value.entries) || !Array.isArray(value.notOwned)) {
     throw manifestError(
@@ -164,7 +166,7 @@ function validateManifest(value, file) {
     );
   }
   for (const [index, raw] of value.entries.entries()) {
-    if (!isRecord(raw) || typeof raw.symbol !== "string" || typeof raw.package !== "string" || typeof raw.importPath !== "string" || typeof raw.kind !== "string" || typeof raw.signature !== "string" || typeof raw.summary !== "string" || typeof raw.example !== "string" || !Array.isArray(raw.situations) || !Array.isArray(raw.aliases) || !Array.isArray(raw.constraints) || raw.requires !== void 0 && !Array.isArray(raw.requires) || !raw.situations.every((situation) => typeof situation === "string") || !raw.aliases.every((alias) => typeof alias === "string") || !raw.constraints.every((constraint) => typeof constraint === "string") || Array.isArray(raw.requires) && !raw.requires.every((requirement) => typeof requirement === "string")) {
+    if (!isRecord(raw) || typeof raw.symbol !== "string" || typeof raw.package !== "string" || typeof raw.importPath !== "string" || typeof raw.kind !== "string" || typeof raw.signature !== "string" || typeof raw.summary !== "string" || typeof raw.example !== "string" || !Array.isArray(raw.situations) || !Array.isArray(raw.aliases) || !Array.isArray(raw.constraints) || raw.requires !== void 0 && !isStringArray(raw.requires) || raw.deprecated !== void 0 && !isStringArray(raw.deprecated) || !raw.situations.every((situation) => typeof situation === "string") || !raw.aliases.every((alias) => typeof alias === "string") || !raw.constraints.every((constraint) => typeof constraint === "string")) {
       throw manifestError(file, `entry ${index} is malformed`);
     }
   }
@@ -375,13 +377,25 @@ function searchCapabilities(situation, manifestFile = defaultManifestPath(), sco
     verdict: "none"
   };
 }
-function capabilityDetail(symbol, manifestFile = defaultManifestPath()) {
+function capabilityDetails(symbol, manifestFile = defaultManifestPath(), importPath) {
   if (typeof symbol !== "string" || symbol.trim().length === 0)
     throw new Error("engine_capability_detail requires a non-empty symbol string.");
-  const manifest = loadCapabilityManifest(manifestFile);
-  const entry = manifest.entries.find((candidate) => candidate.symbol === symbol);
-  if (entry === void 0) throw new Error(`Unknown engine capability '${symbol}'.`);
-  return entry;
+  const matches = loadCapabilityManifest(manifestFile).entries.filter(
+    (candidate) => candidate.symbol === symbol && (importPath === void 0 || candidate.importPath === importPath)
+  );
+  if (matches.length === 0)
+    throw new Error(
+      `Unknown engine capability '${symbol}'${importPath === void 0 ? "" : ` in '${importPath}'`}.`
+    );
+  return matches;
+}
+function capabilityDetail(symbol, manifestFile = defaultManifestPath(), importPath) {
+  const matches = capabilityDetails(symbol, manifestFile, importPath);
+  if (matches.length > 1)
+    throw new Error(
+      `Ambiguous engine capability '${symbol}': pass importPath, one of ${matches.map((match) => `'${match.importPath}'`).join(", ")}.`
+    );
+  return matches[0];
 }
 var TOOL_DEFINITIONS = [
   {
@@ -405,10 +419,16 @@ var TOOL_DEFINITIONS = [
   {
     annotations: { destructiveHint: false, openWorldHint: false, readOnlyHint: true },
     name: "engine_capability_detail",
-    description: "Inspect one engine capability's import, signature, example, constraints, and overrides.",
+    description: "Inspect one engine capability's import, signature, example, constraints, and overrides. When several packages export the symbol, every match is returned under `matches`.",
     inputSchema: {
       additionalProperties: false,
-      properties: { symbol: { type: "string" } },
+      properties: {
+        importPath: {
+          description: "The search result's importPath; required when two packages export the same symbol.",
+          type: "string"
+        },
+        symbol: { type: "string" }
+      },
       required: ["symbol"],
       type: "object"
     }
@@ -417,6 +437,22 @@ var TOOL_DEFINITIONS = [
 function toolDefinitions() {
   return TOOL_DEFINITIONS;
 }
+var DEFAULT_LOG_FILE = path.join(".threenative", "engine-mcp.log");
+var logBroken = false;
+function logToolCall(entry) {
+  if (logBroken) return;
+  const target = process.env.THREENATIVE_ENGINE_MCP_LOG ?? DEFAULT_LOG_FILE;
+  if (target === "off") return;
+  try {
+    mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
+    appendFileSync(target, `${JSON.stringify({ time: (/* @__PURE__ */ new Date()).toISOString(), ...entry })}
+`);
+  } catch (error) {
+    logBroken = true;
+    process.stderr.write(`engine-mcp log disabled (${target}): ${String(error)}
+`);
+  }
+}
 function jsonRpcError(id, code, message) {
   return JSON.stringify({ id, jsonrpc: "2.0", error: { code, message } });
 }
@@ -439,12 +475,36 @@ function handleToolCall(params, manifestFile) {
     const scope = argumentsValue.scope ?? "mechanic";
     if (scope !== "request" && scope !== "mechanic")
       throw new Error("engine_search_capabilities scope must be 'request' or 'mechanic'.");
-    return toolText(searchCapabilities(argumentsValue.situation, manifestFile, scope));
+    const response = searchCapabilities(argumentsValue.situation, manifestFile, scope);
+    logToolCall({
+      results: response.results.map((result) => result.symbol),
+      scope,
+      situation: argumentsValue.situation,
+      tool: name,
+      verdict: response.verdict
+    });
+    return toolText(response);
   }
   if (name === "engine_capability_detail") {
     if (typeof argumentsValue.symbol !== "string")
       throw new Error("engine_capability_detail requires a string 'symbol' argument.");
-    return toolText(capabilityDetail(argumentsValue.symbol, manifestFile));
+    if (argumentsValue.importPath !== void 0 && typeof argumentsValue.importPath !== "string")
+      throw new Error("engine_capability_detail 'importPath' must be a string when given.");
+    const matches = capabilityDetails(
+      argumentsValue.symbol,
+      manifestFile,
+      argumentsValue.importPath
+    );
+    const detail = matches.length === 1 ? matches[0] : {
+      guidance: `${matches.length} packages export '${argumentsValue.symbol}'. Import the match whose summary fits; pass importPath to get one.`,
+      matches
+    };
+    logToolCall({
+      importPath: argumentsValue.importPath,
+      symbol: argumentsValue.symbol,
+      tool: name
+    });
+    return toolText(detail);
   }
   throw new Error(`Unknown engine MCP tool '${String(name)}'.`);
 }
@@ -464,7 +524,7 @@ function handleLine(line, manifestFile) {
         capabilities: { tools: { listChanged: false } },
         instructions: AUTHORING_INSTRUCTIONS,
         protocolVersion: "2025-06-18",
-        serverInfo: { name: "threenative-engine-mcp", version: "0.2.2" }
+        serverInfo: { name: "threenative-engine-mcp", version: "0.2.4" }
       });
     }
     if (request.method === "tools/list") {
@@ -476,7 +536,9 @@ function handleLine(line, manifestFile) {
     }
     return jsonRpcError(request.id, -32601, `Method not found: ${request.method}`);
   } catch (error) {
-    return jsonRpcError(request.id, -32e3, error instanceof Error ? error.message : String(error));
+    const message = error instanceof Error ? error.message : String(error);
+    if (request.method === "tools/call") logToolCall({ error: message, request: request.params });
+    return jsonRpcError(request.id, -32e3, message);
   }
 }
 function runServer(manifestFile = defaultManifestPath()) {
@@ -498,4 +560,4 @@ if (entryPath !== void 0 && realpathSync(path.resolve(entryPath)) === realpathSy
   }
 }
 
-export { ENGINE_MCP_TOOL_NAMES, RELEVANCE_FLOOR, capabilityDetail, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };
+export { ENGINE_MCP_TOOL_NAMES, RELEVANCE_FLOOR, capabilityDetail, capabilityDetails, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threenative-engine-mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "license": "MIT",
   "description": "Offline MCP capability discovery for ThreeNative authoring agents.",
   "keywords": [