typegraph-mcp 0.9.31 → 0.9.33

package/README.md

@@ -80,13 +80,13 @@ This gives you 14 MCP tools, 5 workflow skills that teach Claude *when* and *how
 
 **Other agents** (Cursor, Codex CLI, Gemini CLI, GitHub Copilot) — restart your agent session. The MCP server and skills are already configured.
 
-For **Codex CLI**, setup now registers the server with `codex mcp add` using absolute paths so the tools work even when Codex launches from outside your project root.
+For **Codex CLI**, setup now writes a project-local `.codex/config.toml` entry using absolute paths so the tools stay scoped to the project and still work when Codex launches from a subdirectory.
 
 First query takes ~2s (tsserver warmup). Subsequent queries: 1-60ms.
 
 ## Requirements
 
-- **Node.js** >= 18
+- **Node.js** >= 22
 - **TypeScript** >= 5.0 in the target project
 - **npm** for dependency installation
 
@@ -141,30 +141,31 @@ npx typegraph-mcp check
 
 | Symptom | Fix |
 |---|---|
-| Server won't start | `cd plugins/typegraph-mcp && npm install` |
-| "TypeScript not found" | Add `typescript` to devDependencies |
+| Server won't start | `cd plugins/typegraph-mcp && npm install --include=optional` |
+| "TypeScript not found" | Run `pnpm install` or `npm install`; if TypeScript is not declared, add it to devDependencies first |
 | Tools return empty results | Check `TYPEGRAPH_TSCONFIG` points to the right tsconfig |
 | Build errors from plugins/ | Add `"plugins/**"` to tsconfig.json `exclude` array |
+| `@esbuild/*` or `@rollup/*` package missing | Reinstall with Node 22: `npm install --include=optional` |
 | "npm warn Unknown project config" | Safe to ignore — caused by pnpm settings in your `.npmrc` that npm doesn't recognize |
 
 ## Manual MCP configuration
 
 ### Codex CLI
 
-Register the server with absolute paths:
+Add this to your project's `.codex/config.toml`:
 
-```bash
-codex mcp add typegraph \
-  --env TYPEGRAPH_PROJECT_ROOT=/absolute/path/to/your-project \
-  --env TYPEGRAPH_TSCONFIG=/absolute/path/to/your-project/tsconfig.json \
-  -- npx tsx /absolute/path/to/your-project/plugins/typegraph-mcp/server.ts
+```toml
+[mcp_servers.typegraph]
+command = "npx"
+args = ["tsx", "/absolute/path/to/your-project/plugins/typegraph-mcp/server.ts"]
+env = { TYPEGRAPH_PROJECT_ROOT = "/absolute/path/to/your-project", TYPEGRAPH_TSCONFIG = "/absolute/path/to/your-project/tsconfig.json" }
 ```
 
-Verify with:
+Codex only loads project `.codex/config.toml` files for trusted projects. If needed, add this to `~/.codex/config.toml`:
 
-```bash
-codex mcp get typegraph
-codex mcp list
+```toml
+[projects."/absolute/path/to/your-project"]
+trust_level = "trusted"
 ```
 
 ### JSON-based MCP clients
@@ -213,7 +214,8 @@ Two subsystems start concurrently:
 ```bash
 git clone https://github.com/guyowen/typegraph-mcp.git
 cd typegraph-mcp
-npm install
+nvm use
+npm install --include=optional
 ```
 
 ### Run locally against a project

package/check.ts

@@ -102,6 +102,105 @@ function testTsserver(projectRoot: string): Promise<boolean> {
   });
 }
 
