typegraph-mcp 0.9.33 → 0.9.35

package/README.md

@@ -128,9 +128,13 @@ typegraph-mcp <command> [options]
   bench    Run benchmarks (token, latency, accuracy)
   start    Start the MCP server (stdin/stdout)
 
-  --yes    Skip prompts     --help    Show help
+  --yes                 Skip prompts
+  --clean-global-codex  Also remove a stale global Codex MCP entry for this project
+  --help                Show help
 ```
 
+`remove` always cleans up project-local config. If it detects a legacy global `~/.codex/config.toml` entry that points at the current project, it will ask before removing it in interactive mode. In non-interactive mode, pass `--clean-global-codex` to allow that global cleanup.
+
 ## Troubleshooting
 
 Run the health check first — it catches most issues:
@@ -156,11 +160,13 @@ Add this to your project's `.codex/config.toml`:
 
 ```toml
 [mcp_servers.typegraph]
-command = "npx"
-args = ["tsx", "/absolute/path/to/your-project/plugins/typegraph-mcp/server.ts"]
+command = "/absolute/path/to/your-project/plugins/typegraph-mcp/node_modules/.bin/tsx"
+args = ["/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" }
 ```
 
+Using the plugin-local `tsx` binary avoids relying on `npx tsx` being resolvable when Codex launches the MCP server.
+
 Codex only loads project `.codex/config.toml` files for trusted projects. If needed, add this to `~/.codex/config.toml`:
 
 ```toml

package/check.ts

@@ -112,11 +112,19 @@ function hasCodexTypegraphRegistration(content: string): boolean {
   return /\[mcp_servers\.typegraph\]/.test(content);
 }
 
