typegraph-mcp 0.9.32 → 0.9.34

package/README.md

@@ -142,7 +142,7 @@ npx typegraph-mcp check
 | Symptom | Fix |
 |---|---|
 | Server won't start | `cd plugins/typegraph-mcp && npm install --include=optional` |
-| "TypeScript not found" | Add `typescript` to devDependencies |
+| "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` |

package/check.ts

@@ -162,6 +162,45 @@ function hasTrustedCodexProject(projectRoot: string): boolean | null {
   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> {
@@ -171,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}`);
@@ -228,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}\``
     );
   }
 

package/cli.ts

@@ -40,10 +40,25 @@ interface AgentDef {
 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** (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\`
+- 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:
+
+- 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)";
@@ -808,39 +823,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

package/dist/check.js

@@ -472,11 +472,44 @@ function hasTrustedCodexProject(projectRoot) {
   }
   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++;
@@ -522,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);

package/dist/cli.js

@@ -479,11 +479,44 @@ function hasTrustedCodexProject(projectRoot3) {
   }
   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++;
@@ -493,9 +526,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) {
@@ -529,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);
@@ -2881,10 +2915,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.
 
-- **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 \`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:
+
+- 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";
@@ -3462,10 +3511,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) {
@@ -3473,24 +3526,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");

package/package.json

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