typegraph-mcp 0.9.36 → 0.9.38

package/cli.ts

@@ -59,6 +59,8 @@ Where suitable, use the \`ts_*\` MCP tools instead of grep/glob for navigating T
 
 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.
 
+For quick architectural insight, prefer composition modules and entrypoints over top-level barrel files. If \`ts_module_exports\` on an \`index.ts\` or other barrel looks empty or uninformative, pivot to the app entrypoint, router, handler, service composition root, or API module that wires real behavior together.
+
 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
@@ -74,6 +76,7 @@ Practical rule:
 `.trimStart();
 
 const SNIPPET_MARKER = "## TypeScript Navigation (typegraph-mcp)";
+const CLAUDE_NODE_PLACEHOLDER = "__TYPEGRAPH_NODE__";
 
 const PLUGIN_DIR_NAME = "plugins/typegraph-mcp";
 
@@ -151,6 +154,14 @@ const SKILL_FILES = [
   "skills/deep-survey/SKILL.md",
 ];
 
+const CLAUDE_TEMPLATE_FILES = new Set([
+  "commands/check.md",
+  "commands/test.md",
+  "commands/bench.md",
+  "commands/deep-survey.md",
+  "skills/deep-survey/SKILL.md",
+]);
+
 
 const SKILL_NAMES = [
   "tool-selection",
@@ -810,7 +821,14 @@ async function setup(yes: boolean): Promise<void> {
     const src = path.join(sourceDir, file);
     const dest = path.join(targetDir, file);
     if (fs.existsSync(src)) {
-      copyFile(src, dest);
+      if (selectedAgents.includes("claude-code") && CLAUDE_TEMPLATE_FILES.has(file)) {
+        const content = fs.readFileSync(src, "utf-8")
+          .replaceAll(CLAUDE_NODE_PLACEHOLDER, process.execPath);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, content);
+      } else {
+        copyFile(src, dest);
+      }
       copied++;
     } else {
       p.log.warn(`Source file not found: ${file}`);
@@ -822,8 +840,8 @@ async function setup(yes: boolean): Promise<void> {
     const mcpConfig = {
       mcpServers: {
         typegraph: {
-          command: "npx",
-          args: ["tsx", "${CLAUDE_PLUGIN_ROOT}/server.ts"],
+          command: process.execPath,
+          args: ["${CLAUDE_PLUGIN_ROOT}/node_modules/tsx/dist/cli.mjs", "${CLAUDE_PLUGIN_ROOT}/server.ts"],
           env: {
             TYPEGRAPH_PROJECT_ROOT: ".",
             TYPEGRAPH_TSCONFIG: "./tsconfig.json",

package/commands/bench.md

@@ -12,7 +12,7 @@ Run benchmarks to measure typegraph-mcp performance on this project.
 1. Run the benchmark command:
 
    ```bash
-   npx tsx ${CLAUDE_PLUGIN_ROOT}/cli.ts bench
+   "__TYPEGRAPH_NODE__" "${CLAUDE_PLUGIN_ROOT}/node_modules/tsx/dist/cli.mjs" "${CLAUDE_PLUGIN_ROOT}/cli.ts" bench
    ```
 
 2. Parse the output and report results:

package/commands/check.md

@@ -12,7 +12,7 @@ Run health checks to verify typegraph-mcp is correctly set up for this project.
 1. Run the health check command:
 
    ```bash
-   npx tsx ${CLAUDE_PLUGIN_ROOT}/cli.ts check
+   "__TYPEGRAPH_NODE__" "${CLAUDE_PLUGIN_ROOT}/node_modules/tsx/dist/cli.mjs" "${CLAUDE_PLUGIN_ROOT}/cli.ts" check
    ```
 
 2. Parse the output and report results:

package/commands/deep-survey.md

@@ -23,7 +23,7 @@ Follow the phases below in order. Each phase produces findings.
 
 Run the health check first:
 ```bash
-npx tsx ${CLAUDE_PLUGIN_ROOT}/cli.ts check
+"__TYPEGRAPH_NODE__" "${CLAUDE_PLUGIN_ROOT}/node_modules/tsx/dist/cli.mjs" "${CLAUDE_PLUGIN_ROOT}/cli.ts" check
 ```
 
 Record three numbers from the output:

package/commands/test.md

@@ -12,7 +12,7 @@ Run smoke tests that exercise all 14 tools against the current project.
 1. Run the smoke test command:
 
    ```bash
-   npx tsx ${CLAUDE_PLUGIN_ROOT}/cli.ts test
+   "__TYPEGRAPH_NODE__" "${CLAUDE_PLUGIN_ROOT}/node_modules/tsx/dist/cli.mjs" "${CLAUDE_PLUGIN_ROOT}/cli.ts" test
    ```
 
 2. Parse the output and report results:

package/dist/cli.js

@@ -2927,6 +2927,8 @@ Where suitable, use the \`ts_*\` MCP tools instead of grep/glob for navigating T
 
 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.
 
+For quick architectural insight, prefer composition modules and entrypoints over top-level barrel files. If \`ts_module_exports\` on an \`index.ts\` or other barrel looks empty or uninformative, pivot to the app entrypoint, router, handler, service composition root, or API module that wires real behavior together.
+
 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
@@ -2941,6 +2943,7 @@ Practical rule:
 - combine both when a task spans TypeScript code and surrounding docs/config
 `.trimStart();
 var SNIPPET_MARKER = "## TypeScript Navigation (typegraph-mcp)";
+var CLAUDE_NODE_PLACEHOLDER = "__TYPEGRAPH_NODE__";
 var PLUGIN_DIR_NAME = "plugins/typegraph-mcp";
 var AGENT_IDS = ["claude-code", "cursor", "codex", "gemini", "copilot"];
 var AGENTS = {
@@ -3007,6 +3010,13 @@ var SKILL_FILES = [
   "skills/code-exploration/SKILL.md",
   "skills/deep-survey/SKILL.md"
 ];
+var CLAUDE_TEMPLATE_FILES = /* @__PURE__ */ new Set([
+  "commands/check.md",
+  "commands/test.md",
+  "commands/bench.md",
+  "commands/deep-survey.md",
+  "skills/deep-survey/SKILL.md"
+]);
 var SKILL_NAMES = [
   "tool-selection",
   "impact-analysis",
@@ -3494,7 +3504,13 @@ async function setup(yes2) {
     const src = path9.join(sourceDir, file);
     const dest = path9.join(targetDir, file);
     if (fs8.existsSync(src)) {
-      copyFile(src, dest);
+      if (selectedAgents.includes("claude-code") && CLAUDE_TEMPLATE_FILES.has(file)) {
+        const content = fs8.readFileSync(src, "utf-8").replaceAll(CLAUDE_NODE_PLACEHOLDER, process.execPath);
+        fs8.mkdirSync(path9.dirname(dest), { recursive: true });
+        fs8.writeFileSync(dest, content);
+      } else {
+        copyFile(src, dest);
+      }
       copied++;
     } else {
       p.log.warn(`Source file not found: ${file}`);
@@ -3504,8 +3520,8 @@ async function setup(yes2) {
     const mcpConfig = {
       mcpServers: {
         typegraph: {
-          command: "npx",
-          args: ["tsx", "${CLAUDE_PLUGIN_ROOT}/server.ts"],
+          command: process.execPath,
+          args: ["${CLAUDE_PLUGIN_ROOT}/node_modules/tsx/dist/cli.mjs", "${CLAUDE_PLUGIN_ROOT}/server.ts"],
           env: {
             TYPEGRAPH_PROJECT_ROOT: ".",
             TYPEGRAPH_TSCONFIG: "./tsconfig.json"

package/package.json

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

package/skills/code-exploration/SKILL.md

@@ -24,6 +24,11 @@ If you know the file:
 - Call `ts_module_exports` to see what the file provides
 - Call `ts_find_symbol` to locate a specific symbol within it
 
+If `ts_module_exports` on a top-level `index.ts` is empty or mostly re-exports:
+- Treat it as a barrel, not a dead end
+- Pivot to a composition module such as an app entrypoint, router, handler, API module, or service composition root
+- Use `ts_dependency_tree` on that composition module to get quick architectural context
+
 ### Step 2: Understand the Type
 Call `ts_type_info` on the entry point symbol. This gives you the full type signature and documentation without reading the entire file.
 
@@ -33,6 +38,8 @@ Call `ts_trace_chain` to follow the definition chain from the entry point to the
 ### Step 4: Explore the Neighborhood
 Call `ts_subgraph` with the key files discovered in step 3 to see the surrounding module structure. Use `direction: "both"` and `depth: 1` for immediate context.
 
+For a fast system-level read, `ts_dependency_tree` on the composition module often gives a better first picture than reading a barrel file's exports.
+
 ### Step 5: Deep Dive Where Needed
 Only now, read specific files at the lines identified by the tools. You have precise coordinates — no need to read entire files.
 

package/skills/deep-survey/SKILL.md

@@ -31,7 +31,7 @@ Follow the phases below in order. Each phase produces findings.
 
 Run the health check first:
 ```bash
-npx tsx ${CLAUDE_PLUGIN_ROOT}/cli.ts check
+"__TYPEGRAPH_NODE__" "${CLAUDE_PLUGIN_ROOT}/node_modules/tsx/dist/cli.mjs" "${CLAUDE_PLUGIN_ROOT}/cli.ts" check
 ```
 
 Record three numbers from the output:
@@ -54,6 +54,8 @@ Glob: **/index.ts, **/main.ts, **/entry*.ts, **/worker*.ts, **/server.ts, **/app
 
 Exclude `node_modules/` hits. The results are your starting nodes.
 
+Prefer these composition modules over top-level barrel files for your first passes. Barrels often describe the public API surface, but entry points and composition roots reveal how the system is actually wired.
+
 ### 1b. Dependency tree from every entry point (depth 2)
 
 For each entry point, run:
@@ -121,6 +123,8 @@ Record for each:
 - **Export types** — classes, interfaces, types, constants, functions. A file that exports 8 interfaces is a contract definition. A file that exports 8 constants is a configuration. A file that exports a mix of class + error + test layer is a service module.
 - **Naming patterns** — do exports follow consistent naming (`*Service`, `*Error`, `*Test`, `*Live`)? Consistency across files is evidence of intentional patterns.
 
+If a file is a barrel and `ts_module_exports` is sparse or uninformative, do not stop there. Pivot to the concrete composition modules it fronts and use `ts_dependency_tree` or `ts_module_exports` there instead.
+
 ### 2c. Module boundaries — how coupled are directories?
 
 Identify 3-5 directories that look like they should be self-contained modules (e.g., `services/billing/`, `providers/email/`, `middleware/`).

package/skills/tool-selection/SKILL.md

@@ -29,6 +29,8 @@ Use **ts_type_info** — returns the same info as hovering in VS Code. Includes
 ### "What are all the exports of this file?"
 Use **ts_module_exports** — lists all exported symbols with their resolved types.
 
+If the file is a top-level barrel (`index.ts`, re-export hub), the result may be sparse or unhelpful for architecture discovery. For quick project insight, prefer composition modules such as entrypoints, routers, handler modules, service composition roots, or API modules that wire concrete behavior together.
+
 ### "Where is X used?"
 Use **ts_references** for all semantic references. Unlike grep, this returns only real code references, not string matches in comments or unrelated variables.
 
@@ -63,6 +65,7 @@ Use **ts_module_boundary** — analyzes incoming/outgoing edges, shared dependen
 3. **Combine tools for workflows.** Impact analysis = ts_blast_radius + ts_dependents. Refactor safety = ts_trace_chain + ts_import_cycles.
 4. **Graph queries are instant** (~0.1ms). Point queries are fast (~2-50ms). Don't hesitate to use them liberally.
 5. **First query may be slow** (~2s) as tsserver warms up. All subsequent queries are fast.
+6. **For fast architecture reads, start at composition modules, not barrels.** Barrels are useful for API shape, but entrypoints and composition roots tell you how the system is actually wired.
 
 ## Tool Reference