@papyruslabsai/seshat-mcp 0.16.7 → 0.16.8

package/dist/graph.js

@@ -29,6 +29,25 @@ export function buildCallGraph(entities) {
             entityByModule.get(mod).push(entity);
         }
     }
+    // Suffix index: map last dotted segment → first matching entity ID (for O(1) suffix lookups)
+    const bySuffix = new Map();
+    for (const [id] of entityById) {
+        const suffix = id.split('.').pop();
+        if (suffix && !bySuffix.has(suffix))
+            bySuffix.set(suffix, id);
+    }
+    // Filepath index: map source file paths and basenames → entity ID (for O(1) import resolution)
+    const byFilePath = new Map();
+    for (const [id, entity] of entityById) {
+        const src = entity._sourceFile || entity.context?.module || '';
+        if (src) {
+            const basename = src.split('/').pop()?.replace(/\.[^.]+$/, '') || '';
+            if (basename && !byFilePath.has(basename))
+                byFilePath.set(basename, id);
+            if (!byFilePath.has(src))
+                byFilePath.set(src, id);
+        }
+    }
     // Build call edges from dependency data
     for (const caller of entities) {
         if (!caller.id || !caller.edges)
@@ -72,14 +91,9 @@ export function buildCallGraph(entities) {
                         calleeId = `${modulePart}.${methodPart}`;
                     }
                 }
