typegraph-mcp 0.9.37 → 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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typegraph-mcp",
-  "version": "0.9.37",
+  "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

@@ -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