@threenative/core 0.3.0 → 0.3.1

package/mcp/engine-server.mjs

@@ -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.1" }
       });
     }
     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/mcp/engine.mjs

@@ -5,19 +5,27 @@ import { fileURLToPath } from "node:url";
 import { launchMcpServer } from "./launch.mjs";
 import { MCP_PACKAGES } from "./servers.mjs";
 
-// The capability server reads a committed manifest from the project root. A scaffolded game has
-// one; a project that added ThreeNative to an existing tree does not, so fall back to the copy this
-// package ships rather than letting the server refuse to start.
+// The capability server must answer with the manifest of the engine the game actually runs, and
+// the copy this package ships is generated by the same build as that engine. Prefer it over any
+// copy the project committed: a committed snapshot drifts the moment the engine dependency moves.
+// With no bundled copy (a stripped install), fall through to the server's own defaults.
 const bundled = path.resolve(fileURLToPath(import.meta.url), "..", "..", "capabilities.json");
-const env =
-  existsSync(path.join(process.cwd(), "capabilities.json")) || !existsSync(bundled)
-    ? {}
-    : Object.fromEntries([["THREENATIVE_CAPABILITIES_MANIFEST", bundled]]);
+const env = existsSync(bundled)
+  ? Object.fromEntries([["THREENATIVE_CAPABILITIES_MANIFEST", bundled]])
+  : {};
 
 const localServer = path.resolve(fileURLToPath(import.meta.url), "..", "engine-server.mjs");
 if (existsSync(localServer)) {
   const { runServer } = await import("./engine-server.mjs");
   runServer(env.THREENATIVE_CAPABILITIES_MANIFEST);
 } else {
+  // Say so. This branch fetches a package over the network, and when the network is slow, absent
+  // or the version unpublished it produces no output at all — the host simply waits. A CI run
+  // spent 30 s here twice and reported `threenative-engine initialize timed out after 30000ms`
+  // with empty stderr, which named neither the fallback nor the reason for it. The bundled server
+  // is missing here for a reason worth reporting even when the fetch then succeeds.
+  process.stderr.write(
+    `TN_MCP_ENGINE_FALLBACK: no bundled capability server at ${localServer}; fetching ${MCP_PACKAGES.engine.name}@${MCP_PACKAGES.engine.version} over the network instead. A packaged @threenative/core should always carry the bundle.\n`,
+  );
   await launchMcpServer({ ...MCP_PACKAGES.engine, env });
 }

package/mcp/install.d.mts

@@ -0,0 +1,37 @@
+// Types for `install.mjs`, the same contract `servers.d.mts` provides for `servers.mjs`. That file
+// is plain JavaScript by design — `@threenative/core`'s postinstall runs it before anything is
+// built — so it can never be a `.ts`. Without this declaration every consumer reached for
+// `@ts-expect-error` and then retyped the host table locally.
+
+/** One project-scoped host config the installer writes. */
+export interface IMcpHost {
+  readonly file: string;
+  readonly format: string;
+  readonly id: string;
+  readonly label: string;
+  readonly seed?: Readonly<Record<string, unknown>>;
+}
+
+/** What a single config write did, or why it was left alone. */
+export type McpConfigOutcome =
+  | "conflict"
+  | "created"
+  | "unchanged"
+  | "unreadable"
+  | "unwritable"
+  | "updated";
+
+export declare const MCP_HOSTS: readonly IMcpHost[];
+export declare function installTarget(
+  environment?: NodeJS.ProcessEnv,
+  cwd?: string,
+): string | undefined;
+export declare function ensureJsonMcpConfig(
+  target: string,
+  file: string,
+  format: string,
+  seed?: Readonly<Record<string, unknown>>,
+): McpConfigOutcome;
+export declare function ensureMcpConfig(target: string): McpConfigOutcome;
+export declare function ensureCodexMcpConfig(target: string): McpConfigOutcome;
+export declare function ensureHostMcpConfigs(target: string): Map<string, McpConfigOutcome>;

package/mcp/install.mjs

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { mergeMcpServers } from "./servers.mjs";
+import { CODEX_MCP_SERVERS, mergeMcpServers } from "./servers.mjs";
 
 /** The project being installed into, or undefined when this install has no project to write to —
  * a nested dependency install, or core's own workspace build. */
