threenative-engine-mcp 0.2.0 → 0.2.2

package/README.md

@@ -12,3 +12,21 @@ with that mechanically explicit request and `scope: "request"`, then once per me
 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.
+
+## Which manifest the server reads
+
+The first that exists wins, so the manifest can never drift from the engine the project runs:
+
+1. `THREENATIVE_CAPABILITIES_MANIFEST` — an explicit override, resolved against the working
+   directory.
+2. `node_modules/@threenative/core/capabilities.json` — found by walking up from the working
+   directory. The installed package ships the manifest its own build generated, so it always
+   describes the engine the project actually links; it moves exactly when the dependency does.
+3. `packages/core/capabilities.json` — found by walking up from the running server file, which
+   answers from the engine repository's own generated manifest when the server is launched from
+   the repository rather than from an installed package.
+4. `capabilities.json` in the working directory — the original default, kept for a bare checkout
+   with a committed copy and no installed engine package.
+
+A project copy committed at scaffold time is therefore inert whenever the package is installed:
+the two never need re-syncing by hand.

package/dist/index.d.ts

@@ -6,13 +6,21 @@ interface ICapabilityEntry {
     readonly signature: string;
     readonly summary: string;
     readonly situations: readonly string[];
+    readonly aliases: readonly string[];
     readonly example: string;
     readonly constraints: readonly string[];
     readonly overrides?: readonly string[];
+    readonly requires?: readonly string[];
+}
+interface INotOwnedCapability {
+    readonly id: string;
+    readonly situations: readonly string[];
+    readonly guidance: string;
 }
 interface ICapabilityManifest {
     readonly version: number;
     readonly entries: readonly ICapabilityEntry[];
+    readonly notOwned: readonly INotOwnedCapability[];
 }
 interface ICapabilitySearchResult {
     readonly symbol: string;
@@ -20,7 +28,14 @@ interface ICapabilitySearchResult {
     readonly summary: string;
     readonly example: string;
     readonly constraints: readonly string[];
+    readonly requires?: readonly string[];
     readonly matchedSituation: string;
+    readonly score: number;
+}
+interface ICapabilitySearchResponse {
+    readonly verdict: "matched" | "none";
+    readonly results: readonly ICapabilitySearchResult[];
+    readonly guidance: string;
 }
 interface ICapabilityDetail extends ICapabilityEntry {
 }
@@ -44,9 +59,12 @@ interface IEngineTool {
     };
 }
 declare const ENGINE_MCP_TOOL_NAMES: readonly ["engine_search_capabilities", "engine_capability_detail"];
+/** Chosen by the current-manifest threshold sweep: the highest recalled candidate at 0.27. */
+declare const RELEVANCE_FLOOR = 0.27;
 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 capabilitySituationTokens(value: string): string[];
