threenative-engine-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Paulo Furtado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# threenative-engine-mcp
+
+An offline MCP server that lets a ThreeNative authoring agent search the committed engine
+capability manifest by situation and inspect one capability in detail.
+
+The server exposes exactly two read-only tools: `engine_search_capabilities` and
+`engine_capability_detail`.
+
+First infer the concrete mechanics implied by the request. Call `engine_search_capabilities` once
+with that mechanically explicit request and `scope: "request"`, then once per mechanic with
+`scope: "mechanic"`. Complete requests return up to 15 deduplicated capabilities; focused
+situations return up to five. A genre label alone returns no guessed recipe. Every result includes
+`matchedSituation`, so an authoring agent can verify why it was selected instead of treating a
+lexical coincidence as engine guidance.

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+interface ICapabilityEntry {
+    readonly symbol: string;
+    readonly package: string;
+    readonly importPath: string;
+    readonly kind: string;
+    readonly signature: string;
+    readonly summary: string;
+    readonly situations: readonly string[];
+    readonly example: string;
+    readonly constraints: readonly string[];
+    readonly overrides?: readonly string[];
+}
+interface ICapabilityManifest {
+    readonly version: number;
+    readonly entries: readonly ICapabilityEntry[];
+}
+interface ICapabilitySearchResult {
+    readonly symbol: string;
+    readonly importPath: string;
+    readonly summary: string;
+    readonly example: string;
+    readonly constraints: readonly string[];
+    readonly matchedSituation: string;
+}
+interface ICapabilityDetail extends ICapabilityEntry {
+}
+interface IEngineTool {
+    readonly name: string;
+    readonly description: string;
+    readonly annotations: {
+        readonly destructiveHint: false;
+        readonly openWorldHint: false;
+        readonly readOnlyHint: true;
+    };
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: Record<string, {
+            readonly description?: string;
+            readonly enum?: readonly string[];
+            readonly type: "string";
+        }>;
+        readonly required: readonly string[];
+        readonly additionalProperties: false;
+    };
+}
+declare const ENGINE_MCP_TOOL_NAMES: readonly ["engine_search_capabilities", "engine_capability_detail"];
+declare function defaultManifestPath(cwd?: string): string;
+declare function loadCapabilityManifest(file?: string): ICapabilityManifest;
+declare function searchCapabilities(situation: string, manifestFile?: string, scope?: "mechanic" | "request"): readonly ICapabilitySearchResult[];
+declare function capabilityDetail(symbol: string, manifestFile?: string): ICapabilityDetail;
+declare function toolDefinitions(): readonly IEngineTool[];
+/**
+ * Handles one raw stdin line and returns the JSON-RPC response to write, or `undefined` when the
+ * line must be consumed silently. Extracted so the stdio contract is testable without a live
+ * `process.stdin`: this framing is the whole surface an authoring agent's MCP client speaks.
+ */
+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 ICapabilitySearchResult, type IEngineTool, capabilityDetail, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };

package/dist/index.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+import { realpathSync, readFileSync } from 'fs';
+import path from 'path';
+import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
+
+var ENGINE_MCP_TOOL_NAMES = [
+  "engine_search_capabilities",
+  "engine_capability_detail"
+];
+var DEFAULT_MANIFEST_FILE = "capabilities.json";
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "add",
+  "an",
+  "and",
+  "around",
+  "build",
+  "by",
+  "create",
+  "for",
+  "from",
+  "game",
+  "in",
+  "into",
+  "it",
+  "make",
+  "of",
+  "on",
+  "that",
+  "the",
+  "to",
+  "use",
+  "with"
+]);
+var MAX_COMPLETE_REQUEST_RESULTS = 15;
+var MAX_SITUATION_RESULTS = 5;
+var AUTHORING_INSTRUCTIONS = `Before authoring, infer concrete gameplay mechanics. Preserve the request's distinctive fantasy: choose the smallest loop that uses its characteristic setting, traversal medium, or simulation instead of a generic character game with themed props, and search those implied mechanics even when the user did not name engine terms. Search the mechanically explicit complete request with scope "request", then each mechanic with scope "mechanic". A genre label alone is not a capability query: clarify or decompose it; do not assume a preset. Inspect capability detail and obey constraints before implementing. Capability detail is authoritative on platform support: never invent a platform limitation it does not state.`;
+function defaultManifestPath(cwd = process.cwd()) {
+  return path.resolve(cwd, process.env.THREENATIVE_CAPABILITIES_MANIFEST ?? DEFAULT_MANIFEST_FILE);
+}
+function manifestError(file, reason) {
+  return new Error(`TN_ENGINE_CAPABILITIES_MANIFEST: ${file}: ${reason}`);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateManifest(value, file) {
+  if (!isRecord(value) || typeof value.version !== "number" || !Array.isArray(value.entries)) {
+    throw manifestError(file, "root must contain a numeric version and entries array");
+  }
+  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.constraints) || !raw.situations.every((situation) => typeof situation === "string") || !raw.constraints.every((constraint) => typeof constraint === "string")) {
+      throw manifestError(file, `entry ${index} is malformed`);
+    }
+  }
+  return value;
+}
+function loadCapabilityManifest(file = defaultManifestPath()) {
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch (error) {
+    throw manifestError(file, `cannot read committed manifest: ${String(error)}`);
+  }
+  try {
+    return validateManifest(JSON.parse(raw), file);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("TN_ENGINE_CAPABILITIES_MANIFEST:"))
+      throw error;
+    throw manifestError(file, `cannot parse JSON: ${String(error)}`);
+  }
+}
+function tokens(value) {
+  return value.toLocaleLowerCase().split(/[^a-z0-9]+/u).filter((token) => token.length > 1 && !STOP_WORDS.has(token)).map((token) => {
+    if (token.length > 4 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
+    if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss"))
+      return token.slice(0, -1);
+    return token;
+  });
+}
+function situationScore(query, situations) {
+  if (query.length === 0) return { matchedSituation: "", score: 0 };
+  const queryText = query.join(" ");
+  let best = 0;
+  let matchedSituation = "";
+  for (const situation of situations) {
+    const phrase = tokens(situation);
+    const overlap = new Set(phrase.filter((token) => query.includes(token))).size;
+    const score = overlap / Math.max(query.length, phrase.length);
+    const phraseBonus = phrase.join(" ").includes(queryText) || queryText.includes(phrase.join(" ")) ? 1 : 0;
+    if (overlap < (query.length >= 4 ? 2 : 1) && phraseBonus === 0) continue;
+    const candidate = score + phraseBonus;
+    if (candidate > best) {
+      best = candidate;
+      matchedSituation = situation;
+    }
+  }
+  return { matchedSituation, score: best };
+}
+function capabilitySearchKey(entry) {
+  return `${entry.importPath}
+${entry.signature}
+${entry.summary}
+${entry.situations.join("\n")}`;
+}
+function searchCapabilities(situation, manifestFile = defaultManifestPath(), scope = "mechanic") {
+  if (typeof situation !== "string" || situation.trim().length === 0)
+    throw new Error("engine_search_capabilities requires a non-empty situation string.");
+  const manifest = loadCapabilityManifest(manifestFile);
+  const query = tokens(situation);
+  const limit = scope === "request" ? MAX_COMPLETE_REQUEST_RESULTS : MAX_SITUATION_RESULTS;
+  return manifest.entries.map((entry) => ({ entry, ...situationScore(query, entry.situations) })).filter(({ score }) => score > 0).sort(
+    (left, right) => right.score - left.score || `${left.entry.importPath}:${left.entry.symbol}`.localeCompare(
+      `${right.entry.importPath}:${right.entry.symbol}`
+    )
+  ).filter(
+    (candidate, index, candidates) => candidates.findIndex(
+      (other) => capabilitySearchKey(other.entry) === capabilitySearchKey(candidate.entry)
+    ) === index
+  ).slice(0, limit).map(({ entry, matchedSituation }) => ({
+    constraints: entry.constraints,
+    example: entry.example,
+    importPath: entry.importPath,
+    matchedSituation,
+    summary: entry.summary,
+    symbol: entry.symbol
+  }));
+}
+function capabilityDetail(symbol, manifestFile = defaultManifestPath()) {
+  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;
+}
+var TOOL_DEFINITIONS = [
+  {
+    annotations: { destructiveHint: false, openWorldHint: false, readOnlyHint: true },
+    name: "engine_search_capabilities",
+    description: 'Search the installed engine by concrete gameplay mechanic. Decompose genres first. Use scope "request" for the mechanically explicit full request and "mechanic" for each focused search; matchedSituation explains every result.',
+    inputSchema: {
+      additionalProperties: false,
+      properties: {
+        scope: {
+          description: "Use request for the complete cross-system game request; use mechanic or omit it for one mechanic.",
+          enum: ["request", "mechanic"],
+          type: "string"
+        },
+        situation: { type: "string" }
+      },
+      required: ["situation"],
+      type: "object"
+    }
+  },
+  {
+    annotations: { destructiveHint: false, openWorldHint: false, readOnlyHint: true },
+    name: "engine_capability_detail",
+    description: "Inspect one engine capability's import, signature, example, constraints, and overrides.",
+    inputSchema: {
+      additionalProperties: false,
+      properties: { symbol: { type: "string" } },
+      required: ["symbol"],
+      type: "object"
+    }
+  }
+];
+function toolDefinitions() {
+  return TOOL_DEFINITIONS;
+}
+function jsonRpcError(id, code, message) {
+  return JSON.stringify({ id, jsonrpc: "2.0", error: { code, message } });
+}
+function jsonRpcResult(id, result) {
+  return JSON.stringify({ id, jsonrpc: "2.0", result });
+}
+function writeLine(value) {
+  process.stdout.write(`${value}
+`);
+}
+function toolText(value) {
+  return { content: [{ text: JSON.stringify(value, null, 2), type: "text" }] };
+}
+function handleToolCall(params, manifestFile) {
+  const name = params.name;
+  const argumentsValue = isRecord(params.arguments) ? params.arguments : {};
+  if (name === "engine_search_capabilities") {
+    if (typeof argumentsValue.situation !== "string")
+      throw new Error("engine_search_capabilities requires a string 'situation' argument.");
+    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));
+  }
+  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));
+  }
+  throw new Error(`Unknown engine MCP tool '${String(name)}'.`);
+}
+function handleLine(line, manifestFile) {
+  if (line.trim().length === 0) return void 0;
+  let request;
+  try {
+    request = JSON.parse(line);
+  } catch (error) {
+    return jsonRpcError(null, -32700, `Invalid JSON: ${String(error)}`);
+  }
+  if (!isRecord(request) || request.id === void 0 || typeof request.method !== "string")
+    return void 0;
+  try {
+    if (request.method === "initialize") {
+      return jsonRpcResult(request.id, {
+        capabilities: { tools: { listChanged: false } },
+        instructions: AUTHORING_INSTRUCTIONS,
+        protocolVersion: "2025-06-18",
+        serverInfo: { name: "threenative-engine-mcp", version: "0.2.0" }
+      });
+    }
+    if (request.method === "tools/list") {
+      return jsonRpcResult(request.id, { tools: TOOL_DEFINITIONS });
+    }
+    if (request.method === "tools/call") {
+      if (!isRecord(request.params)) throw new Error("tools/call requires an object params value.");
+      return jsonRpcResult(request.id, handleToolCall(request.params, 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));
+  }
+}
+function runServer(manifestFile = defaultManifestPath()) {
+  loadCapabilityManifest(manifestFile);
+  const input = createInterface({ input: process.stdin });
+  input.on("line", (line) => {
+    const response = handleLine(line, manifestFile);
+    if (response !== void 0) writeLine(response);
+  });
+}
+var entryPath = process.argv[1];
+if (entryPath !== void 0 && realpathSync(path.resolve(entryPath)) === realpathSync(fileURLToPath(import.meta.url))) {
+  try {
+    runServer();
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = 1;
+  }
+}
+
+export { ENGINE_MCP_TOOL_NAMES, capabilityDetail, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "threenative-engine-mcp",
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "Offline MCP capability discovery for ThreeNative authoring agents.",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "threenative-engine-mcp": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "publint": "0.3.22",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts && publint",
+    "typecheck": "tsc --noEmit",
+    "test": "publint --strict"
+  }
+}