@@ -9,19 +9,68 @@ export function installTarget(environment = process.env, cwd = process.cwd()) {
   if (target.split(path.sep).includes("node_modules")) return undefined;
   const manifestPath = path.join(target, "package.json");
   if (!existsSync(manifestPath)) return undefined;
-  let name;
+  let manifest;
   try {
-    name = JSON.parse(readFileSync(manifestPath, "utf8")).name;
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
   } catch {
     return undefined;
   }
-  return name === "@threenative/core" ? undefined : target;
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest))
+    return undefined;
+  if (manifest.name === "@threenative/core") return undefined;
+  const dependencyGroups = [
+    manifest.dependencies,
+    manifest.devDependencies,
+    manifest.optionalDependencies,
+    manifest.peerDependencies,
+  ];
+  const declaresCore = dependencyGroups.some(
+    (dependencies) =>
+      typeof dependencies === "object" &&
+      dependencies !== null &&
+      Object.hasOwn(dependencies, "@threenative/core"),
+  );
+  return declaresCore ? target : undefined;
 }
 
-/** Adds the ThreeNative servers to `<target>/.mcp.json`, creating it when absent. Returns what it
+/** Every agent host that reads a **project-scoped** MCP config, and the file each one reads.
+ *
+ * Project-scoped is the whole admission rule. A host that only reads a machine-wide config
+ * (Windsurf, Cline, Amp, the JetBrains assistants) is deliberately absent: installing a library
+ * into one game must never edit a file that governs every other project on the machine. Those
+ * hosts are wired by hand, and `docs/architecture/` says so. */
+export const MCP_HOSTS = Object.freeze([
+  Object.freeze({
+    id: "claude-code",
+    label: "Claude Code",
+    file: ".mcp.json",
+    format: "mcpServers",
+  }),
+  Object.freeze({ id: "codex", label: "Codex", file: ".codex/config.toml", format: "codex" }),
+  Object.freeze({ id: "cursor", label: "Cursor", file: ".cursor/mcp.json", format: "mcpServers" }),
+  Object.freeze({ id: "vscode", label: "VS Code", file: ".vscode/mcp.json", format: "vscode" }),
+  Object.freeze({
+    id: "gemini-cli",
+    label: "Gemini CLI",
+    file: ".gemini/settings.json",
+    format: "mcpServers",
+  }),
+  Object.freeze({
+    id: "opencode",
+    label: "opencode",
+    file: "opencode.json",
+    format: "opencode",
+    // Written only when this installer creates the file, so a second install still reports
+    // "unchanged" rather than rewriting a config the user has since edited.
+    seed: Object.freeze({ $schema: "https://opencode.ai/config.json" }),
+  }),
+  Object.freeze({ id: "zed", label: "Zed", file: ".zed/settings.json", format: "zed" }),
+]);
+
+/** Adds the ThreeNative servers to one host's JSON config, creating it when absent. Returns what it
  * did so the installer can say so once and stay quiet otherwise. */