+declare function searchCapabilities(situation: string, manifestFile?: string, scope?: "mechanic" | "request"): ICapabilitySearchResponse;
 declare function capabilityDetail(symbol: string, manifestFile?: string): ICapabilityDetail;
 declare function toolDefinitions(): readonly IEngineTool[];
 /**
@@ -57,4 +75,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 ICapabilitySearchResult, type IEngineTool, capabilityDetail, 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, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync, readFileSync } from 'fs';
+import { realpathSync, readFileSync, existsSync } from 'fs';
 import path from 'path';
 import { createInterface } from 'readline';
 import { fileURLToPath } from 'url';
@@ -12,32 +12,143 @@ var DEFAULT_MANIFEST_FILE = "capabilities.json";
 var STOP_WORDS = /* @__PURE__ */ new Set([
   "a",
   "add",
+  "after",
+  "again",
+  "all",
+  "also",
   "an",
   "and",
+  "any",
+  "are",
   "around",
+  "as",
+  "at",
+  "be",
+  "because",
+  "been",
+  "being",
+  "both",
   "build",
+  "but",
   "by",
+  "can",
   "create",
+  "do",
+  "does",
+  "each",
+  "either",
+  "else",
+  "every",
   "for",
   "from",
   "game",
+  "get",
+  "give",
+  "had",
+  "has",
+  "have",
+  "how",
+  "if",
   "in",
   "into",
+  "is",
   "it",
+  "its",
+  "let",
+  "made",
   "make",
+  "may",
+  "might",
+  "must",
+  "no",
+  "nor",
+  "not",
   "of",
   "on",
-  "that",
-  "the",
+  "once",
+  "one",
+  "only",
+  "or",
+  "other",
+  "our",
+  "own",
+  "put",
+  "rather",
+  "same",
+  "shall",
+  "should",
+  "since",
+  "so",
+  "some",
+  "such",
+  "take",
+  "than",
+  "their",
+  "them",
+  "then",
+  "there",
+  "these",
+  "they",
+  "this",
+  "those",
+  "though",
+  "thus",
   "to",
+  "too",
   "use",
-  "with"
+  "very",
+  "was",
+  "want",
+  "way",
+  "we",
+  "well",
+  "were",
+  "what",
+  "when",
+  "whenever",
+  "where",
+  "whether",
+  "which",
+  "while",
+  "who",
+  "whose",
+  "why",
+  "will",
+  "with",
+  "within",
+  "without",
+  "would",
+  "yet",
+  "you",
+  "your"
 ]);
 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.`;
+var RELEVANCE_FLOOR = 0.27;
+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. A response with verdict "none" is an actionable answer: follow its guidance and write game-owned behavior in src/ instead of rephrasing the same request.`;
+var GENERIC_GUIDANCE = "No installed engine capability matches this situation. Decompose it into concrete mechanics and write the game-owned behavior in your project's src/; inspect the relevant template AGENTS.md before adding a package.";
 function defaultManifestPath(cwd = process.cwd()) {
-  return path.resolve(cwd, process.env.THREENATIVE_CAPABILITIES_MANIFEST ?? DEFAULT_MANIFEST_FILE);
+  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 parent = path.dirname(directory);
+    if (parent === directory) break;
+  }
+  for (let directory = path.dirname(fileURLToPath(import.meta.url)); ; directory = path.dirname(directory)) {
+    const repository = path.join(directory, "packages", "core", "capabilities.json");
+    if (existsSync(repository)) return repository;
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+  }
+  return path.resolve(cwd, DEFAULT_MANIFEST_FILE);
 }
 function manifestError(file, reason) {
   return new Error(`TN_ENGINE_CAPABILITIES_MANIFEST: ${file}: ${reason}`);
@@ -46,14 +157,29 @@ 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");
+  if (!isRecord(value) || value.version !== 2 || !Array.isArray(value.entries) || !Array.isArray(value.notOwned)) {
+    throw manifestError(
+      file,
+      "root must contain manifest version 2, entries array, and notOwned 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")) {
+    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")) {
       throw manifestError(file, `entry ${index} is malformed`);
     }
   }