-                // Strategy 3: Prefix match
+                // Strategy 3: Suffix match via index (O(1) lookup)
                 if (!calleeId) {
-                    for (const [id] of entityById) {
-                        if (id.endsWith(`.${target}`) || id === target) {
-                            calleeId = id;
-                            break;
-                        }
-                    }
+                    calleeId = bySuffix.get(target) || null;
                 }
                 if (calleeId && calleeId !== caller.id) {
                     callees.get(caller.id)?.add(calleeId);
@@ -96,15 +110,9 @@ export function buildCallGraph(entities) {
                 const source = imp.source || imp.module;
                 if (!source)
                     continue;
-                // Attempt to find the imported module or entity
-                // Here we do a basic substring match against source files/modules
-                for (const [id, entity] of entityById) {
-                    const eSource = entity._sourceFile || entity.context?.module || '';
-                    if (eSource && (eSource.includes(source) || source.includes(eSource))) {
-                        calleeId = id;
-                        break;
-                    }
-                }
+                // Attempt to find the imported module or entity via filepath index (O(1) lookup)
+                const sourceBasename = source.split('/').pop()?.replace(/\.[^.]+$/, '') || '';
+                calleeId = byFilePath.get(source) || (sourceBasename ? byFilePath.get(sourceBasename) : null) || null;
                 if (calleeId && calleeId !== caller.id) {
                     callees.get(caller.id)?.add(calleeId);
                     callers.get(calleeId)?.add(caller.id);
@@ -123,12 +131,8 @@ export function buildCallGraph(entities) {
                     callerId = source;
                 }
                 else {
-                    for (const [id] of entityById) {
-                        if (id.endsWith(`.${source}`) || id === source) {
-                            callerId = id;
-                            break;
-                        }
-                    }
+                    // Suffix match via index (O(1) lookup)
+                    callerId = bySuffix.get(source) || null;
                 }
                 // In this relationship, the current entity (`caller` in this loop context, despite the name) 
                 // is actually the CALLEE, and the `source` is the true CALLER.

package/dist/index.js

@@ -54,21 +54,35 @@ if (process.argv[2] === 'setup') {
 // Sent to the LLM at connection time. This is the "first contact" pitch.
 const SERVER_INSTRUCTIONS = `Seshat provides structural code analysis backed by a compiled intermediate representation — not heuristic guesses or text search. Every function, class, and route in the synced codebase has been extracted into a typed symbol graph with dependency edges, data flow, constraints, and architectural layer tags. Results are precise and complete — if Seshat says a function has 3 callers, it has exactly 3 callers.
 
+HOW TO USE SESHAT — Seshat tools are designed for iterative exploration, not one-shot lookups. A single tool call answers a single structural question. Understanding a system requires several calls that build on each other — the same way a senior developer investigates code before changing it.
+
+A typical investigation:
+1. query_entities or list_modules → orient yourself in the codebase
+2. get_entity → deep-dive the function you care about
+3. get_blast_radius → discover what's connected and what could break
+4. get_dependencies or get_data_flow → trace specific edges
+5. get_optimal_context → decide what source to read before making changes
+6. Repeat steps 2-5 on newly discovered symbols until you have a complete picture
+
+Each call reveals structure that informs the next. The goal is understanding, not minimum calls. 5-15 queries per investigation is normal and expected.
+
+All tools are read-only and safe to call at any time.
+
 GETTING STARTED — If list_projects returns empty, the current project hasn't been synced yet. Use the sync_project tool to import it:
 1. Detect the git remote: run \`git remote get-url origin\` in the user's terminal
 2. Call sync_project with that repo URL
 3. Wait for extraction to complete (typically 5-30 seconds depending on repo size)
 4. Then call list_projects again — the project will now appear
-Note: For private repos, sync_project will return a GitHub authorization URL. Direct the user to open it in their browser to connect their GitHub account, then retry sync_project. Once connected, all future private repo syncs work automatically.
+Note: For private repos, sync_project will return a GitHub authorization URL. Direct the user to open it in their browser to connect their GitHub account, then retry sync_project.
 
-Use Seshat tools instead of grep/Read when you need to understand code structure. Each tool maps to a question you're already asking:
+TOOL REFERENCE — Each tool maps to a structural question:
 
 Setup & Navigation:
 - "What projects are loaded?" → list_projects
 - "Sync this repo to Seshat" → sync_project
 - "How is the codebase organized?" → list_modules
 - "What's the full API surface?" → get_topology
-- "What tier am I on / what tools are available?" → get_account_status
+- "What tier am I on?" → get_account_status
 
 Understanding Code:
 - "Find functions by name or layer" → query_entities
@@ -89,23 +103,17 @@ Security & Quality Audits:
 - "Which endpoints require auth and which don't?" → get_auth_matrix
 - "Where is sensitive data exposed without protection?" → find_exposure_leaks
 - "Where are errors thrown but never caught?" → find_error_gaps
-- "Are there architecture violations (e.g. routes calling repos directly)?" → find_layer_violations
+- "Are there architecture violations?" → find_layer_violations
 - "Does framework-agnostic code import framework-specific code?" → find_runtime_violations
 - "Are there memory/lifecycle/ownership issues?" → find_ownership_violations
 
 Metrics:
-- "How coupled is the codebase? Where are the hotspots?" → get_coupling_metrics
+- "How coupled is the codebase?" → get_coupling_metrics
 - "Which functions are tested and which aren't?" → get_test_coverage
 
-All tools are read-only and safe to call speculatively — there is no cost to trying them.
-
-TEMPORAL ANALYSIS — Any tool accepts an optional temporal parameter: { temporal: { last_n: N } }. This runs the tool across the N most recent snapshots and returns a trend — timeseries of scalar metrics plus entity-level diffs (what appeared/disappeared). Requires at least 2 snapshots (call sync_project after commits to build history). Example:
+TEMPORAL ANALYSIS — Any tool accepts an optional temporal parameter: { temporal: { last_n: N } }. This runs the tool across recent snapshots and returns a trend. Requires at least 2 snapshots. Example:
   get_coupling_metrics({ project: "myapp", temporal: { last_n: 5 } })
-  → shows coupling trend over last 5 syncs
-  find_dead_code({ project: "myapp", temporal: { last_n: 3 } })
-  → shows whether dead code is accumulating or being cleaned up
-
-get_blast_radius and get_optimal_context are designed to be called iteratively. Start with any entity, then feed discovered entities back in to expand your understanding. Each round reveals new structure that informs where to look next. When answering "what does this system do?" questions, a few rounds of blast_radius → get_entity → blast_radius on the newly discovered symbols will build a complete picture faster than reading files.`;
+`;
 // ─── Private Tools (Ptah IP — never exposed publicly) ────────────
 // These tools are reserved for the Ptah write layer. They exist in
 // the codebase but are never listed, never hinted at, never mentioned.
@@ -815,25 +823,26 @@ async function main() {
             if (name === 'list_projects' && result.projects && result.projects.length > 0) {
                 _lastKnownProject = result.projects[0].name;
             }
+            // Extract pre-formatted text (table-of-contents style) if the API provided one.
+            // This is far more token-efficient than JSON for list-heavy responses.
+            const textContent = result._text || null;
+            if (result._text)
+                delete result._text;
             // Separate _meta into assistant-only content so it doesn't clutter
             // the user-visible response. The LLM still sees it for context.
             // Server-side _meta now includes cross-tool recommendations.
-            if (result._meta && Object.keys(result._meta).length > 0) {
-                const meta = result._meta;
-                delete result._meta;
-                return {
-                    content: [
-                        { type: 'text', text: JSON.stringify(result, null, 2) },
-                        { type: 'text', text: JSON.stringify({ _meta: meta }), annotations: { audience: ['assistant'], priority: 0.2 } },
-                    ],
-                };
-            }
-            // Strip empty _meta
+            const meta = (result._meta && Object.keys(result._meta).length > 0) ? result._meta : null;
             if (result._meta)
                 delete result._meta;
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-            };
+            // Use text format when available; fall back to compact JSON (no pretty-print)
+            const primaryText = textContent || JSON.stringify(result);
+            const content = [
+                { type: 'text', text: primaryText },
+            ];
+            if (meta) {
+                content.push({ type: 'text', text: JSON.stringify({ _meta: meta }), annotations: { audience: ['assistant'], priority: 0.2 } });
+            }
+            return { content };
         }
         catch (err) {
             return {
@@ -844,7 +853,7 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`Seshat MCP v0.16.6 connected. Structural intelligence ready.\n`);
+    process.stderr.write(`Seshat MCP v0.16.7 connected. Structural intelligence ready.\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

package/dist/tools/index.js

@@ -9,6 +9,12 @@
  */
 import { buildCallGraph, computeBlastRadius } from '../graph.js';
 export function getGraph(project, loader) {
+    // Fast path: use pre-computed call graph edges cached on the snapshot row
+    // (avoids 3-10s CPU rebuild on first request for large codebases)
+    const precomputed = loader.getPrecomputedGraph?.();
+    if (precomputed)
+        return precomputed;
+    // Fallback for old snapshots (NULL call_graph_edges) or local file loaders
     return buildCallGraph(loader.getEntities(project));
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.16.7",
+  "version": "0.16.8",
   "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
   "type": "module",
   "bin": {