+function readProjectCodexConfig(projectRoot: string): string | null {
+  const configPath = path.resolve(projectRoot, ".codex/config.toml");
+  if (!fs.existsSync(configPath)) return null;
+  return fs.readFileSync(configPath, "utf-8");
+}
+
+function hasCodexTypegraphRegistration(content: string): boolean {
+  return /\[mcp_servers\.typegraph\]/.test(content);
+}
+
+function hasCompleteCodexTypegraphRegistration(content: string): boolean {
+  return (
+    hasCodexTypegraphRegistration(content) &&
+    /command\s*=\s*"[^"]+"/.test(content) &&
+    /args\s*=\s*\[[\s\S]*"tsx"/.test(content) &&
+    /TYPEGRAPH_PROJECT_ROOT\s*=/.test(content) &&
+    /TYPEGRAPH_TSCONFIG\s*=/.test(content)
+  );
+}
+
+function hasTrustedCodexProject(projectRoot: string): boolean | null {
+  const home = process.env.HOME;
+  if (!home) return null;
+
+  const globalConfigPath = path.join(home, ".codex/config.toml");
+  if (!fs.existsSync(globalConfigPath)) return null;
+
+  const lines = fs.readFileSync(globalConfigPath, "utf-8").split(/\r?\n/);
+  let currentProject: string | null = null;
+  let currentTrusted = false;
+
+  const matchesTrustedProject = (): boolean =>
+    currentProject !== null &&
+    currentTrusted &&
+    (projectRoot === currentProject || projectRoot.startsWith(currentProject + path.sep));
+
+  for (const line of lines) {
+    const sectionMatch = line.match(/^\[projects\."([^"]+)"\]\s*$/);
+    if (sectionMatch) {
+      if (matchesTrustedProject()) return true;
+      currentProject = path.resolve(sectionMatch[1]!);
+      currentTrusted = false;
+      continue;
+    }
+
+    if (line.startsWith("[")) {
+      if (matchesTrustedProject()) return true;
+      currentProject = null;
+      currentTrusted = false;
+      continue;
+    }
+
+    if (currentProject && /\btrust_level\s*=\s*"trusted"/.test(line)) {
+      currentTrusted = true;
+    }
+  }
+
+  return matchesTrustedProject();
+}
+
+function readProjectPackageJson(projectRoot: string): Record<string, unknown> | null {
+  const packageJsonPath = path.resolve(projectRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function getProjectInstallCommand(projectRoot: string, packageJson: Record<string, unknown> | null): string {
+  const packageManager = typeof packageJson?.["packageManager"] === "string"
+    ? packageJson["packageManager"]
+    : "";
+
+  if (packageManager.startsWith("pnpm@") || fs.existsSync(path.join(projectRoot, "pnpm-lock.yaml"))) {
+    return "pnpm install";
+  }
+  if (packageManager.startsWith("yarn@") || fs.existsSync(path.join(projectRoot, "yarn.lock"))) {
+    return "yarn install";
+  }
+  return "npm install";
+}
+
+function hasDeclaredDependency(packageJson: Record<string, unknown> | null, packageName: string): boolean {
+  const depKeys = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+  ] as const;
+
+  return depKeys.some((key) => {
+    const deps = packageJson?.[key];
+    return typeof deps === "object" && deps !== null && packageName in deps;
+  });
+}
+
 // ─── Main ────────────────────────────────────────────────────────────────────
 
 export async function main(configOverride?: TypegraphConfig): Promise<CheckResult> {
@@ -111,6 +210,8 @@ export async function main(configOverride?: TypegraphConfig): Promise<CheckResul
   let passed = 0;
   let failed = 0;
   let warned = 0;
+  const projectPackageJson = readProjectPackageJson(projectRoot);
+  const installCommand = getProjectInstallCommand(projectRoot, projectPackageJson);
 
   function pass(msg: string): void {
     console.log(`  \u2713 ${msg}`);
@@ -142,10 +243,10 @@ export async function main(configOverride?: TypegraphConfig): Promise<CheckResul
   // 1. Node.js version
   const nodeVersion = process.version;
   const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0]!, 10);
-  if (nodeMajor >= 18) {
-    pass(`Node.js ${nodeVersion} (>= 18 required)`);
+  if (nodeMajor >= 22) {
+    pass(`Node.js ${nodeVersion} (>= 22 required)`);
   } else {
-    fail(`Node.js ${nodeVersion} is too old`, "Upgrade Node.js to >= 18");
+    fail(`Node.js ${nodeVersion} is too old`, "Upgrade Node.js to >= 22");
   }
 
   // 2. tsx availability (if we're running, tsx works — but check it's in the project)
@@ -168,9 +269,14 @@ export async function main(configOverride?: TypegraphConfig): Promise<CheckResul
     tsVersion = tsPkg.version;
     pass(`TypeScript found (v${tsVersion})`);
   } catch {
+    const hasDeclaredTs = hasDeclaredDependency(projectPackageJson, "typescript");
     fail(
-      "TypeScript not found in project",
-      "Add `typescript` to devDependencies and run `npm install`"
+      hasDeclaredTs
+        ? "TypeScript is declared but not installed in project"
+        : "TypeScript not found in project",
+      hasDeclaredTs
+        ? `Run \`${installCommand}\` to install project dependencies`
+        : `Add \`typescript\` to devDependencies and run \`${installCommand}\``
     );
   }
 
@@ -186,18 +292,50 @@ export async function main(configOverride?: TypegraphConfig): Promise<CheckResul
   // Check for plugin .mcp.json in the tool directory (embedded plugin install)
   const pluginMcpPath = path.join(toolDir, ".mcp.json");
   const hasPluginMcp = fs.existsSync(pluginMcpPath) && fs.existsSync(path.join(toolDir, ".claude-plugin/plugin.json"));
+  const projectCodexConfig = readProjectCodexConfig(projectRoot);
+  const hasProjectCodexRegistration =
+    projectCodexConfig !== null && hasCompleteCodexTypegraphRegistration(projectCodexConfig);
   const codexGet = spawnSync("codex", ["mcp", "get", "typegraph"], {
     stdio: "pipe",
     encoding: "utf-8",
   });
-  const hasCodexRegistration = codexGet.status === 0;
+  const hasGlobalCodexRegistration = codexGet.status === 0;
   if (process.env.CLAUDE_PLUGIN_ROOT) {
     pass("MCP registered via plugin (CLAUDE_PLUGIN_ROOT set)");
   } else if (hasPluginMcp) {
     pass("MCP registered via plugin (.mcp.json + .claude-plugin/ present)");
-  } else if (hasCodexRegistration) {
-    pass("MCP registered in Codex CLI");
+  } else if (projectCodexConfig !== null) {
+    const codexConfigPath = path.resolve(projectRoot, ".codex/config.toml");
+    const hasSection = hasCodexTypegraphRegistration(projectCodexConfig);
+    const hasCommand = /command\s*=\s*"[^"]+"/.test(projectCodexConfig);
+    const hasArgs = /args\s*=\s*\[[\s\S]*"tsx"/.test(projectCodexConfig);
+    const hasEnvRoot = /TYPEGRAPH_PROJECT_ROOT\s*=/.test(projectCodexConfig);
+    const hasEnvTsconfig = /TYPEGRAPH_TSCONFIG\s*=/.test(projectCodexConfig);
+    if (hasProjectCodexRegistration) {
+      pass("MCP registered in project .codex/config.toml");
+      const trusted = hasTrustedCodexProject(projectRoot);
+      if (trusted === false) {
+        warn(
+          "Project Codex config may be ignored",
+          "Add the project (or a parent directory) to ~/.codex/config.toml with trust_level = \"trusted\""
+        );
+      }
+    } else {
+      const issues: string[] = [];
+      if (!hasSection) issues.push("[mcp_servers.typegraph] section is missing");
+      if (!hasCommand) issues.push("command is missing");
+      if (!hasArgs) issues.push("args should include 'tsx'");
+      if (!hasEnvRoot) issues.push("TYPEGRAPH_PROJECT_ROOT is missing");
+      if (!hasEnvTsconfig) issues.push("TYPEGRAPH_TSCONFIG is missing");
+      fail(
+        `Project .codex/config.toml registration incomplete: ${issues.join(", ")}`,
+        `Update ${codexConfigPath} with a complete [mcp_servers.typegraph] entry`
+      );
+    }
+  } else if (hasGlobalCodexRegistration) {
+    pass("MCP registered in global Codex CLI config");
   } else {
+    const codexConfigPath = path.resolve(projectRoot, ".codex/config.toml");
     const mcpJsonPath = path.resolve(projectRoot, ".claude/mcp.json");
     if (fs.existsSync(mcpJsonPath)) {
       try {
@@ -244,7 +382,10 @@ export async function main(configOverride?: TypegraphConfig): Promise<CheckResul
         );
       }
     } else {
-      fail(".claude/mcp.json not found", `Create .claude/mcp.json with typegraph server registration`);
+      fail(
+        "No MCP registration found",
+        `Create ${codexConfigPath} with [mcp_servers.typegraph] or create .claude/mcp.json with typegraph server registration`
+      );
     }
   }
 

package/cli.ts

@@ -15,7 +15,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { execSync, spawnSync } from "node:child_process";
+import { execSync } from "node:child_process";
 import * as p from "@clack/prompts";
 import { resolveConfig } from "./config.js";
 
@@ -192,6 +192,87 @@ function getAbsoluteMcpServerEntry(projectRoot: string): {
   };
 }
 