+  const notOwnedIds = /* @__PURE__ */ new Set();
+  for (const [index, raw] of value.notOwned.entries()) {
+    if (!isRecord(raw) || typeof raw.id !== "string" || raw.id.trim().length === 0 || !Array.isArray(raw.situations) || raw.situations.length === 0 || !raw.situations.every(
+      (situation) => typeof situation === "string" && situation.trim().length > 0
+    ) || typeof raw.guidance !== "string" || raw.guidance.trim().length === 0) {
+      throw manifestError(file, `notOwned ${index} is malformed`);
+    }
+    if (notOwnedIds.has(raw.id)) {
+      throw manifestError(file, `notOwned contains duplicate id '${raw.id}'`);
+    }
+    notOwnedIds.add(raw.id);
+  }
   return value;
 }
 function loadCapabilityManifest(file = defaultManifestPath()) {
@@ -71,15 +197,103 @@ function loadCapabilityManifest(file = defaultManifestPath()) {
     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 undouble(stem2) {
+  const last = stem2.at(-1);
+  return stem2.length > 3 && last !== void 0 && last === stem2.at(-2) && !"aeiou".includes(last) ? stem2.slice(0, -1) : stem2;
+}
+function stem(token) {
+  const stripped = suffixStripped(token);
+  return stripped.length > 3 && stripped.endsWith("e") ? stripped.slice(0, -1) : stripped;
+}
+function suffixStripped(token) {
+  if (token.length > 4 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
+  if (token.length > 4 && token.endsWith("ing")) return undouble(token.slice(0, -3));
+  if (token.length > 4 && token.endsWith("ed")) return undouble(token.slice(0, -2));
+  if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss")) return token.slice(0, -1);
+  return token;
+}
+function capabilitySituationTokens(value) {
+  return value.toLocaleLowerCase().split(/[^a-z0-9]+/u).filter((token) => token.length > 1 && !STOP_WORDS.has(token)).map(stem);
+}
+var tokens = capabilitySituationTokens;
+function tokenWeights(entries) {
+  const frequency = /* @__PURE__ */ new Map();
+  let situations = 0;
+  for (const entry of entries) {
+    for (const situation of [...entry.situations, ...entry.aliases]) {
+      situations += 1;
+      for (const token of new Set(tokens(situation)))
+        frequency.set(token, (frequency.get(token) ?? 0) + 1);
+    }
+  }
+  const weights = /* @__PURE__ */ new Map();
+  for (const [token, count] of frequency) weights.set(token, Math.log(1 + situations / count));
+  return weights;
+}
+function weightOf(weights, token) {
+  return weights.get(token) ?? 0;
+}
+var DISTINCTIVE_SITUATION_SHARE = 0.02;
+var DISTINCTIVE_FLOOR = Math.log(1 + 1 / DISTINCTIVE_SITUATION_SHARE);
+var AGREEMENT_WEIGHT = 0.4;
+var LONE_WORD_COVERAGE = 0.22;
+function agreement(situation, query) {
+  const matched = situation.filter((token) => query.has(token)).length;
+  return 1 + AGREEMENT_WEIGHT * Math.max(0, matched - 1);
+}
+function scorePhrase(value, queryTokens, queryText, weights) {
+  const phrase = tokens(value);
+  const unique = [...new Set(phrase)];
+  const total = unique.reduce((sum, token) => sum + weightOf(weights, token), 0);
+  const matched = unique.filter((token) => queryTokens.has(token)).reduce((sum, token) => sum + weightOf(weights, token), 0);
+  const phraseBonus = phrase.join(" ").includes(queryText) || queryText.includes(phrase.join(" ")) ? 1 : 0;
+  if (total === 0 || matched === 0 && phraseBonus === 0) return void 0;
+  const coverage = matched / total;
+  const agreed = agreement(unique, queryTokens);
+  return { agreed, coverage, matched, phraseBonus, score: coverage * agreed + phraseBonus };
+}
+function isDistinctivePhrase(candidate) {
+  if (candidate.phraseBonus > 0) return true;
+  if (candidate.matched < DISTINCTIVE_FLOOR) return false;
+  return !(candidate.agreed === 1 && candidate.coverage < LONE_WORD_COVERAGE);
+}
+function scoreReadableSituations(situations, queryTokens, queryText, weights) {
+  let best = 0;
+  let matchedSituation = "";
+  let bestReadableScore = 0;
+  let bestReadableSituation = situations[0] ?? "";
+  for (const situation of situations) {
+    const candidate = scorePhrase(situation, queryTokens, queryText, weights);
+    if (candidate === void 0) continue;
+    if (candidate.score > bestReadableScore) {
+      bestReadableScore = candidate.score;
+      bestReadableSituation = situation;
+    }
+    if (isDistinctivePhrase(candidate) && candidate.score > best) {
+      best = candidate.score;
+      matchedSituation = situation;
+    }
+  }
+  return { best, bestReadableSituation, matchedSituation };
 }
-function situationScore(query, situations) {
+function scoreAliases(aliases, queryTokens, queryText, weights) {
+  let best = 0;
+  for (const alias of aliases) {
+    const candidate = scorePhrase(alias, queryTokens, queryText, weights);
+    if (candidate !== void 0) best = Math.max(best, candidate.score);
+  }
+  return best;
+}
+function situationScore(query, situations, aliases, weights) {
+  if (query.length === 0) return { matchedSituation: "", score: 0 };
+  const queryTokens = new Set(query);
+  const queryText = query.join(" ");
+  const readable = scoreReadableSituations(situations, queryTokens, queryText, weights);
+  const best = Math.max(readable.best, scoreAliases(aliases, queryTokens, queryText, weights));
+  const matchedSituation = readable.matchedSituation.length > 0 ? readable.matchedSituation : best >= RELEVANCE_FLOOR ? readable.bestReadableSituation : "";
+  return matchedSituation.length > 0 ? { matchedSituation, score: best } : { matchedSituation: "", score: 0 };
+}
+function notOwnedSituationScore(query, situations) {
   if (query.length === 0) return { matchedSituation: "", score: 0 };
   const queryText = query.join(" ");
   let best = 0;
@@ -98,9 +312,24 @@ function situationScore(query, situations) {
   }
   return { matchedSituation, score: best };
 }
+function notOwnedMatch(manifest, query) {
+  return manifest.notOwned.map((entry) => ({ entry, ...notOwnedSituationScore(query, entry.situations) })).filter(
+    ({ matchedSituation, score }) => matchedSituation.length > 0 && score >= RELEVANCE_FLOOR
+  ).sort(
+    (left, right) => right.score - left.score || left.entry.id.localeCompare(right.entry.id)
+  )[0];
+}
+function isSpecificNotOwnedMatch(query, matchedSituation) {
+  const queryText = query.join(" ");
+  const phrase = tokens(matchedSituation);
+  const phraseText = phrase.join(" ");
+  if (queryText === phraseText) return true;
+  if (query.length === 1 && phrase.length <= 2 && phrase.includes(query[0] ?? "")) return true;
+  if (query.length > phrase.length + 1) return false;
+  return new Set(phrase.filter((token) => query.includes(token))).size >= 2;
+}
 function capabilitySearchKey(entry) {
   return `${entry.importPath}
-${entry.signature}
 ${entry.summary}
 ${entry.situations.join("\n")}`;
 }
@@ -110,7 +339,18 @@ function searchCapabilities(situation, manifestFile = defaultManifestPath(), sco
   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(
+  const weights = tokenWeights(manifest.entries);
+  const notOwned = notOwnedMatch(manifest, query);
+  if (notOwned !== void 0 && isSpecificNotOwnedMatch(query, notOwned.matchedSituation)) {
+    return {
+      guidance: notOwned.entry.guidance,
+      results: [],
+      verdict: "none"
+    };
+  }
+  const results = manifest.entries.map((entry) => ({ entry, ...situationScore(query, entry.situations, entry.aliases, weights) })).filter(
+    ({ matchedSituation, score }) => matchedSituation.length > 0 && score >= RELEVANCE_FLOOR
+  ).sort(
     (left, right) => right.score - left.score || `${left.entry.importPath}:${left.entry.symbol}`.localeCompare(
       `${right.entry.importPath}:${right.entry.symbol}`
     )
@@ -118,14 +358,22 @@ function searchCapabilities(situation, manifestFile = defaultManifestPath(), sco
     (candidate, index, candidates) => candidates.findIndex(
       (other) => capabilitySearchKey(other.entry) === capabilitySearchKey(candidate.entry)
     ) === index
-  ).slice(0, limit).map(({ entry, matchedSituation }) => ({
+  ).slice(0, limit).map(({ entry, matchedSituation, score }) => ({
     constraints: entry.constraints,
     example: entry.example,
     importPath: entry.importPath,
     matchedSituation,
+    ...entry.requires === void 0 ? {} : { requires: entry.requires },
+    score,
     summary: entry.summary,
     symbol: entry.symbol
   }));
+  if (results.length > 0) return { guidance: "", results, verdict: "matched" };
+  return {
+    guidance: notOwned?.entry.guidance ?? GENERIC_GUIDANCE,
+    results: [],
+    verdict: "none"
+  };
 }
 function capabilityDetail(symbol, manifestFile = defaultManifestPath()) {
   if (typeof symbol !== "string" || symbol.trim().length === 0)
@@ -139,7 +387,7 @@ 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.',
+    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 and score explain every result. The response verdict "none" is an actionable answer with guidance, not a failed search.',
     inputSchema: {
       additionalProperties: false,
       properties: {
@@ -216,7 +464,7 @@ function handleLine(line, manifestFile) {
         capabilities: { tools: { listChanged: false } },
         instructions: AUTHORING_INSTRUCTIONS,
         protocolVersion: "2025-06-18",
-        serverInfo: { name: "threenative-engine-mcp", version: "0.2.0" }
+        serverInfo: { name: "threenative-engine-mcp", version: "0.2.2" }
       });
     }
     if (request.method === "tools/list") {
@@ -250,4 +498,4 @@ if (entryPath !== void 0 && realpathSync(path.resolve(entryPath)) === realpathSy
   }
 }
 
-export { ENGINE_MCP_TOOL_NAMES, capabilityDetail, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };
+export { ENGINE_MCP_TOOL_NAMES, RELEVANCE_FLOOR, capabilityDetail, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };

package/package.json

@@ -1,8 +1,26 @@
 {
   "name": "threenative-engine-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "license": "MIT",
   "description": "Offline MCP capability discovery for ThreeNative authoring agents.",
+  "keywords": [
+    "threenative",
+    "mcp",
+    "model-context-protocol",
+    "three",
+    "threejs",
+    "agents",
+    "capabilities"
+  ],
+  "homepage": "https://github.com/ThreeNativeHQ/threenative#readme",
+  "bugs": {
+    "url": "https://github.com/ThreeNativeHQ/threenative/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThreeNativeHQ/threenative.git",
+    "directory": "packages/engine-mcp"
+  },
   "type": "module",
   "files": [
     "dist",