@threenative/core 0.3.2 → 0.3.4

package/mcp/blender-server.mjs

@@ -379,6 +379,21 @@ var RECIPES = Object.freeze([
       }
     ]),
     script: "retarget.py"
+  }),
+  Object.freeze({
+    description: "Export a Blender-authored world as a ThreeNative world package v1: world.json, a raw uint16 heightmap, one GLB plus a decimated LOD1 per referenced scatter asset, per-cell chunk GLBs and placements.bin. Reads render-density instances, so viewport share tricks never leak in.",
+    name: "export_world",
+    parameters: Object.freeze([
+      { description: "Path to the .blend world to read.", name: "source", required: true },
+      { description: "Directory to write the package into.", name: "out", required: true },
+      { description: "Cell edge length in metres.", name: "cell", required: true },
+      {
+        description: "Heightmap sample spacing in metres. Default 2.",
+        name: "spacing",
+        required: false
+      }
+    ]),
+    script: "export_world.py"
   })
 ]);
 function recipeNames() {
@@ -424,7 +439,7 @@ async function runRecipe(name, request, options = {}) {
 
 // src/index.ts
 var SERVER_NAME = "threenative-blender-mcp";
-var SERVER_VERSION = "0.1.2";
+var SERVER_VERSION = "0.1.4";
 var AUTHORING_INSTRUCTIONS = "Call blender_status before anything else: it answers whether this machine can convert models at all, and when it cannot it names the install command rather than failing. Blender is never installed for the user \u2014 ask first, then let them run the command. An .fbx, .blend, .obj or .dae placed in a game's assets directory is converted by the build itself; these tools are for inspecting a source before committing it and for operations the build does not perform. For anything no named tool covers, read a shipped recipe with blender_recipes and adapt it, then run it with blender_run_python.";
 var TOOL_DEFINITIONS = [
   {
@@ -476,6 +491,25 @@ var TOOL_DEFINITIONS = [
       type: "object"
     }
   },
+  {
+    annotations: { destructiveHint: true, openWorldHint: false, readOnlyHint: false },
+    name: "blender_export_world",
+    description: "Export a Blender-authored world as a ThreeNative world package v1: world.json, a raw uint16 heightmap, one GLB plus a decimated LOD1 per referenced scatter asset, per-cell chunk GLBs and placements.bin. Reads render-density instances so viewport share tricks never leak in; marks the terrain with tn_world_terrain, scatter sources with tn_asset_id and chunk collections with tn_world_chunk.",
+    inputSchema: {
+      additionalProperties: false,
+      properties: {
+        cell: { description: "Cell edge length in metres.", type: "number" },
+        out: { description: "Directory to write the package into.", type: "string" },
+        source: { description: "Path to the .blend world to read.", type: "string" },
+        spacing: {
+          description: "Heightmap sample spacing in metres. Default 2.",
+          type: "number"
+        }
+      },
+      required: ["source", "out", "cell"],
+      type: "object"
+    }
+  },
   {
     annotations: { destructiveHint: true, openWorldHint: false, readOnlyHint: false },
     name: "blender_run_python",
@@ -570,6 +604,26 @@ async function handleToolCall(params) {
     return toolText(await convertModel(source, out));
   }
   if (name === "blender_recipes") return toolText(await handleRecipes(argumentsValue));
+  if (name === "blender_export_world") {
+    const source = requiredString(argumentsValue, "source", "blender_export_world");
+    const out = requiredString(argumentsValue, "out", "blender_export_world");
+    const cell = argumentsValue.cell;
+    if (typeof cell !== "number" || !Number.isFinite(cell) || cell <= 0) {
+      throw new Error("blender_export_world 'cell' must be a number greater than zero.");
+    }
+    const spacing = argumentsValue.spacing;
+    if (spacing !== void 0 && (typeof spacing !== "number" || !Number.isFinite(spacing) || spacing <= 0)) {
+      throw new Error("blender_export_world 'spacing' must be a number greater than zero.");
+    }
+    return toolText(
+      await runRecipe("export_world", {
+        cell,
+        out,
+        source,
+        ...spacing === void 0 ? {} : { spacing }
+      })
+    );
+  }
   if (name === "blender_run_python") {
     const script = requiredString(argumentsValue, "script", "blender_run_python");
     const request = isRecord(argumentsValue.arguments) ? argumentsValue.arguments : {};

package/mcp/engine-server.mjs

@@ -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/mcp/servers.mjs

@@ -38,10 +38,10 @@ export const MCP_SERVERS = Object.freeze({
  * separately. The pinned engine version remains an emergency fallback for a legacy development
  * checkout whose bundle has not been built. */
 export const MCP_PACKAGES = Object.freeze({
-  assets: Object.freeze({ name: "threenative-asset-mcp", version: "0.8.0" }),
+  assets: Object.freeze({ name: "threenative-asset-mcp", version: "0.9.5" }),
   sculpt: Object.freeze({ name: "threenative-sculpt-mcp", version: "0.1.1" }),
-  engine: Object.freeze({ name: "threenative-engine-mcp", version: "0.2.2" }),
-  blender: Object.freeze({ name: "threenative-blender-mcp", version: "0.1.2" }),
+  engine: Object.freeze({ name: "threenative-engine-mcp", version: "0.2.4" }),
+  blender: Object.freeze({ name: "threenative-blender-mcp", version: "0.1.4" }),
 });
 
 /** How one host spells a stdio MCP server. Hosts agree on what to run and disagree on where to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threenative/core",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "license": "MIT AND GPL-2.0-or-later",
   "description": "The small vanilla Three.js game runtime foundation.",
   "keywords": [
@@ -76,7 +76,7 @@
   "dependencies": {
     "three": "0.185.1",
     "three-mesh-bvh": "0.9.14",
-    "threenative-asset-mcp": "0.8.0",
+    "threenative-asset-mcp": "0.9.5",
     "threenative-sculpt-mcp": "0.1.1",
     "zustand": "5.0.14"
   },
@@ -89,12 +89,12 @@
     "react-reconciler": "0.33.0",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
-    "threenative-blender-mcp": "0.1.2",
-    "@threenative/playtest": "0.3.2",
-    "threenative-engine-mcp": "0.2.2"
+    "@threenative/playtest": "0.3.4",
+    "threenative-engine-mcp": "0.2.4",
+    "threenative-blender-mcp": "0.1.4"
   },
   "peerDependencies": {
-    "@threenative/playtest": ">=0.3.2 <0.4.0",
+    "@threenative/playtest": ">=0.3.4 <0.4.0",
     "react": ">=19.2.0 <20",
     "react-reconciler": ">=0.33.0 <0.34"
   },