+function hasCodexTsxLauncher(content: string): boolean {
+  return (
+    /command\s*=\s*"[^"]*tsx(?:\.cmd)?"/.test(content) ||
+    /args\s*=\s*\[[\s\S]*"tsx"/.test(content)
+  );
+}
+
 function hasCompleteCodexTypegraphRegistration(content: string): boolean {
   return (
     hasCodexTypegraphRegistration(content) &&
     /command\s*=\s*"[^"]+"/.test(content) &&
-    /args\s*=\s*\[[\s\S]*"tsx"/.test(content) &&
+    /args\s*=\s*\[[\s\S]*\]/.test(content) &&
+    hasCodexTsxLauncher(content) &&
     /TYPEGRAPH_PROJECT_ROOT\s*=/.test(content) &&
     /TYPEGRAPH_TSCONFIG\s*=/.test(content)
   );
@@ -308,7 +316,8 @@ export async function main(configOverride?: TypegraphConfig): Promise<CheckResul
     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 hasArgs = /args\s*=\s*\[[\s\S]*\]/.test(projectCodexConfig);
+    const hasTsxLauncher = hasCodexTsxLauncher(projectCodexConfig);
     const hasEnvRoot = /TYPEGRAPH_PROJECT_ROOT\s*=/.test(projectCodexConfig);
     const hasEnvTsconfig = /TYPEGRAPH_TSCONFIG\s*=/.test(projectCodexConfig);
     if (hasProjectCodexRegistration) {
@@ -324,7 +333,8 @@ export async function main(configOverride?: TypegraphConfig): Promise<CheckResul
       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 (!hasArgs) issues.push("args are missing");
+      if (!hasTsxLauncher) issues.push("command should point to tsx or args should include 'tsx'");
       if (!hasEnvRoot) issues.push("TYPEGRAPH_PROJECT_ROOT is missing");
       if (!hasEnvTsconfig) issues.push("TYPEGRAPH_TSCONFIG is missing");
       fail(

package/cli.ts

@@ -10,6 +10,7 @@
  *
  * Options:
  *   --yes   Skip confirmation prompts (accept all defaults)
+ *   --clean-global-codex   Also remove a stale global Codex MCP entry for this project
  *   --help  Show help
  */
 
@@ -35,15 +36,35 @@ interface AgentDef {
   detect: (projectRoot: string) => boolean;
 }
 
+interface LegacyGlobalCodexCleanup {
+  globalConfigPath: string;
+  nextContent: string;
+}
+
 // ─── Constants ───────────────────────────────────────────────────────────────
 
 const AGENT_SNIPPET = `
 ## TypeScript Navigation (typegraph-mcp)
 
-Use the \`ts_*\` MCP tools instead of grep/glob for navigating TypeScript code. They resolve through barrel files, re-exports, and project references — returning precise results, not string matches.
+Where suitable, use the \`ts_*\` MCP tools instead of grep/glob for navigating TypeScript code. They resolve through barrel files, re-exports, and project references and return semantic results instead of string matches.
+
+- Point queries: \`ts_find_symbol\`, \`ts_definition\`, \`ts_references\`, \`ts_type_info\`, \`ts_navigate_to\`, \`ts_trace_chain\`, \`ts_blast_radius\`, \`ts_module_exports\`
+- Graph queries: \`ts_dependency_tree\`, \`ts_dependents\`, \`ts_import_cycles\`, \`ts_shortest_path\`, \`ts_subgraph\`, \`ts_module_boundary\`
+
+Start with the navigation tools before reading entire files. Use direct file reads only after the MCP tools identify the exact symbols or lines that matter.
+
+Use \`rg\` or \`grep\` when semantic symbol navigation is not the right tool, especially for:
+
+- docs, config, SQL, migrations, JSON, env vars, route strings, and other non-TypeScript assets
+- broad text discovery when you do not yet know the symbol name
+- exact string matching across the repo
+- validating wording or finding repeated plan/document references
+
+Practical rule:
 
-- **Point queries** (tsserver): \`ts_find_symbol\`, \`ts_definition\`, \`ts_references\`, \`ts_type_info\`, \`ts_navigate_to\`, \`ts_trace_chain\`, \`ts_blast_radius\`, \`ts_module_exports\`
-- **Graph queries** (import graph): \`ts_dependency_tree\`, \`ts_dependents\`, \`ts_import_cycles\`, \`ts_shortest_path\`, \`ts_subgraph\`, \`ts_module_boundary\`
+- use \`ts_*\` first for TypeScript symbol definition, references, types, and dependency analysis
+- use \`rg\`/\`grep\` for text search and non-TypeScript exploration
+- combine both when a task spans TypeScript code and surrounding docs/config
 `.trimStart();
 
 const SNIPPET_MARKER = "## TypeScript Navigation (typegraph-mcp)";
@@ -148,8 +169,9 @@ Commands:
   start    Start the MCP server (stdin/stdout)
 
 Options:
-  --yes   Skip confirmation prompts (accept all defaults)
-  --help  Show this help
+  --yes                 Skip confirmation prompts (accept all defaults)
+  --clean-global-codex  Also remove a stale global Codex MCP entry for this project
+  --help                Show this help
 `.trim();
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -192,12 +214,78 @@ function getAbsoluteMcpServerEntry(projectRoot: string): {
   };
 }
 
+function getCodexMcpServerEntry(projectRoot: string): {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+} {
+  return {
+    command: path.resolve(projectRoot, PLUGIN_DIR_NAME, "node_modules/.bin/tsx"),
+    args: [path.resolve(projectRoot, PLUGIN_DIR_NAME, "server.ts")],
+    env: {
+      TYPEGRAPH_PROJECT_ROOT: projectRoot,
+      TYPEGRAPH_TSCONFIG: path.resolve(projectRoot, "tsconfig.json"),
+    },
+  };
+}
+
 function getCodexConfigPath(projectRoot: string): string {
   return path.resolve(projectRoot, ".codex/config.toml");
 }
 
-function hasCodexMcpSection(content: string): boolean {
-  return content.includes("[mcp_servers.typegraph]");
+function isTomlSectionGroup(sectionName: string | null, prefix: string): boolean {
+  return sectionName === prefix || sectionName?.startsWith(`${prefix}.`) === true;
+}
+
+function splitTomlBlocks(content: string): Array<{ sectionName: string | null; raw: string }> {
+  const lines = content.split(/\r?\n/);
+  const blocks: Array<{ sectionName: string | null; raw: string }> = [];
+  let sectionName: string | null = null;
+  let currentLines: string[] = [];
+
+  for (const line of lines) {
+    const match = line.match(/^\[([^\]]+)\]\s*$/);
+    if (match) {
+      if (currentLines.length > 0 || sectionName !== null) {
+        blocks.push({ sectionName, raw: currentLines.join("\n") });
+      }
+      sectionName = match[1]!;
+      currentLines = [line];
+      continue;
+    }
+
+    currentLines.push(line);
+  }
+
+  if (currentLines.length > 0 || sectionName !== null) {
+    blocks.push({ sectionName, raw: currentLines.join("\n") });
+  }
+
+  return blocks;
+}
+
+function removeTomlSectionGroup(
+  content: string,
+  prefix: string
+): { content: string; removed: boolean; removedContent: string } {
+  const blocks = splitTomlBlocks(content);
+  const removedBlocks = blocks.filter((block) => isTomlSectionGroup(block.sectionName, prefix));
+  if (removedBlocks.length === 0) {
+    return { content, removed: false, removedContent: "" };
+  }
+
+  const keptBlocks = blocks.filter((block) => !isTomlSectionGroup(block.sectionName, prefix));
+  const nextContent = keptBlocks
+    .map((block) => block.raw)
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trimEnd();
+
+  return {
+    content: nextContent ? `${nextContent}\n` : "",
+    removed: true,
+    removedContent: removedBlocks.map((block) => block.raw).join("\n").trim(),
+  };
 }
 
 function upsertCodexMcpSection(content: string, block: string): { content: string; changed: boolean } {
@@ -221,12 +309,13 @@ function upsertCodexMcpSection(content: string, block: string): { content: strin
 }
 
 function makeCodexMcpBlock(projectRoot: string): string {
-  const absoluteEntry = getAbsoluteMcpServerEntry(projectRoot);
+  const absoluteEntry = getCodexMcpServerEntry(projectRoot);
+  const args = absoluteEntry.args.map((arg) => `"${arg}"`).join(", ");
   return [
     "",
     "[mcp_servers.typegraph]",
     `command = "${absoluteEntry.command}"`,
-    `args = ["${absoluteEntry.args[0]}", "${absoluteEntry.args[1]}"]`,
+    `args = [${args}]`,
     `env = { TYPEGRAPH_PROJECT_ROOT = "${absoluteEntry.env.TYPEGRAPH_PROJECT_ROOT}", TYPEGRAPH_TSCONFIG = "${absoluteEntry.env.TYPEGRAPH_TSCONFIG}" }`,
     "",
   ].join("\n");
@@ -273,6 +362,57 @@ function isCodexProjectTrusted(projectRoot: string): boolean {
   return matchesTrustedProject();
 }
 
+function pathEqualsOrContains(candidatePath: string, targetPath: string): boolean {
+  const resolvedCandidate = path.resolve(candidatePath);
+  const resolvedTarget = path.resolve(targetPath);
+  if (resolvedCandidate === resolvedTarget || resolvedCandidate.startsWith(`${resolvedTarget}${path.sep}`)) {
+    return true;
+  }
+
+  try {
+    const realCandidate = fs.realpathSync(candidatePath);
+    const realTarget = fs.realpathSync(targetPath);
+    return realCandidate === realTarget || realCandidate.startsWith(`${realTarget}${path.sep}`);
+  } catch {
+    return false;
+  }
+}
+
+function findLegacyGlobalCodexCleanup(projectRoot: string): LegacyGlobalCodexCleanup | 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 content = fs.readFileSync(globalConfigPath, "utf-8");
+  const { content: nextContent, removed, removedContent } = removeTomlSectionGroup(content, "mcp_servers.typegraph");
+  if (!removed) return null;
+
+  const pluginRoot = path.resolve(projectRoot, PLUGIN_DIR_NAME);
+  const quotedPaths = Array.from(removedContent.matchAll(/"([^"\n]+)"/g), (match) => match[1]!);
+  const looksProjectSpecific = quotedPaths.some((quotedPath) =>
+    pathEqualsOrContains(quotedPath, projectRoot) ||
+    pathEqualsOrContains(quotedPath, pluginRoot)
+  );
+
+  if (!looksProjectSpecific) {
+    return null;
+  }
+
+  return { globalConfigPath, nextContent };
+}
+
+function removeLegacyGlobalCodexMcp(cleanup: LegacyGlobalCodexCleanup): void {
+  if (cleanup.nextContent === "") {
+    fs.unlinkSync(cleanup.globalConfigPath);
+  } else {
+    fs.writeFileSync(cleanup.globalConfigPath, cleanup.nextContent);
+  }
+
+  p.log.info("~/.codex/config.toml: removed stale global typegraph MCP server entry for this project");
+}
+
 /** Register the typegraph MCP server in agent-specific config files */
 function registerMcpServers(projectRoot: string, selectedAgents: AgentId[]): void {
   if (selectedAgents.includes("cursor")) {
@@ -386,26 +526,19 @@ function registerCodexMcp(projectRoot: string): void {
 function deregisterCodexMcp(projectRoot: string): void {
   const configPath = ".codex/config.toml";
   const fullPath = getCodexConfigPath(projectRoot);
-  if (!fs.existsSync(fullPath)) return;
-
-  let content = fs.readFileSync(fullPath, "utf-8");
-  if (!hasCodexMcpSection(content)) return;
-
-  // Remove the [mcp_servers.typegraph] section (stops at next section header or end of file)
-  content = content.replace(
-    /\n?\[mcp_servers\.typegraph\]\n[\s\S]*?(?=\n\[|$)/,
-    ""
-  );
-
-  // Clean up multiple trailing newlines
-  content = content.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
-
-  if (content.trim() === "") {
-    fs.unlinkSync(fullPath);
-  } else {
-    fs.writeFileSync(fullPath, content);
+  if (fs.existsSync(fullPath)) {
+    const content = fs.readFileSync(fullPath, "utf-8");
+    const { content: nextContent, removed } = removeTomlSectionGroup(content, "mcp_servers.typegraph");
+
+    if (removed) {
+      if (nextContent === "") {
+        fs.unlinkSync(fullPath);
+      } else {
+        fs.writeFileSync(fullPath, nextContent);
+      }
+      p.log.info(`${configPath}: removed typegraph MCP server`);
+    }
   }
-  p.log.info(`${configPath}: removed typegraph MCP server`);
 }
 
 // ─── TSConfig Exclude ─────────────────────────────────────────────────────────
@@ -733,16 +866,26 @@ async function setup(yes: boolean): Promise<void> {
 
 // ─── Remove Command ──────────────────────────────────────────────────────────
 
-async function removePlugin(projectRoot: string, pluginDir: string): Promise<void> {
+async function removePlugin(
+  projectRoot: string,
+  pluginDir: string,
+  options: { removeGlobalCodex: boolean; legacyGlobalCodexCleanup: LegacyGlobalCodexCleanup | null }
+): Promise<void> {
   const s = p.spinner();
   s.start("Removing typegraph-mcp...");
 
-  // 1. Remove plugin directory
+  // 1. Deregister MCP server from agent config files while project paths still exist
+  deregisterMcpServers(projectRoot);
+  if (options.removeGlobalCodex && options.legacyGlobalCodexCleanup) {
+    removeLegacyGlobalCodexMcp(options.legacyGlobalCodexCleanup);
+  }
+
+  // 2. Remove plugin directory
   if (fs.existsSync(pluginDir)) {
     fs.rmSync(pluginDir, { recursive: true });
   }
 
-  // 2. Remove .agents/skills/ entries (only typegraph-mcp skills, not the whole dir)
+  // 3. Remove .agents/skills/ entries (only typegraph-mcp skills, not the whole dir)
   const agentsSkillsDir = path.resolve(projectRoot, ".agents/skills");
   for (const skill of SKILL_NAMES) {
     const skillDir = path.join(agentsSkillsDir, skill);
@@ -759,7 +902,7 @@ async function removePlugin(projectRoot: string, pluginDir: string): Promise<voi
     }
   }
 
-  // 3. Remove agent instruction snippet from all known agent files
+  // 4. Remove agent instruction snippet from all known agent files
   const allAgentFiles = AGENT_IDS
     .map((id) => AGENTS[id].agentFile)
     .filter((f): f is string => f !== null);
@@ -782,7 +925,7 @@ async function removePlugin(projectRoot: string, pluginDir: string): Promise<voi
     }
   }
 
-  // 4. Remove --plugin-dir ./plugins/typegraph-mcp from CLAUDE.md
+  // 5. Remove --plugin-dir ./plugins/typegraph-mcp from CLAUDE.md
   const claudeMdPath = path.resolve(projectRoot, "CLAUDE.md");
   if (fs.existsSync(claudeMdPath)) {
     let content = fs.readFileSync(claudeMdPath, "utf-8");
@@ -792,9 +935,6 @@ async function removePlugin(projectRoot: string, pluginDir: string): Promise<voi
 
   s.stop("Removed typegraph-mcp");
 
-  // 5. Deregister MCP server from agent config files
-  deregisterMcpServers(projectRoot);
-
   p.outro("typegraph-mcp has been uninstalled from this project.");
 }
 
@@ -808,39 +948,35 @@ async function setupAgentInstructions(projectRoot: string, selectedAgents: Agent
     return; // No agents with instruction files selected (e.g. Cursor only)
   }
 
-  // Find existing files, resolve symlinks to deduplicate
+  // Ensure each selected agent file exists and has the snippet once. Resolve
+  // symlinks to avoid writing duplicate content through multiple aliases.
   const seenRealPaths = new Map<string, string>(); // realPath -> first agentFile name
-  const existingFiles: { file: string; realPath: string; hasSnippet: boolean }[] = [];
   for (const agentFile of agentFiles) {
     const filePath = path.resolve(projectRoot, agentFile);
-    if (!fs.existsSync(filePath)) continue;
-    const realPath = fs.realpathSync(filePath);
+    if (!fs.existsSync(filePath)) {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, AGENT_SNIPPET + "\n");
+      p.log.success(`${agentFile}: created with typegraph-mcp instructions`);
+      continue;
+    }
 
+    const realPath = fs.realpathSync(filePath);
     const previousFile = seenRealPaths.get(realPath);
     if (previousFile) {
       p.log.info(`${agentFile}: same file as ${previousFile} (skipped)`);
       continue;
     }
-    seenRealPaths.set(realPath, agentFile);
-    const content = fs.readFileSync(filePath, "utf-8");
-    existingFiles.push({ file: agentFile, realPath, hasSnippet: content.includes(SNIPPET_MARKER) });
-  }
 
-  if (existingFiles.length === 0) {
-    p.log.warn(`No agent instruction files found (${agentFiles.join(", ")})`);
-    p.note(AGENT_SNIPPET, "Add this snippet to your agent instructions file");
-  } else if (existingFiles.some((f) => f.hasSnippet)) {
-    for (const f of existingFiles) {
-      if (f.hasSnippet) {
-        p.log.info(`${f.file}: already has typegraph-mcp instructions`);
-      }
+    seenRealPaths.set(realPath, agentFile);
+    const content = fs.readFileSync(realPath, "utf-8");
+    if (content.includes(SNIPPET_MARKER)) {
+      p.log.info(`${agentFile}: already has typegraph-mcp instructions`);
+      continue;
     }
-  } else {
-    const target = existingFiles[0]!;
-    const content = fs.readFileSync(target.realPath, "utf-8");
+
     const appendContent = (content.endsWith("\n") ? "" : "\n") + "\n" + AGENT_SNIPPET;
-    fs.appendFileSync(target.realPath, appendContent);
-    p.log.success(`${target.file}: appended typegraph-mcp instructions`);
+    fs.appendFileSync(realPath, appendContent);
+    p.log.success(`${agentFile}: appended typegraph-mcp instructions`);
   }
 
   // Update --plugin-dir line in CLAUDE.md if Claude Code is selected
@@ -902,6 +1038,7 @@ async function runVerification(pluginDir: string, selectedAgents: AgentId[]): Pr
 async function remove(yes: boolean): Promise<void> {
   const projectRoot = process.cwd();
   const pluginDir = path.resolve(projectRoot, PLUGIN_DIR_NAME);
+  const cleanGlobalCodex = args.includes("--clean-global-codex");
 
   process.stdout.write("\x1Bc");
   p.intro("TypeGraph MCP Remove");
@@ -919,7 +1056,33 @@ async function remove(yes: boolean): Promise<void> {
     }
   }
 
-  await removePlugin(projectRoot, pluginDir);
+  const legacyGlobalCodexCleanup = findLegacyGlobalCodexCleanup(projectRoot);
+  let removeGlobalCodex = cleanGlobalCodex;
+
+  if (legacyGlobalCodexCleanup && !cleanGlobalCodex && !yes) {
+    const shouldRemoveGlobal = await p.confirm({
+      message: "Also remove the stale global Codex MCP entry for this project from ~/.codex/config.toml?",
+      initialValue: false,
+    });
+    if (p.isCancel(shouldRemoveGlobal)) {
+      p.cancel("Removal cancelled.");
+      process.exit(0);
+    }
+    removeGlobalCodex = shouldRemoveGlobal;
+  }
+
+  await removePlugin(projectRoot, pluginDir, {
+    removeGlobalCodex,
+    legacyGlobalCodexCleanup,
+  });
+
+  if (legacyGlobalCodexCleanup && !removeGlobalCodex) {
+    p.log.warn(
+      "Left a stale global Codex MCP entry for this project in ~/.codex/config.toml. " +
+      "Codex may show MCP startup warnings or errors until you remove it. " +
+      "Re-run `typegraph-mcp remove --clean-global-codex` or remove the `typegraph` block manually."
+    );
+  }
 }
 
 // ─── Check Command ───────────────────────────────────────────────────────────

package/dist/check.js

@@ -440,8 +440,11 @@ function readProjectCodexConfig(projectRoot) {
 function hasCodexTypegraphRegistration(content) {
   return /\[mcp_servers\.typegraph\]/.test(content);
 }
+function hasCodexTsxLauncher(content) {
+  return /command\s*=\s*"[^"]*tsx(?:\.cmd)?"/.test(content) || /args\s*=\s*\[[\s\S]*"tsx"/.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);
+  return hasCodexTypegraphRegistration(content) && /command\s*=\s*"[^"]+"/.test(content) && /args\s*=\s*\[[\s\S]*\]/.test(content) && hasCodexTsxLauncher(content) && /TYPEGRAPH_PROJECT_ROOT\s*=/.test(content) && /TYPEGRAPH_TSCONFIG\s*=/.test(content);
 }
 function hasTrustedCodexProject(projectRoot) {
   const home = process.env.HOME;
@@ -584,7 +587,8 @@ async function main(configOverride) {
     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 hasArgs = /args\s*=\s*\[[\s\S]*\]/.test(projectCodexConfig);
+    const hasTsxLauncher = hasCodexTsxLauncher(projectCodexConfig);
     const hasEnvRoot = /TYPEGRAPH_PROJECT_ROOT\s*=/.test(projectCodexConfig);
     const hasEnvTsconfig = /TYPEGRAPH_TSCONFIG\s*=/.test(projectCodexConfig);
     if (hasProjectCodexRegistration) {
@@ -600,7 +604,8 @@ async function main(configOverride) {
       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 (!hasArgs) issues.push("args are missing");
+      if (!hasTsxLauncher) issues.push("command should point to tsx or args should include 'tsx'");
       if (!hasEnvRoot) issues.push("TYPEGRAPH_PROJECT_ROOT is missing");
       if (!hasEnvTsconfig) issues.push("TYPEGRAPH_TSCONFIG is missing");
       fail(

package/dist/cli.js

@@ -447,8 +447,11 @@ function readProjectCodexConfig(projectRoot3) {
 function hasCodexTypegraphRegistration(content) {
   return /\[mcp_servers\.typegraph\]/.test(content);
 }
+function hasCodexTsxLauncher(content) {
+  return /command\s*=\s*"[^"]*tsx(?:\.cmd)?"/.test(content) || /args\s*=\s*\[[\s\S]*"tsx"/.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);
+  return hasCodexTypegraphRegistration(content) && /command\s*=\s*"[^"]+"/.test(content) && /args\s*=\s*\[[\s\S]*\]/.test(content) && hasCodexTsxLauncher(content) && /TYPEGRAPH_PROJECT_ROOT\s*=/.test(content) && /TYPEGRAPH_TSCONFIG\s*=/.test(content);
 }
 function hasTrustedCodexProject(projectRoot3) {
   const home = process.env.HOME;
@@ -526,9 +529,9 @@ async function main(configOverride) {
     console.log(`    Fix: ${fix}`);
     failed++;
   }
-  function warn(msg, note2) {
+  function warn(msg, note) {
     console.log(`  ! ${msg}`);
-    console.log(`    ${note2}`);
+    console.log(`    ${note}`);
     warned++;
   }
   function skip(msg) {
@@ -591,7 +594,8 @@ async function main(configOverride) {
     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 hasArgs = /args\s*=\s*\[[\s\S]*\]/.test(projectCodexConfig);
+    const hasTsxLauncher = hasCodexTsxLauncher(projectCodexConfig);
     const hasEnvRoot = /TYPEGRAPH_PROJECT_ROOT\s*=/.test(projectCodexConfig);
     const hasEnvTsconfig = /TYPEGRAPH_TSCONFIG\s*=/.test(projectCodexConfig);
     if (hasProjectCodexRegistration) {
@@ -607,7 +611,8 @@ async function main(configOverride) {
       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 (!hasArgs) issues.push("args are missing");
+      if (!hasTsxLauncher) issues.push("command should point to tsx or args should include 'tsx'");
       if (!hasEnvRoot) issues.push("TYPEGRAPH_PROJECT_ROOT is missing");
       if (!hasEnvTsconfig) issues.push("TYPEGRAPH_TSCONFIG is missing");
       fail(
@@ -2915,10 +2920,25 @@ import * as p from "@clack/prompts";
 var AGENT_SNIPPET = `
 ## TypeScript Navigation (typegraph-mcp)
 
-Use the \`ts_*\` MCP tools instead of grep/glob for navigating TypeScript code. They resolve through barrel files, re-exports, and project references \u2014 returning precise results, not string matches.
+Where suitable, use the \`ts_*\` MCP tools instead of grep/glob for navigating TypeScript code. They resolve through barrel files, re-exports, and project references and return semantic results instead of string matches.
+
+- Point queries: \`ts_find_symbol\`, \`ts_definition\`, \`ts_references\`, \`ts_type_info\`, \`ts_navigate_to\`, \`ts_trace_chain\`, \`ts_blast_radius\`, \`ts_module_exports\`
+- Graph queries: \`ts_dependency_tree\`, \`ts_dependents\`, \`ts_import_cycles\`, \`ts_shortest_path\`, \`ts_subgraph\`, \`ts_module_boundary\`
+
+Start with the navigation tools before reading entire files. Use direct file reads only after the MCP tools identify the exact symbols or lines that matter.
+
+Use \`rg\` or \`grep\` when semantic symbol navigation is not the right tool, especially for:
 
-- **Point queries** (tsserver): \`ts_find_symbol\`, \`ts_definition\`, \`ts_references\`, \`ts_type_info\`, \`ts_navigate_to\`, \`ts_trace_chain\`, \`ts_blast_radius\`, \`ts_module_exports\`
-- **Graph queries** (import graph): \`ts_dependency_tree\`, \`ts_dependents\`, \`ts_import_cycles\`, \`ts_shortest_path\`, \`ts_subgraph\`, \`ts_module_boundary\`
+- docs, config, SQL, migrations, JSON, env vars, route strings, and other non-TypeScript assets
+- broad text discovery when you do not yet know the symbol name
+- exact string matching across the repo
+- validating wording or finding repeated plan/document references
+
+Practical rule:
+
+- use \`ts_*\` first for TypeScript symbol definition, references, types, and dependency analysis
+- use \`rg\`/\`grep\` for text search and non-TypeScript exploration
+- combine both when a task spans TypeScript code and surrounding docs/config
 `.trimStart();
 var SNIPPET_MARKER = "## TypeScript Navigation (typegraph-mcp)";
 var PLUGIN_DIR_NAME = "plugins/typegraph-mcp";
@@ -3009,8 +3029,9 @@ Commands:
   start    Start the MCP server (stdin/stdout)
 
 Options:
-  --yes   Skip confirmation prompts (accept all defaults)
-  --help  Show this help
+  --yes                 Skip confirmation prompts (accept all defaults)
+  --clean-global-codex  Also remove a stale global Codex MCP entry for this project
+  --help                Show this help
 `.trim();
 function copyFile(src, dest) {
   const destDir = path9.dirname(dest);
@@ -3030,10 +3051,10 @@ var MCP_SERVER_ENTRY = {
     TYPEGRAPH_TSCONFIG: "./tsconfig.json"
   }
 };
-function getAbsoluteMcpServerEntry(projectRoot3) {
+function getCodexMcpServerEntry(projectRoot3) {
   return {
-    command: "npx",
-    args: ["tsx", path9.resolve(projectRoot3, PLUGIN_DIR_NAME, "server.ts")],
+    command: path9.resolve(projectRoot3, PLUGIN_DIR_NAME, "node_modules/.bin/tsx"),
+    args: [path9.resolve(projectRoot3, PLUGIN_DIR_NAME, "server.ts")],
     env: {
       TYPEGRAPH_PROJECT_ROOT: projectRoot3,
       TYPEGRAPH_TSCONFIG: path9.resolve(projectRoot3, "tsconfig.json")
@@ -3043,8 +3064,45 @@ function getAbsoluteMcpServerEntry(projectRoot3) {
 function getCodexConfigPath(projectRoot3) {
   return path9.resolve(projectRoot3, ".codex/config.toml");
 }
-function hasCodexMcpSection(content) {
-  return content.includes("[mcp_servers.typegraph]");
+function isTomlSectionGroup(sectionName, prefix) {
+  return sectionName === prefix || sectionName?.startsWith(`${prefix}.`) === true;
+}
+function splitTomlBlocks(content) {
+  const lines = content.split(/\r?\n/);
+  const blocks = [];
+  let sectionName = null;
+  let currentLines = [];
+  for (const line of lines) {
+    const match = line.match(/^\[([^\]]+)\]\s*$/);
+    if (match) {
+      if (currentLines.length > 0 || sectionName !== null) {
+        blocks.push({ sectionName, raw: currentLines.join("\n") });
+      }
+      sectionName = match[1];
+      currentLines = [line];
+      continue;
+    }
+    currentLines.push(line);
+  }
+  if (currentLines.length > 0 || sectionName !== null) {
+    blocks.push({ sectionName, raw: currentLines.join("\n") });
+  }
+  return blocks;
+}
+function removeTomlSectionGroup(content, prefix) {
+  const blocks = splitTomlBlocks(content);
+  const removedBlocks = blocks.filter((block) => isTomlSectionGroup(block.sectionName, prefix));
+  if (removedBlocks.length === 0) {
+    return { content, removed: false, removedContent: "" };
+  }
+  const keptBlocks = blocks.filter((block) => !isTomlSectionGroup(block.sectionName, prefix));
+  const nextContent = keptBlocks.map((block) => block.raw).join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+  return {
+    content: nextContent ? `${nextContent}
+` : "",
+    removed: true,
+    removedContent: removedBlocks.map((block) => block.raw).join("\n").trim()
+  };
 }
 function upsertCodexMcpSection(content, block) {
   const sectionRe = /\n?\[mcp_servers\.typegraph\]\n[\s\S]*?(?=\n\[|$)/;
@@ -3063,12 +3121,13 @@ ${normalizedBlock}
   return { content: nextContent, changed: true };
 }
 function makeCodexMcpBlock(projectRoot3) {
-  const absoluteEntry = getAbsoluteMcpServerEntry(projectRoot3);
+  const absoluteEntry = getCodexMcpServerEntry(projectRoot3);
+  const args2 = absoluteEntry.args.map((arg) => `"${arg}"`).join(", ");
   return [
     "",
     "[mcp_servers.typegraph]",
     `command = "${absoluteEntry.command}"`,
-    `args = ["${absoluteEntry.args[0]}", "${absoluteEntry.args[1]}"]`,
+    `args = [${args2}]`,
     `env = { TYPEGRAPH_PROJECT_ROOT = "${absoluteEntry.env.TYPEGRAPH_PROJECT_ROOT}", TYPEGRAPH_TSCONFIG = "${absoluteEntry.env.TYPEGRAPH_TSCONFIG}" }`,
     ""
   ].join("\n");
@@ -3103,6 +3162,46 @@ function isCodexProjectTrusted(projectRoot3) {
   }
   return matchesTrustedProject();
 }
+function pathEqualsOrContains(candidatePath, targetPath) {
+  const resolvedCandidate = path9.resolve(candidatePath);
+  const resolvedTarget = path9.resolve(targetPath);
+  if (resolvedCandidate === resolvedTarget || resolvedCandidate.startsWith(`${resolvedTarget}${path9.sep}`)) {
+    return true;
+  }
+  try {
+    const realCandidate = fs8.realpathSync(candidatePath);
+    const realTarget = fs8.realpathSync(targetPath);
+    return realCandidate === realTarget || realCandidate.startsWith(`${realTarget}${path9.sep}`);
+  } catch {
+    return false;
+  }
+}
+function findLegacyGlobalCodexCleanup(projectRoot3) {
+  const home = process.env.HOME;
+  if (!home) return null;
+  const globalConfigPath = path9.join(home, ".codex/config.toml");
+  if (!fs8.existsSync(globalConfigPath)) return null;
+  const content = fs8.readFileSync(globalConfigPath, "utf-8");
+  const { content: nextContent, removed, removedContent } = removeTomlSectionGroup(content, "mcp_servers.typegraph");
+  if (!removed) return null;
+  const pluginRoot = path9.resolve(projectRoot3, PLUGIN_DIR_NAME);
+  const quotedPaths = Array.from(removedContent.matchAll(/"([^"\n]+)"/g), (match) => match[1]);
+  const looksProjectSpecific = quotedPaths.some(
+    (quotedPath) => pathEqualsOrContains(quotedPath, projectRoot3) || pathEqualsOrContains(quotedPath, pluginRoot)
+  );
+  if (!looksProjectSpecific) {
+    return null;
+  }
+  return { globalConfigPath, nextContent };
+}
+function removeLegacyGlobalCodexMcp(cleanup) {
+  if (cleanup.nextContent === "") {
+    fs8.unlinkSync(cleanup.globalConfigPath);
+  } else {
+    fs8.writeFileSync(cleanup.globalConfigPath, cleanup.nextContent);
+  }
+  p.log.info("~/.codex/config.toml: removed stale global typegraph MCP server entry for this project");
+}
 function registerMcpServers(projectRoot3, selectedAgents) {
   if (selectedAgents.includes("cursor")) {
     registerJsonMcp(projectRoot3, ".cursor/mcp.json", "mcpServers");
@@ -3190,20 +3289,18 @@ function registerCodexMcp(projectRoot3) {
 function deregisterCodexMcp(projectRoot3) {
   const configPath = ".codex/config.toml";
   const fullPath = getCodexConfigPath(projectRoot3);
-  if (!fs8.existsSync(fullPath)) return;
-  let content = fs8.readFileSync(fullPath, "utf-8");
-  if (!hasCodexMcpSection(content)) return;
-  content = content.replace(
-    /\n?\[mcp_servers\.typegraph\]\n[\s\S]*?(?=\n\[|$)/,
-    ""
-  );
-  content = content.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
-  if (content.trim() === "") {
-    fs8.unlinkSync(fullPath);
-  } else {
-    fs8.writeFileSync(fullPath, content);
+  if (fs8.existsSync(fullPath)) {
+    const content = fs8.readFileSync(fullPath, "utf-8");
+    const { content: nextContent, removed } = removeTomlSectionGroup(content, "mcp_servers.typegraph");
+    if (removed) {
+      if (nextContent === "") {
+        fs8.unlinkSync(fullPath);
+      } else {
+        fs8.writeFileSync(fullPath, nextContent);
+      }
+      p.log.info(`${configPath}: removed typegraph MCP server`);
+    }
   }
-  p.log.info(`${configPath}: removed typegraph MCP server`);
 }
 function ensureTsconfigExclude(projectRoot3) {
   const tsconfigPath3 = path9.resolve(projectRoot3, "tsconfig.json");
@@ -3445,9 +3542,13 @@ async function setup(yes2) {
   ensureEslintIgnore(projectRoot3);
   await runVerification(targetDir, selectedAgents);
 }
-async function removePlugin(projectRoot3, pluginDir) {
+async function removePlugin(projectRoot3, pluginDir, options) {
   const s = p.spinner();
   s.start("Removing typegraph-mcp...");
+  deregisterMcpServers(projectRoot3);
+  if (options.removeGlobalCodex && options.legacyGlobalCodexCleanup) {
+    removeLegacyGlobalCodexMcp(options.legacyGlobalCodexCleanup);
+  }
   if (fs8.existsSync(pluginDir)) {
     fs8.rmSync(pluginDir, { recursive: true });
   }
@@ -3487,7 +3588,6 @@ async function removePlugin(projectRoot3, pluginDir) {
     fs8.writeFileSync(claudeMdPath, content);
   }
   s.stop("Removed typegraph-mcp");
-  deregisterMcpServers(projectRoot3);
   p.outro("typegraph-mcp has been uninstalled from this project.");
 }
 async function setupAgentInstructions(projectRoot3, selectedAgents) {
@@ -3496,10 +3596,14 @@ async function setupAgentInstructions(projectRoot3, selectedAgents) {
     return;
   }
   const seenRealPaths = /* @__PURE__ */ new Map();
-  const existingFiles = [];
   for (const agentFile of agentFiles) {
     const filePath = path9.resolve(projectRoot3, agentFile);
-    if (!fs8.existsSync(filePath)) continue;
+    if (!fs8.existsSync(filePath)) {
+      fs8.mkdirSync(path9.dirname(filePath), { recursive: true });
+      fs8.writeFileSync(filePath, AGENT_SNIPPET + "\n");
+      p.log.success(`${agentFile}: created with typegraph-mcp instructions`);
+      continue;
+    }
     const realPath = fs8.realpathSync(filePath);
     const previousFile = seenRealPaths.get(realPath);
     if (previousFile) {
@@ -3507,24 +3611,14 @@ async function setupAgentInstructions(projectRoot3, selectedAgents) {
       continue;
     }
     seenRealPaths.set(realPath, agentFile);
-    const content = fs8.readFileSync(filePath, "utf-8");
-    existingFiles.push({ file: agentFile, realPath, hasSnippet: content.includes(SNIPPET_MARKER) });
-  }
-  if (existingFiles.length === 0) {
-    p.log.warn(`No agent instruction files found (${agentFiles.join(", ")})`);
-    p.note(AGENT_SNIPPET, "Add this snippet to your agent instructions file");
-  } else if (existingFiles.some((f) => f.hasSnippet)) {
-    for (const f of existingFiles) {
-      if (f.hasSnippet) {
-        p.log.info(`${f.file}: already has typegraph-mcp instructions`);
-      }
+    const content = fs8.readFileSync(realPath, "utf-8");
+    if (content.includes(SNIPPET_MARKER)) {
+      p.log.info(`${agentFile}: already has typegraph-mcp instructions`);
+      continue;
     }
-  } else {
-    const target = existingFiles[0];
-    const content = fs8.readFileSync(target.realPath, "utf-8");
     const appendContent = (content.endsWith("\n") ? "" : "\n") + "\n" + AGENT_SNIPPET;
-    fs8.appendFileSync(target.realPath, appendContent);
-    p.log.success(`${target.file}: appended typegraph-mcp instructions`);
+    fs8.appendFileSync(realPath, appendContent);
+    p.log.success(`${agentFile}: appended typegraph-mcp instructions`);
   }
   if (selectedAgents.includes("claude-code")) {
     const claudeMdPath = path9.resolve(projectRoot3, "CLAUDE.md");
@@ -3573,6 +3667,7 @@ async function runVerification(pluginDir, selectedAgents) {
 async function remove(yes2) {
   const projectRoot3 = process.cwd();
   const pluginDir = path9.resolve(projectRoot3, PLUGIN_DIR_NAME);
+  const cleanGlobalCodex = args.includes("--clean-global-codex");
   process.stdout.write("\x1Bc");
   p.intro("TypeGraph MCP Remove");
   if (!fs8.existsSync(pluginDir)) {
@@ -3586,7 +3681,28 @@ async function remove(yes2) {
       process.exit(0);
     }
   }
-  await removePlugin(projectRoot3, pluginDir);
+  const legacyGlobalCodexCleanup = findLegacyGlobalCodexCleanup(projectRoot3);
+  let removeGlobalCodex = cleanGlobalCodex;
+  if (legacyGlobalCodexCleanup && !cleanGlobalCodex && !yes2) {
+    const shouldRemoveGlobal = await p.confirm({
+      message: "Also remove the stale global Codex MCP entry for this project from ~/.codex/config.toml?",
+      initialValue: false
+    });
+    if (p.isCancel(shouldRemoveGlobal)) {
+      p.cancel("Removal cancelled.");
+      process.exit(0);
+    }
+    removeGlobalCodex = shouldRemoveGlobal;
+  }
+  await removePlugin(projectRoot3, pluginDir, {
+    removeGlobalCodex,
+    legacyGlobalCodexCleanup
+  });
+  if (legacyGlobalCodexCleanup && !removeGlobalCodex) {
+    p.log.warn(
+      "Left a stale global Codex MCP entry for this project in ~/.codex/config.toml. Codex may show MCP startup warnings or errors until you remove it. Re-run `typegraph-mcp remove --clean-global-codex` or remove the `typegraph` block manually."
+    );
+  }
 }
 function resolvePluginDir() {
   const installed = path9.resolve(process.cwd(), PLUGIN_DIR_NAME);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typegraph-mcp",
-  "version": "0.9.33",
+  "version": "0.9.35",
   "description": "Type-aware codebase navigation for AI coding agents — 14 MCP tools powered by tsserver + oxc",
   "license": "MIT",
   "type": "module",