+function getCodexConfigPath(projectRoot: string): string {
+  return path.resolve(projectRoot, ".codex/config.toml");
+}
+
+function hasCodexMcpSection(content: string): boolean {
+  return content.includes("[mcp_servers.typegraph]");
+}
+
+function upsertCodexMcpSection(content: string, block: string): { content: string; changed: boolean } {
+  const sectionRe = /\n?\[mcp_servers\.typegraph\]\n[\s\S]*?(?=\n\[|$)/;
+  const normalizedBlock = block.trim();
+
+  if (sectionRe.test(content)) {
+    const existingSection = (content.match(sectionRe)?.[0] ?? "").trim();
+    if (existingSection === normalizedBlock) {
+      return { content, changed: false };
+    }
+
+    const nextContent = content.replace(sectionRe, `\n${normalizedBlock}\n`);
+    return { content: nextContent.trimEnd() + "\n", changed: true };
+  }
+
+  const nextContent = content
+    ? content.trimEnd() + "\n\n" + normalizedBlock + "\n"
+    : normalizedBlock + "\n";
+  return { content: nextContent, changed: true };
+}
+
+function makeCodexMcpBlock(projectRoot: string): string {
+  const absoluteEntry = getAbsoluteMcpServerEntry(projectRoot);
+  return [
+    "",
+    "[mcp_servers.typegraph]",
+    `command = "${absoluteEntry.command}"`,
+    `args = ["${absoluteEntry.args[0]}", "${absoluteEntry.args[1]}"]`,
+    `env = { TYPEGRAPH_PROJECT_ROOT = "${absoluteEntry.env.TYPEGRAPH_PROJECT_ROOT}", TYPEGRAPH_TSCONFIG = "${absoluteEntry.env.TYPEGRAPH_TSCONFIG}" }`,
+    "",
+  ].join("\n");
+}
+
+function isCodexProjectTrusted(projectRoot: string): boolean {
+  const home = process.env.HOME;
+  if (!home) return false;
+
+  const globalConfigPath = path.join(home, ".codex/config.toml");
+  if (!fs.existsSync(globalConfigPath)) return false;
+
+  const content = fs.readFileSync(globalConfigPath, "utf-8");
+  const lines = content.split(/\r?\n/);
+  let currentProject: string | null = null;
+  let currentTrusted = false;
+
+  const matchesTrustedProject = (): boolean =>
+    currentProject !== null &&
+    currentTrusted &&
+    (projectRoot === currentProject || projectRoot.startsWith(currentProject + path.sep));
+
+  for (const line of lines) {
+    const sectionMatch = line.match(/^\[projects\."([^"]+)"\]\s*$/);
+    if (sectionMatch) {
+      if (matchesTrustedProject()) return true;
+      currentProject = path.resolve(sectionMatch[1]!);
+      currentTrusted = false;
+      continue;
+    }
+
+    if (line.startsWith("[")) {
+      if (matchesTrustedProject()) return true;
+      currentProject = null;
+      currentTrusted = false;
+      continue;
+    }
+
+    if (currentProject && /\btrust_level\s*=\s*"trusted"/.test(line)) {
+      currentTrusted = true;
+    }
+  }
+
+  return matchesTrustedProject();
+}
+
 /** Register the typegraph MCP server in agent-specific config files */
 function registerMcpServers(projectRoot: string, selectedAgents: AgentId[]): void {
   if (selectedAgents.includes("cursor")) {
@@ -274,104 +355,41 @@ function deregisterJsonMcp(projectRoot: string, configPath: string, rootKey: str
 
 /** Register MCP server in Codex CLI's TOML config */
 function registerCodexMcp(projectRoot: string): void {
-  const absoluteEntry = getAbsoluteMcpServerEntry(projectRoot);
-
-  const codexGet = spawnSync("codex", ["mcp", "get", "typegraph"], {
-    stdio: "pipe",
-    encoding: "utf-8",
-  });
-
-  if (codexGet.status === 0) {
-    const output = `${codexGet.stdout ?? ""}${codexGet.stderr ?? ""}`;
-    const hasServerPath = output.includes(absoluteEntry.args[1]!);
-    const hasProjectRoot = output.includes("TYPEGRAPH_PROJECT_ROOT=*****") || output.includes(projectRoot);
-    const hasTsconfig = output.includes("TYPEGRAPH_TSCONFIG=*****") || output.includes(path.resolve(projectRoot, "tsconfig.json"));
-    if (hasServerPath && hasProjectRoot && hasTsconfig) {
-      p.log.info("Codex CLI: typegraph MCP server already registered");
-      return;
-    }
-    spawnSync("codex", ["mcp", "remove", "typegraph"], {
-      stdio: "pipe",
-      encoding: "utf-8",
-    });
-  }
-
-  const codexAdd = spawnSync(
-    "codex",
-    [
-      "mcp",
-      "add",
-      "typegraph",
-      "--env",
-      `TYPEGRAPH_PROJECT_ROOT=${absoluteEntry.env.TYPEGRAPH_PROJECT_ROOT}`,
-      "--env",
-      `TYPEGRAPH_TSCONFIG=${absoluteEntry.env.TYPEGRAPH_TSCONFIG}`,
-      "--",
-      absoluteEntry.command,
-      ...absoluteEntry.args,
-    ],
-    {
-      stdio: "pipe",
-      encoding: "utf-8",
-    }
-  );
-
-  if (codexAdd.status === 0) {
-    p.log.success("Codex CLI: registered typegraph MCP server");
-    return;
-  }
-
-  p.log.warn(
-    `Codex CLI registration failed — falling back to ${".codex/config.toml"}`
-  );
-
   const configPath = ".codex/config.toml";
-  const fullPath = path.resolve(projectRoot, configPath);
+  const fullPath = getCodexConfigPath(projectRoot);
+  const block = makeCodexMcpBlock(projectRoot);
   let content = "";
 
   if (fs.existsSync(fullPath)) {
     content = fs.readFileSync(fullPath, "utf-8");
-    // Already registered?
-    if (content.includes("[mcp_servers.typegraph]")) {
-      p.log.info(`${configPath}: typegraph MCP server already registered`);
-      return;
-    }
   }
 
-  const block = [
-    "",
-    "[mcp_servers.typegraph]",
-    `command = "${absoluteEntry.command}"`,
-    `args = ["${absoluteEntry.args[0]}", "${absoluteEntry.args[1]}"]`,
-    `env = { TYPEGRAPH_PROJECT_ROOT = "${absoluteEntry.env.TYPEGRAPH_PROJECT_ROOT}", TYPEGRAPH_TSCONFIG = "${absoluteEntry.env.TYPEGRAPH_TSCONFIG}" }`,
-    "",
-  ].join("\n");
-
   const dir = path.dirname(fullPath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
-  const newContent = content ? content.trimEnd() + "\n" + block : block.trimStart();
-  fs.writeFileSync(fullPath, newContent);
-  p.log.success(`${configPath}: registered typegraph MCP server`);
+
+  const { content: nextContent, changed } = upsertCodexMcpSection(content, block);
+  if (changed) {
+    fs.writeFileSync(fullPath, nextContent);
+    p.log.success(`${configPath}: registered typegraph MCP server`);
+  } else {
+    p.log.info(`${configPath}: typegraph MCP server already registered`);
+  }
+
+  if (!isCodexProjectTrusted(projectRoot)) {
+    p.log.info(`Codex CLI: trust ${projectRoot} in ~/.codex/config.toml to load project MCP settings`);
+  }
 }
 
 /** Deregister MCP server from Codex CLI's TOML config */
 function deregisterCodexMcp(projectRoot: string): void {
-  const codexRemove = spawnSync("codex", ["mcp", "remove", "typegraph"], {
-    stdio: "pipe",
-    encoding: "utf-8",
-  });
-  if (codexRemove.status === 0) {
-    p.log.info("Codex CLI: removed typegraph MCP server");
-  }
-
   const configPath = ".codex/config.toml";
-  const fullPath = path.resolve(projectRoot, configPath);
+  const fullPath = getCodexConfigPath(projectRoot);
   if (!fs.existsSync(fullPath)) return;
 
   let content = fs.readFileSync(fullPath, "utf-8");
-  if (!content.includes("[mcp_servers.typegraph]")) return;
+  if (!hasCodexMcpSection(content)) return;
 
   // Remove the [mcp_servers.typegraph] section (stops at next section header or end of file)
   content = content.replace(
@@ -643,12 +661,12 @@ async function setup(yes: boolean): Promise<void> {
 
   s.message("Installing dependencies...");
   try {
-    execSync("npm install", { cwd: targetDir, stdio: "pipe" });
+    execSync("npm install --include=optional", { cwd: targetDir, stdio: "pipe" });
     s.stop(`${isUpdate ? "Updated" : "Installed"} ${copied} files with dependencies`);
   } catch (err) {
     s.stop(`${isUpdate ? "Updated" : "Installed"} ${copied} files`);
     p.log.warn(`Dependency install failed: ${err instanceof Error ? err.message : String(err)}`);
-    p.log.info(`Run manually: cd ${PLUGIN_DIR_NAME} && npm install`);
+    p.log.info(`Run manually: cd ${PLUGIN_DIR_NAME} && npm install --include=optional`);
   }
 
   // 4. Copy skills to .agents/skills/ for cross-platform discovery

package/dist/check.js

@@ -432,11 +432,84 @@ function testTsserver(projectRoot) {
     child.stdin.write(request + "\n");
   });
 }
+function readProjectCodexConfig(projectRoot) {
+  const configPath = path3.resolve(projectRoot, ".codex/config.toml");
+  if (!fs2.existsSync(configPath)) return null;
+  return fs2.readFileSync(configPath, "utf-8");
+}
+function hasCodexTypegraphRegistration(content) {
+  return /\[mcp_servers\.typegraph\]/.test(content);
+}
+function hasCompleteCodexTypegraphRegistration(content) {
+  return hasCodexTypegraphRegistration(content) && /command\s*=\s*"[^"]+"/.test(content) && /args\s*=\s*\[[\s\S]*"tsx"/.test(content) && /TYPEGRAPH_PROJECT_ROOT\s*=/.test(content) && /TYPEGRAPH_TSCONFIG\s*=/.test(content);
+}
+function hasTrustedCodexProject(projectRoot) {
+  const home = process.env.HOME;
+  if (!home) return null;
+  const globalConfigPath = path3.join(home, ".codex/config.toml");
+  if (!fs2.existsSync(globalConfigPath)) return null;
+  const lines = fs2.readFileSync(globalConfigPath, "utf-8").split(/\r?\n/);
+  let currentProject = null;
+  let currentTrusted = false;
+  const matchesTrustedProject = () => currentProject !== null && currentTrusted && (projectRoot === currentProject || projectRoot.startsWith(currentProject + path3.sep));
+  for (const line of lines) {
+    const sectionMatch = line.match(/^\[projects\."([^"]+)"\]\s*$/);
+    if (sectionMatch) {
+      if (matchesTrustedProject()) return true;
+      currentProject = path3.resolve(sectionMatch[1]);
+      currentTrusted = false;
+      continue;
+    }
+    if (line.startsWith("[")) {
+      if (matchesTrustedProject()) return true;
+      currentProject = null;
+      currentTrusted = false;
+      continue;
+    }
+    if (currentProject && /\btrust_level\s*=\s*"trusted"/.test(line)) {
+      currentTrusted = true;
+    }
+  }
+  return matchesTrustedProject();
+}
+function readProjectPackageJson(projectRoot) {
+  const packageJsonPath = path3.resolve(projectRoot, "package.json");
+  if (!fs2.existsSync(packageJsonPath)) return null;
+  try {
+    return JSON.parse(fs2.readFileSync(packageJsonPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function getProjectInstallCommand(projectRoot, packageJson) {
+  const packageManager = typeof packageJson?.["packageManager"] === "string" ? packageJson["packageManager"] : "";
+  if (packageManager.startsWith("pnpm@") || fs2.existsSync(path3.join(projectRoot, "pnpm-lock.yaml"))) {
+    return "pnpm install";
+  }
+  if (packageManager.startsWith("yarn@") || fs2.existsSync(path3.join(projectRoot, "yarn.lock"))) {
+    return "yarn install";
+  }
+  return "npm install";
+}
+function hasDeclaredDependency(packageJson, packageName) {
+  const depKeys = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies"
+  ];
+  return depKeys.some((key) => {
+    const deps = packageJson?.[key];
+    return typeof deps === "object" && deps !== null && packageName in deps;
+  });
+}
 async function main(configOverride) {
   const { projectRoot, tsconfigPath, toolDir, toolIsEmbedded, toolRelPath } = configOverride ?? resolveConfig(import.meta.dirname);
   let passed = 0;
   let failed = 0;
   let warned = 0;
+  const projectPackageJson = readProjectPackageJson(projectRoot);
+  const installCommand = getProjectInstallCommand(projectRoot, projectPackageJson);
   function pass(msg) {
     console.log(`  \u2713 ${msg}`);
     passed++;
@@ -461,10 +534,10 @@ async function main(configOverride) {
   console.log("");
   const nodeVersion = process.version;
   const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0], 10);
-  if (nodeMajor >= 18) {
-    pass(`Node.js ${nodeVersion} (>= 18 required)`);
+  if (nodeMajor >= 22) {
+    pass(`Node.js ${nodeVersion} (>= 22 required)`);
   } else {
-    fail(`Node.js ${nodeVersion} is too old`, "Upgrade Node.js to >= 18");
+    fail(`Node.js ${nodeVersion} is too old`, "Upgrade Node.js to >= 22");
   }
   const tsxInRoot = fs2.existsSync(path3.join(projectRoot, "node_modules/.bin/tsx"));
   const tsxInTool = fs2.existsSync(path3.join(toolDir, "node_modules/.bin/tsx"));
@@ -482,9 +555,10 @@ async function main(configOverride) {
     tsVersion = tsPkg.version;
     pass(`TypeScript found (v${tsVersion})`);
   } catch {
+    const hasDeclaredTs = hasDeclaredDependency(projectPackageJson, "typescript");
     fail(
-      "TypeScript not found in project",
-      "Add `typescript` to devDependencies and run `npm install`"
+      hasDeclaredTs ? "TypeScript is declared but not installed in project" : "TypeScript not found in project",
+      hasDeclaredTs ? `Run \`${installCommand}\` to install project dependencies` : `Add \`typescript\` to devDependencies and run \`${installCommand}\``
     );
   }
   const tsconfigAbs = path3.resolve(projectRoot, tsconfigPath);
@@ -495,18 +569,49 @@ async function main(configOverride) {
   }
   const pluginMcpPath = path3.join(toolDir, ".mcp.json");
   const hasPluginMcp = fs2.existsSync(pluginMcpPath) && fs2.existsSync(path3.join(toolDir, ".claude-plugin/plugin.json"));
+  const projectCodexConfig = readProjectCodexConfig(projectRoot);
+  const hasProjectCodexRegistration = projectCodexConfig !== null && hasCompleteCodexTypegraphRegistration(projectCodexConfig);
   const codexGet = spawnSync("codex", ["mcp", "get", "typegraph"], {
     stdio: "pipe",
     encoding: "utf-8"
   });
-  const hasCodexRegistration = codexGet.status === 0;
+  const hasGlobalCodexRegistration = codexGet.status === 0;
   if (process.env.CLAUDE_PLUGIN_ROOT) {
     pass("MCP registered via plugin (CLAUDE_PLUGIN_ROOT set)");
   } else if (hasPluginMcp) {
     pass("MCP registered via plugin (.mcp.json + .claude-plugin/ present)");
-  } else if (hasCodexRegistration) {
-    pass("MCP registered in Codex CLI");
+  } else if (projectCodexConfig !== null) {
+    const codexConfigPath = path3.resolve(projectRoot, ".codex/config.toml");
+    const hasSection = hasCodexTypegraphRegistration(projectCodexConfig);
+    const hasCommand = /command\s*=\s*"[^"]+"/.test(projectCodexConfig);
+    const hasArgs = /args\s*=\s*\[[\s\S]*"tsx"/.test(projectCodexConfig);
+    const hasEnvRoot = /TYPEGRAPH_PROJECT_ROOT\s*=/.test(projectCodexConfig);
+    const hasEnvTsconfig = /TYPEGRAPH_TSCONFIG\s*=/.test(projectCodexConfig);
+    if (hasProjectCodexRegistration) {
+      pass("MCP registered in project .codex/config.toml");
+      const trusted = hasTrustedCodexProject(projectRoot);
+      if (trusted === false) {
+        warn(
+          "Project Codex config may be ignored",
+          'Add the project (or a parent directory) to ~/.codex/config.toml with trust_level = "trusted"'
+        );
+      }
+    } else {
+      const issues = [];
+      if (!hasSection) issues.push("[mcp_servers.typegraph] section is missing");
+      if (!hasCommand) issues.push("command is missing");
+      if (!hasArgs) issues.push("args should include 'tsx'");
+      if (!hasEnvRoot) issues.push("TYPEGRAPH_PROJECT_ROOT is missing");
+      if (!hasEnvTsconfig) issues.push("TYPEGRAPH_TSCONFIG is missing");
+      fail(
+        `Project .codex/config.toml registration incomplete: ${issues.join(", ")}`,
+        `Update ${codexConfigPath} with a complete [mcp_servers.typegraph] entry`
+      );
+    }
+  } else if (hasGlobalCodexRegistration) {
+    pass("MCP registered in global Codex CLI config");
   } else {
+    const codexConfigPath = path3.resolve(projectRoot, ".codex/config.toml");
     const mcpJsonPath = path3.resolve(projectRoot, ".claude/mcp.json");
     if (fs2.existsSync(mcpJsonPath)) {
       try {
@@ -551,7 +656,10 @@ async function main(configOverride) {
         );
       }
     } else {
-      fail(".claude/mcp.json not found", `Create .claude/mcp.json with typegraph server registration`);
+      fail(
+        "No MCP registration found",
+        `Create ${codexConfigPath} with [mcp_servers.typegraph] or create .claude/mcp.json with typegraph server registration`
+      );
     }
   }
   const toolNodeModules = path3.join(toolDir, "node_modules");

package/dist/cli.js

@@ -439,11 +439,84 @@ function testTsserver(projectRoot3) {
     child.stdin.write(request + "\n");
   });
 }
+function readProjectCodexConfig(projectRoot3) {
+  const configPath = path3.resolve(projectRoot3, ".codex/config.toml");
+  if (!fs2.existsSync(configPath)) return null;
+  return fs2.readFileSync(configPath, "utf-8");
+}
+function hasCodexTypegraphRegistration(content) {
+  return /\[mcp_servers\.typegraph\]/.test(content);
+}
+function hasCompleteCodexTypegraphRegistration(content) {
+  return hasCodexTypegraphRegistration(content) && /command\s*=\s*"[^"]+"/.test(content) && /args\s*=\s*\[[\s\S]*"tsx"/.test(content) && /TYPEGRAPH_PROJECT_ROOT\s*=/.test(content) && /TYPEGRAPH_TSCONFIG\s*=/.test(content);
+}
+function hasTrustedCodexProject(projectRoot3) {
+  const home = process.env.HOME;
+  if (!home) return null;
+  const globalConfigPath = path3.join(home, ".codex/config.toml");
+  if (!fs2.existsSync(globalConfigPath)) return null;
+  const lines = fs2.readFileSync(globalConfigPath, "utf-8").split(/\r?\n/);
+  let currentProject = null;
+  let currentTrusted = false;
+  const matchesTrustedProject = () => currentProject !== null && currentTrusted && (projectRoot3 === currentProject || projectRoot3.startsWith(currentProject + path3.sep));
+  for (const line of lines) {
+    const sectionMatch = line.match(/^\[projects\."([^"]+)"\]\s*$/);
+    if (sectionMatch) {
+      if (matchesTrustedProject()) return true;
+      currentProject = path3.resolve(sectionMatch[1]);
+      currentTrusted = false;
+      continue;
+    }
+    if (line.startsWith("[")) {
+      if (matchesTrustedProject()) return true;
+      currentProject = null;
+      currentTrusted = false;
+      continue;
+    }
+    if (currentProject && /\btrust_level\s*=\s*"trusted"/.test(line)) {
+      currentTrusted = true;
+    }
+  }
+  return matchesTrustedProject();
+}
+function readProjectPackageJson(projectRoot3) {
+  const packageJsonPath = path3.resolve(projectRoot3, "package.json");
+  if (!fs2.existsSync(packageJsonPath)) return null;
+  try {
+    return JSON.parse(fs2.readFileSync(packageJsonPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function getProjectInstallCommand(projectRoot3, packageJson) {
+  const packageManager = typeof packageJson?.["packageManager"] === "string" ? packageJson["packageManager"] : "";
+  if (packageManager.startsWith("pnpm@") || fs2.existsSync(path3.join(projectRoot3, "pnpm-lock.yaml"))) {
+    return "pnpm install";
+  }
+  if (packageManager.startsWith("yarn@") || fs2.existsSync(path3.join(projectRoot3, "yarn.lock"))) {
+    return "yarn install";
+  }
+  return "npm install";
+}
+function hasDeclaredDependency(packageJson, packageName) {
+  const depKeys = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies"
+  ];
+  return depKeys.some((key) => {
+    const deps = packageJson?.[key];
+    return typeof deps === "object" && deps !== null && packageName in deps;
+  });
+}
 async function main(configOverride) {
   const { projectRoot: projectRoot3, tsconfigPath: tsconfigPath3, toolDir, toolIsEmbedded, toolRelPath } = configOverride ?? resolveConfig(import.meta.dirname);
   let passed = 0;
   let failed = 0;
   let warned = 0;
+  const projectPackageJson = readProjectPackageJson(projectRoot3);
+  const installCommand = getProjectInstallCommand(projectRoot3, projectPackageJson);
   function pass(msg) {
     console.log(`  \u2713 ${msg}`);
     passed++;
@@ -468,10 +541,10 @@ async function main(configOverride) {
   console.log("");
   const nodeVersion = process.version;
   const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0], 10);
-  if (nodeMajor >= 18) {
-    pass(`Node.js ${nodeVersion} (>= 18 required)`);
+  if (nodeMajor >= 22) {
+    pass(`Node.js ${nodeVersion} (>= 22 required)`);
   } else {
-    fail(`Node.js ${nodeVersion} is too old`, "Upgrade Node.js to >= 18");
+    fail(`Node.js ${nodeVersion} is too old`, "Upgrade Node.js to >= 22");
   }
   const tsxInRoot = fs2.existsSync(path3.join(projectRoot3, "node_modules/.bin/tsx"));
   const tsxInTool = fs2.existsSync(path3.join(toolDir, "node_modules/.bin/tsx"));
@@ -489,9 +562,10 @@ async function main(configOverride) {
     tsVersion = tsPkg.version;
     pass(`TypeScript found (v${tsVersion})`);
   } catch {
+    const hasDeclaredTs = hasDeclaredDependency(projectPackageJson, "typescript");
     fail(
-      "TypeScript not found in project",
-      "Add `typescript` to devDependencies and run `npm install`"
+      hasDeclaredTs ? "TypeScript is declared but not installed in project" : "TypeScript not found in project",
+      hasDeclaredTs ? `Run \`${installCommand}\` to install project dependencies` : `Add \`typescript\` to devDependencies and run \`${installCommand}\``
     );
   }
   const tsconfigAbs = path3.resolve(projectRoot3, tsconfigPath3);
@@ -502,18 +576,49 @@ async function main(configOverride) {
   }
   const pluginMcpPath = path3.join(toolDir, ".mcp.json");
   const hasPluginMcp = fs2.existsSync(pluginMcpPath) && fs2.existsSync(path3.join(toolDir, ".claude-plugin/plugin.json"));
+  const projectCodexConfig = readProjectCodexConfig(projectRoot3);
+  const hasProjectCodexRegistration = projectCodexConfig !== null && hasCompleteCodexTypegraphRegistration(projectCodexConfig);
   const codexGet = spawnSync("codex", ["mcp", "get", "typegraph"], {
     stdio: "pipe",
     encoding: "utf-8"
   });
-  const hasCodexRegistration = codexGet.status === 0;
+  const hasGlobalCodexRegistration = codexGet.status === 0;
   if (process.env.CLAUDE_PLUGIN_ROOT) {
     pass("MCP registered via plugin (CLAUDE_PLUGIN_ROOT set)");
   } else if (hasPluginMcp) {
     pass("MCP registered via plugin (.mcp.json + .claude-plugin/ present)");
-  } else if (hasCodexRegistration) {
-    pass("MCP registered in Codex CLI");
+  } else if (projectCodexConfig !== null) {
+    const codexConfigPath = path3.resolve(projectRoot3, ".codex/config.toml");
+    const hasSection = hasCodexTypegraphRegistration(projectCodexConfig);
+    const hasCommand = /command\s*=\s*"[^"]+"/.test(projectCodexConfig);
+    const hasArgs = /args\s*=\s*\[[\s\S]*"tsx"/.test(projectCodexConfig);
+    const hasEnvRoot = /TYPEGRAPH_PROJECT_ROOT\s*=/.test(projectCodexConfig);
+    const hasEnvTsconfig = /TYPEGRAPH_TSCONFIG\s*=/.test(projectCodexConfig);
+    if (hasProjectCodexRegistration) {
+      pass("MCP registered in project .codex/config.toml");
+      const trusted = hasTrustedCodexProject(projectRoot3);
+      if (trusted === false) {
+        warn(
+          "Project Codex config may be ignored",
+          'Add the project (or a parent directory) to ~/.codex/config.toml with trust_level = "trusted"'
+        );
+      }
+    } else {
+      const issues = [];
+      if (!hasSection) issues.push("[mcp_servers.typegraph] section is missing");
+      if (!hasCommand) issues.push("command is missing");
+      if (!hasArgs) issues.push("args should include 'tsx'");
+      if (!hasEnvRoot) issues.push("TYPEGRAPH_PROJECT_ROOT is missing");
+      if (!hasEnvTsconfig) issues.push("TYPEGRAPH_TSCONFIG is missing");
+      fail(
+        `Project .codex/config.toml registration incomplete: ${issues.join(", ")}`,
+        `Update ${codexConfigPath} with a complete [mcp_servers.typegraph] entry`
+      );
+    }
+  } else if (hasGlobalCodexRegistration) {
+    pass("MCP registered in global Codex CLI config");
   } else {
+    const codexConfigPath = path3.resolve(projectRoot3, ".codex/config.toml");
     const mcpJsonPath = path3.resolve(projectRoot3, ".claude/mcp.json");
     if (fs2.existsSync(mcpJsonPath)) {
       try {
@@ -558,7 +663,10 @@ async function main(configOverride) {
         );
       }
     } else {
-      fail(".claude/mcp.json not found", `Create .claude/mcp.json with typegraph server registration`);
+      fail(
+        "No MCP registration found",
+        `Create ${codexConfigPath} with [mcp_servers.typegraph] or create .claude/mcp.json with typegraph server registration`
+      );
     }
   }
   const toolNodeModules = path3.join(toolDir, "node_modules");
@@ -2802,7 +2910,7 @@ var init_server = __esm({
 init_config();
 import * as fs8 from "fs";
 import * as path9 from "path";
-import { execSync as execSync2, spawnSync as spawnSync2 } from "child_process";
+import { execSync as execSync2 } from "child_process";
 import * as p from "@clack/prompts";
 var AGENT_SNIPPET = `
 ## TypeScript Navigation (typegraph-mcp)
@@ -2932,6 +3040,69 @@ function getAbsoluteMcpServerEntry(projectRoot3) {
     }
   };
 }
+function getCodexConfigPath(projectRoot3) {
+  return path9.resolve(projectRoot3, ".codex/config.toml");
+}
+function hasCodexMcpSection(content) {
+  return content.includes("[mcp_servers.typegraph]");
+}
+function upsertCodexMcpSection(content, block) {
+  const sectionRe = /\n?\[mcp_servers\.typegraph\]\n[\s\S]*?(?=\n\[|$)/;
+  const normalizedBlock = block.trim();
+  if (sectionRe.test(content)) {
+    const existingSection = (content.match(sectionRe)?.[0] ?? "").trim();
+    if (existingSection === normalizedBlock) {
+      return { content, changed: false };
+    }
+    const nextContent2 = content.replace(sectionRe, `
+${normalizedBlock}
+`);
+    return { content: nextContent2.trimEnd() + "\n", changed: true };
+  }
+  const nextContent = content ? content.trimEnd() + "\n\n" + normalizedBlock + "\n" : normalizedBlock + "\n";
+  return { content: nextContent, changed: true };
+}
+function makeCodexMcpBlock(projectRoot3) {
+  const absoluteEntry = getAbsoluteMcpServerEntry(projectRoot3);
+  return [
+    "",
+    "[mcp_servers.typegraph]",
+    `command = "${absoluteEntry.command}"`,
+    `args = ["${absoluteEntry.args[0]}", "${absoluteEntry.args[1]}"]`,
+    `env = { TYPEGRAPH_PROJECT_ROOT = "${absoluteEntry.env.TYPEGRAPH_PROJECT_ROOT}", TYPEGRAPH_TSCONFIG = "${absoluteEntry.env.TYPEGRAPH_TSCONFIG}" }`,
+    ""
+  ].join("\n");
+}
+function isCodexProjectTrusted(projectRoot3) {
+  const home = process.env.HOME;
+  if (!home) return false;
+  const globalConfigPath = path9.join(home, ".codex/config.toml");
+  if (!fs8.existsSync(globalConfigPath)) return false;
+  const content = fs8.readFileSync(globalConfigPath, "utf-8");
+  const lines = content.split(/\r?\n/);
+  let currentProject = null;
+  let currentTrusted = false;
+  const matchesTrustedProject = () => currentProject !== null && currentTrusted && (projectRoot3 === currentProject || projectRoot3.startsWith(currentProject + path9.sep));
+  for (const line of lines) {
+    const sectionMatch = line.match(/^\[projects\."([^"]+)"\]\s*$/);
+    if (sectionMatch) {
+      if (matchesTrustedProject()) return true;
+      currentProject = path9.resolve(sectionMatch[1]);
+      currentTrusted = false;
+      continue;
+    }
+    if (line.startsWith("[")) {
+      if (matchesTrustedProject()) return true;
+      currentProject = null;
+      currentTrusted = false;
+      continue;
+    }
+    if (currentProject && /\btrust_level\s*=\s*"trusted"/.test(line)) {
+      currentTrusted = true;
+    }
+  }
+  return matchesTrustedProject();
+}
 function registerMcpServers(projectRoot3, selectedAgents) {
   if (selectedAgents.includes("cursor")) {
     registerJsonMcp(projectRoot3, ".cursor/mcp.json", "mcpServers");
@@ -2994,90 +3165,34 @@ function deregisterJsonMcp(projectRoot3, configPath, rootKey) {
   }
 }
 function registerCodexMcp(projectRoot3) {
-  const absoluteEntry = getAbsoluteMcpServerEntry(projectRoot3);
-  const codexGet = spawnSync2("codex", ["mcp", "get", "typegraph"], {
-    stdio: "pipe",
-    encoding: "utf-8"
-  });
-  if (codexGet.status === 0) {
-    const output = `${codexGet.stdout ?? ""}${codexGet.stderr ?? ""}`;
-    const hasServerPath = output.includes(absoluteEntry.args[1]);
-    const hasProjectRoot = output.includes("TYPEGRAPH_PROJECT_ROOT=*****") || output.includes(projectRoot3);
-    const hasTsconfig = output.includes("TYPEGRAPH_TSCONFIG=*****") || output.includes(path9.resolve(projectRoot3, "tsconfig.json"));
-    if (hasServerPath && hasProjectRoot && hasTsconfig) {
-      p.log.info("Codex CLI: typegraph MCP server already registered");
-      return;
-    }
-    spawnSync2("codex", ["mcp", "remove", "typegraph"], {
-      stdio: "pipe",
-      encoding: "utf-8"
-    });
-  }
-  const codexAdd = spawnSync2(
-    "codex",
-    [
-      "mcp",
-      "add",
-      "typegraph",
-      "--env",
-      `TYPEGRAPH_PROJECT_ROOT=${absoluteEntry.env.TYPEGRAPH_PROJECT_ROOT}`,
-      "--env",
-      `TYPEGRAPH_TSCONFIG=${absoluteEntry.env.TYPEGRAPH_TSCONFIG}`,
-      "--",
-      absoluteEntry.command,
-      ...absoluteEntry.args
-    ],
-    {
-      stdio: "pipe",
-      encoding: "utf-8"
-    }
-  );
-  if (codexAdd.status === 0) {
-    p.log.success("Codex CLI: registered typegraph MCP server");
-    return;
-  }
-  p.log.warn(
-    `Codex CLI registration failed \u2014 falling back to ${".codex/config.toml"}`
-  );
   const configPath = ".codex/config.toml";
-  const fullPath = path9.resolve(projectRoot3, configPath);
+  const fullPath = getCodexConfigPath(projectRoot3);
+  const block = makeCodexMcpBlock(projectRoot3);
   let content = "";
   if (fs8.existsSync(fullPath)) {
     content = fs8.readFileSync(fullPath, "utf-8");
-    if (content.includes("[mcp_servers.typegraph]")) {
-      p.log.info(`${configPath}: typegraph MCP server already registered`);
-      return;
-    }
   }
-  const block = [
-    "",
-    "[mcp_servers.typegraph]",
-    `command = "${absoluteEntry.command}"`,
-    `args = ["${absoluteEntry.args[0]}", "${absoluteEntry.args[1]}"]`,
-    `env = { TYPEGRAPH_PROJECT_ROOT = "${absoluteEntry.env.TYPEGRAPH_PROJECT_ROOT}", TYPEGRAPH_TSCONFIG = "${absoluteEntry.env.TYPEGRAPH_TSCONFIG}" }`,
-    ""
-  ].join("\n");
   const dir = path9.dirname(fullPath);
   if (!fs8.existsSync(dir)) {
     fs8.mkdirSync(dir, { recursive: true });
   }
-  const newContent = content ? content.trimEnd() + "\n" + block : block.trimStart();
-  fs8.writeFileSync(fullPath, newContent);
-  p.log.success(`${configPath}: registered typegraph MCP server`);
+  const { content: nextContent, changed } = upsertCodexMcpSection(content, block);
+  if (changed) {
+    fs8.writeFileSync(fullPath, nextContent);
+    p.log.success(`${configPath}: registered typegraph MCP server`);
+  } else {
+    p.log.info(`${configPath}: typegraph MCP server already registered`);
+  }
+  if (!isCodexProjectTrusted(projectRoot3)) {
+    p.log.info(`Codex CLI: trust ${projectRoot3} in ~/.codex/config.toml to load project MCP settings`);
+  }
 }
 function deregisterCodexMcp(projectRoot3) {
-  const codexRemove = spawnSync2("codex", ["mcp", "remove", "typegraph"], {
-    stdio: "pipe",
-    encoding: "utf-8"
-  });
-  if (codexRemove.status === 0) {
-    p.log.info("Codex CLI: removed typegraph MCP server");
-  }
   const configPath = ".codex/config.toml";
-  const fullPath = path9.resolve(projectRoot3, configPath);
+  const fullPath = getCodexConfigPath(projectRoot3);
   if (!fs8.existsSync(fullPath)) return;
   let content = fs8.readFileSync(fullPath, "utf-8");
-  if (!content.includes("[mcp_servers.typegraph]")) return;
+  if (!hasCodexMcpSection(content)) return;
   content = content.replace(
     /\n?\[mcp_servers\.typegraph\]\n[\s\S]*?(?=\n\[|$)/,
     ""
@@ -3279,12 +3394,12 @@ async function setup(yes2) {
   }
   s.message("Installing dependencies...");
   try {
-    execSync2("npm install", { cwd: targetDir, stdio: "pipe" });
+    execSync2("npm install --include=optional", { cwd: targetDir, stdio: "pipe" });
     s.stop(`${isUpdate ? "Updated" : "Installed"} ${copied} files with dependencies`);
   } catch (err) {
     s.stop(`${isUpdate ? "Updated" : "Installed"} ${copied} files`);
     p.log.warn(`Dependency install failed: ${err instanceof Error ? err.message : String(err)}`);
-    p.log.info(`Run manually: cd ${PLUGIN_DIR_NAME} && npm install`);
+    p.log.info(`Run manually: cd ${PLUGIN_DIR_NAME} && npm install --include=optional`);
   }
   if (needsAgentsSkills) {
     const agentsNames = selectedAgents.filter((id) => AGENTS[id].needsAgentsSkills).map((id) => AGENTS[id].name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typegraph-mcp",
-  "version": "0.9.31",
+  "version": "0.9.33",
   "description": "Type-aware codebase navigation for AI coding agents — 14 MCP tools powered by tsserver + oxc",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,10 @@
     "type": "git",
     "url": "https://github.com/guyowen/typegraph-mcp.git"
   },
+  "packageManager": "npm@11.5.2",
+  "engines": {
+    "node": ">=22"
+  },
   "bin": {
     "typegraph-mcp": "./dist/cli.js",
     "typegraph": "./dist/cli.js"

package/scripts/ensure-deps.sh

@@ -9,6 +9,14 @@ set -e
 
 PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
 
+if command -v node &> /dev/null; then
+  NODE_MAJOR="$(node -p 'process.versions.node.split(".")[0]')"
+  if [ "$NODE_MAJOR" -lt 22 ]; then
+    echo "Warning: typegraph-mcp requires Node.js >= 22. Current: $(node -v)"
+    exit 1
+  fi
+fi
+
 # Check if node_modules exist with required packages
 if [ -d "$PLUGIN_DIR/node_modules/@modelcontextprotocol" ] && \
    [ -d "$PLUGIN_DIR/node_modules/oxc-parser" ] && \
@@ -21,7 +29,7 @@ echo "Installing typegraph-mcp dependencies..."
 cd "$PLUGIN_DIR"
 
 if command -v npm &> /dev/null; then
-  npm install
+  npm install --include=optional
 else
   echo "Warning: npm not found. Run 'npm install' in $PLUGIN_DIR manually."
   exit 1