-export function ensureMcpConfig(target) {
-  const configPath = path.join(target, ".mcp.json");
+export function ensureJsonMcpConfig(target, file, format, seed = undefined) {
+  const configPath = path.join(target, file);
   let existing;
   if (existsSync(configPath)) {
     // A config we cannot parse is still the user's. Rewriting it would drop servers we never wrote.
@@ -31,29 +80,28 @@ export function ensureMcpConfig(target) {
       return "unreadable";
     }
   }
-  const { changed, config } = mergeMcpServers(existing);
-  if (!changed) return "unchanged";
-  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
-  return existing === undefined ? "created" : "updated";
+  let merged;
+  try {
+    merged = mergeMcpServers(existing, format);
+  } catch {
+    return "unreadable";
+  }
+  const { changed, config, conflicts } = merged;
+  if (!changed) return conflicts.length > 0 ? "conflict" : "unchanged";
+  const written = existing === undefined ? { ...seed, ...config } : config;
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(written, null, 2)}\n`);
+  return conflicts.length > 0 ? "conflict" : existing === undefined ? "created" : "updated";
 }
 
-const CODEX_MCP_SERVERS = [
-  {
-    body: `[mcp_servers.threenative-assets]\ncommand = "node"\nargs = ["./node_modules/@threenative/core/mcp/assets.mjs"]\n\n[mcp_servers.threenative-assets.env]\nASSET_DOWNLOAD_DIR = "./public/assets"\nAUDIO_DOWNLOAD_DIR = "./public/audio"`,
-    name: "threenative-assets",
-  },
-  {
-    body: `[mcp_servers.threenative-sculpt]\ncommand = "node"\nargs = ["./node_modules/@threenative/core/mcp/sculpt.mjs"]`,
-    name: "threenative-sculpt",
-  },
-  {
-    body: `[mcp_servers.threenative-engine]\ncommand = "node"\nargs = ["./node_modules/@threenative/core/mcp/engine.mjs"]`,
-    name: "threenative-engine",
-  },
-];
+/** Adds the ThreeNative servers to `<target>/.mcp.json`, the config Claude Code reads. */
+export function ensureMcpConfig(target) {
+  return ensureJsonMcpConfig(target, ".mcp.json", "mcpServers");
+}
 
 /** Adds any missing ThreeNative servers to Codex's project-scoped MCP config without replacing
- * user-authored settings or server definitions. */
+ * user-authored settings or server definitions. TOML rather than JSON, so this one appends text
+ * instead of re-serialising: a config we cannot parse back is one we must not rewrite. */
 export function ensureCodexMcpConfig(target) {
   const directory = path.join(target, ".codex");
   const configPath = path.join(directory, "config.toml");
@@ -75,3 +123,23 @@ export function ensureCodexMcpConfig(target) {
   );
   return existing.length === 0 ? "created" : "updated";
 }
+
+/** Wires every host in `MCP_HOSTS`, mapping host id to what the write did. One host's unreadable
+ * or unwritable config never stops the rest: a project with a hand-edited `.cursor/mcp.json`
+ * should still get its Codex and VS Code tools. */
+export function ensureHostMcpConfigs(target) {
+  const outcomes = new Map();
+  for (const host of MCP_HOSTS) {
+    try {
+      outcomes.set(
+        host.id,
+        host.format === "codex"
+          ? ensureCodexMcpConfig(target)
+          : ensureJsonMcpConfig(target, host.file, host.format, host.seed),
+      );
+    } catch {
+      outcomes.set(host.id, "unreadable");
+    }
+  }
+  return outcomes;
+}

package/mcp/servers.d.mts

@@ -0,0 +1,34 @@
+// Types for `servers.mjs`. That file is plain JavaScript by design — `@threenative/core`'s
+// postinstall runs it before anything is built — so it can never be a `.ts`. Without this
+// declaration every consumer reached for `@ts-expect-error` and then cast the result back into a
+// shape of its own, which is three private copies of one contract.
+
+export interface IMcpServerEntry {
+  readonly args: readonly string[];
+  readonly command: string;
+  readonly env?: Readonly<Record<string, string>>;
+}
+
+export interface IMcpPackage {
+  readonly name: string;
+  readonly version: string;
+}
+
+/** One host's whole config with this format's server table merged in. The table's key is the
+ * host's own (`mcpServers`, `servers`, `mcp`, `context_servers`), so a caller reading a key it did
+ * not ask for gets `undefined` rather than a silently empty object. */
+export interface IMcpConfigFormat {
+  readonly changed: boolean;
+  readonly config: Record<string, Record<string, Record<string, unknown>> | undefined>;
+}
+
+export interface ICodexMcpServer {
+  readonly body: string;
+  readonly name: string;
+}
+
+export declare const MCP_SERVERS: Readonly<Record<string, IMcpServerEntry>>;
+export declare const MCP_PACKAGES: Readonly<Record<string, IMcpPackage>>;
+export declare const SERVER_FORMAT_NAMES: readonly string[];
+export declare const CODEX_MCP_SERVERS: readonly ICodexMcpServer[];
+export declare function mergeMcpServers(existing: unknown, format?: string): IMcpConfigFormat;