@papyruslabsai/seshat-mcp 0.16.2 → 0.16.4

package/dist/index.js

@@ -126,6 +126,7 @@ const TOOLS = [
     // ─── Always Visible ───────────────────────────────────────────────
     {
         name: 'get_account_status',
+        title: 'Account Status',
         description: 'See your current plan, available tools, and credit balance. Call this if a tool returns a tier error or you want to know what tools are available.',
         inputSchema: { type: 'object', properties: {} },
         annotations: READ_ONLY_OPEN,
@@ -133,23 +134,27 @@ const TOOLS = [
     // ─── Cartographer (Free Tier) ─────────────────────────────────────
     {
         name: 'list_projects',
+        title: 'List Projects',
         description: 'Start here. Returns all synced codebases with their size, language, and project name. You need the project name for every other tool. If this returns empty, use sync_project to import the current repo.',
         inputSchema: { type: 'object', properties: {} },
         annotations: READ_ONLY_OPEN,
     },
     {
         name: 'sync_project',
-        description: 'Import a public GitHub repo into Seshat for structural analysis. Call this when list_projects returns empty or when the user wants to analyze a new repo. Detects the git remote automatically if no URL is provided. Extraction typically takes 5-30 seconds. After syncing, call list_projects to confirm the project is available.',
+        title: 'Sync Project',
+        description: 'Import a public GitHub repo into Seshat for structural analysis. Call this when list_projects returns empty or when the user wants to analyze a new repo. Detects the git remote automatically if no URL is provided. Extraction typically takes 5-30 seconds. After syncing, call list_projects to confirm the project is available. Use force: true to re-extract even if a cached snapshot exists (useful after code changes or when Seshat extraction has been updated).',
         inputSchema: {
             type: 'object',
             properties: {
                 repo_url: { type: 'string', description: 'Public GitHub repo URL (e.g., https://github.com/org/repo). If omitted, tries to detect from the current git remote.' },
+                force: { type: 'boolean', description: 'Force re-extraction even if a cached snapshot exists. Default: false.' },
             },
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
         name: 'query_entities',
+        title: 'Query Entities',
         description: 'Like grep but for code structure. Find functions, classes, and routes by name, architectural layer (route/service/component), or module. Returns matching symbols with their type, file, and layer — use this instead of grep when you need to find code by what it does, not by text content.',
         inputSchema: {
             type: 'object',
@@ -166,6 +171,7 @@ const TOOLS = [
     },
     {
         name: 'get_entity',
+        title: 'Get Entity Details',
         description: 'Get everything about one function or class — its signature, callers, callees, data flow, constraints, source location, and database operations (which tables it reads/writes). Use this when you need to deeply understand a single symbol before modifying it. Returns more than reading the source file because it includes the dependency context.',
         inputSchema: {
             type: 'object',
@@ -179,6 +185,7 @@ const TOOLS = [
     },
     {
         name: 'get_dependencies',
+        title: 'Get Dependencies',
         description: 'Trace who calls a function and what it calls, up to N levels deep. Use this instead of grep-for-function-name when you need the actual call chain — returns the dependency graph, not text matches. Covers callers (upstream), callees (downstream), or both.',
         inputSchema: {
             type: 'object',
@@ -194,6 +201,7 @@ const TOOLS = [
     },
     {
         name: 'get_data_flow',
+        title: 'Get Data Flow',
         description: 'See what data a function reads, returns, and mutates (DB writes, state changes). Use this when debugging data bugs or when you need to verify whether a function has side effects before refactoring it.',
         inputSchema: {
             type: 'object',
@@ -207,6 +215,7 @@ const TOOLS = [
     },
     {
         name: 'find_by_constraint',
+        title: 'Find by Constraint',
         description: 'Find every function with a specific syntactic constraint tag — AUTH (requires authentication), DB_ACCESS (touches database), THROWS (explicit throw statement), PURE (no side effects), NETWORK_IO (makes HTTP calls), VALIDATED (has input validation). Also supports table-level queries: pass table="walks" to find every function that reads or writes the walks table (answers "what touches this table?" for schema migrations). Constraints are extracted from source syntax, not inferred. For semantic/behavioral properties (e.g., "can fail transitively"), use query_traits instead.',
         inputSchema: {
             type: 'object',
@@ -221,6 +230,7 @@ const TOOLS = [
     },
     {
         name: 'get_blast_radius',
+        title: 'Get Blast Radius',
         description: 'Before modifying a function, call this to see everything that could break. Returns all transitively affected symbols — both upstream callers and downstream callees — with distance from the change point. Like git log --follow but for runtime impact. Designed for repeated use: as you discover new symbols with other tools, call this again on them to expand your understanding of the affected surface.',
         inputSchema: {
             type: 'object',
@@ -234,6 +244,7 @@ const TOOLS = [
     },
     {
         name: 'list_modules',
+        title: 'List Modules',
         description: 'Get a bird\'s-eye view of how the codebase is organized. Groups all symbols by architectural layer (route/service/component), module, file, or language with counts. Use this to orient yourself in an unfamiliar codebase before diving into specifics.',
         inputSchema: {
             type: 'object',
@@ -246,6 +257,7 @@ const TOOLS = [
     },
     {
         name: 'get_topology',
+        title: 'Get Topology',
         description: 'Get the full API surface map in one call — all routes, middleware, auth patterns, and database tables. Use this when you need to understand the overall architecture without reading every file. Returns the information you\'d normally piece together from dozens of file reads.',
         inputSchema: {
             type: 'object',
@@ -255,6 +267,7 @@ const TOOLS = [
     },
     {
         name: 'get_optimal_context',
+        title: 'Get Optimal Context',
         description: 'Before working on a function, call this to get the most relevant related code ranked by importance and fitted to a token budget. Returns a prioritized reading list of symbols you should understand — better than guessing which files to open. Designed for iterative use: call it on your target, read the top results, then call it again on any surprising dependencies to build a complete picture.',
         inputSchema: {
             type: 'object',
@@ -271,7 +284,8 @@ const TOOLS = [
     // ─── Analyst Tools (Tier 2) ───────────────────────────────────────
     {
         name: 'find_dead_code',
-        description: 'Find functions that nothing calls. Walks the call graph from all entry points (routes, exports, tests) and flags symbols that are unreachable. Use this during cleanup or before a release to find safe deletion candidates.',
+        title: 'Find Dead Code',
+        description: 'Find functions that nothing calls. Walks the call graph from all entry points (routes, exports, tests) and flags symbols that are unreachable. Use this during cleanup or before a release to find safe deletion candidates. Note: JSX rendering (<Component />) is not currently tracked as a call edge. Sub-components rendered via JSX may appear as dead code in React/Vue codebases.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -283,6 +297,7 @@ const TOOLS = [
     },
     {
         name: 'find_layer_violations',
+        title: 'Find Layer Violations',
         description: 'Find places where the architecture is broken — a database repository calling a route handler, a utility importing a component. Returns every backward or skip-layer dependency that violates clean architecture.',
         inputSchema: {
             type: 'object',
@@ -292,6 +307,7 @@ const TOOLS = [
     },
     {
         name: 'get_coupling_metrics',
+        title: 'Get Coupling Metrics',
         description: 'Measure how tangled your code is. Returns coupling (cross-boundary dependencies), cohesion (within-group dependencies), and instability scores. High coupling + low cohesion = refactoring candidates. Start with group_by: "layer" for the architectural health view ("are my controllers more coupled than my services?"), then drill into group_by: "module" for specific hotspots.',
         inputSchema: {
             type: 'object',
@@ -304,7 +320,8 @@ const TOOLS = [
     },
     {
         name: 'get_auth_matrix',
-        description: 'Audit authentication coverage. Shows which API routes and controllers require auth and which don\'t, plus inconsistencies like database access without auth checks. For large codebases, use the module parameter to drill into a specific module/directory.',
+        title: 'Get Auth Matrix',
+        description: 'Audit authentication coverage. Shows which API routes and controllers require auth and which don\'t, plus inconsistencies like database access without auth checks. For large codebases, use the module parameter to drill into a specific module/directory. Most useful for backend codebases with middleware-based auth. Frontend frameworks (React, Vue) handle auth via component wrappers, which this tool won\'t detect as AUTH constraints.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -317,6 +334,7 @@ const TOOLS = [
     },
     {
         name: 'find_error_gaps',
+        title: 'Find Error Gaps',
         description: 'Find crash risks: functions that throw or have network/DB side effects whose callers don\'t catch errors. Returns the specific caller→callee pairs where exceptions can propagate unhandled. Use this before shipping to find missing error handling.',
         inputSchema: {
             type: 'object',
@@ -326,6 +344,7 @@ const TOOLS = [
     },
     {
         name: 'get_test_coverage',
+        title: 'Get Test Coverage',
         description: 'See which production functions are actually exercised by tests via the call graph — semantic coverage, not line coverage. Optionally ranks uncovered functions by blast radius so you know which missing tests are riskiest.',
         inputSchema: {
             type: 'object',
@@ -338,18 +357,21 @@ const TOOLS = [
     },
     {
         name: 'find_runtime_violations',
+        title: 'Find Runtime Violations',
         description: 'Find architectural boundary leaks where framework-agnostic code imports framework-specific code. Use this when separating core logic from framework dependencies. Returns 0 for most JS/Python codebases — a non-zero result indicates a serious boundary violation worth investigating.',
         inputSchema: { type: 'object', properties: { project: projectParam } },
         annotations: READ_ONLY_OPEN,
     },
     {
         name: 'find_ownership_violations',
+        title: 'Find Ownership Violations',
         description: 'Find memory and lifecycle issues — entities with complex ownership, unsafe blocks, escaping references, or illegal mutability on borrowed data. Returns 0 for most JS/Python codebases — a non-zero result in those languages indicates a serious boundary violation worth investigating. Most detailed results for Rust and C++.',
         inputSchema: { type: 'object', properties: { project: projectParam } },
         annotations: READ_ONLY_OPEN,
     },
     {
         name: 'query_traits',
+        title: 'Query Traits',
         description: 'Find functions by inferred behavioral trait — "fallible" (can fail, including transitively via callees that throw), "asyncContext" (carries async state), "generator" (yields values). Traits are semantic properties inferred from the call graph, not just syntax. Use this when you need to find all code with a specific capability. For syntactic tags (explicit throw statements, DB access), use find_by_constraint instead.',
         inputSchema: {
             type: 'object',
@@ -363,12 +385,14 @@ const TOOLS = [
     },
     {
         name: 'find_exposure_leaks',
+        title: 'Find Exposure Leaks',
         description: 'Find places where public/API code directly accesses private internals, bypassing the intended abstraction boundary. Use this during API design reviews or before extracting a module.',
         inputSchema: { type: 'object', properties: { project: projectParam } },
         annotations: READ_ONLY_OPEN,
     },
     {
         name: 'find_semantic_clones',
+        title: 'Find Semantic Clones',
         description: 'Find duplicated logic across the codebase. Normalizes variable names and compares code structure to catch identical algorithms in different files — even across different languages. Use this before a DRY refactor.',
         inputSchema: {
             type: 'object',
@@ -382,6 +406,7 @@ const TOOLS = [
     // ─── Architect Tools (Tier 3) ─────────────────────────────────────
     {
         name: 'estimate_task_cost',
+        title: 'Estimate Task Cost',
         description: 'Before starting a code change, estimate how many tokens it will consume. Computes the blast radius, sums source tokens across all affected symbols, and projects total burn including iteration cycles. Use this to check if a task fits your context budget before committing to it.',
         inputSchema: {
             type: 'object',
@@ -396,6 +421,7 @@ const TOOLS = [
     },
     {
         name: 'simulate_mutation',
+        title: 'Simulate Mutation',
         description: 'Simulate a hypothetical code change without writing anything. Propose adding or removing constraints/traits on a symbol and see which other symbols would break and what fixes they\'d need. Use this to plan a change before making it.',
         inputSchema: {
             type: 'object',
@@ -424,6 +450,7 @@ const TOOLS = [
     },
     {
         name: 'create_symbol',
+        title: 'Create Symbol',
         description: 'Register a planned new symbol in the graph before it exists on disk. This lets simulate_mutation and conflict_matrix reason about code you haven\'t written yet. Nothing is written to disk.',
         inputSchema: {
             type: 'object',
@@ -440,6 +467,7 @@ const TOOLS = [
     },
     {
         name: 'diff_bundle',
+        title: 'Diff Bundle',
         description: 'Compare a worktree against the loaded project to see what changed structurally — not a line diff, but which symbols were added, removed, or had their signatures/dependencies changed. Use this after making changes to verify the structural impact.',
         inputSchema: {
             type: 'object',
@@ -454,6 +482,7 @@ const TOOLS = [
     },
     {
         name: 'conflict_matrix',
+        title: 'Conflict Matrix',
         description: 'Given multiple planned tasks, check which ones can run in parallel safely. Classifies every task pair: Tier 1 (different files, safe), Tier 2 (same file different symbols, careful), Tier 3 (same symbol, must sequence). Returns a matrix and suggested execution order.',
         inputSchema: {
             type: 'object',
@@ -478,8 +507,23 @@ const TOOLS = [
         },
         annotations: READ_ONLY_OPEN,
     },
+    {
+        name: 'trace_boundaries',
+        title: 'Trace Boundaries',
+        description: 'Identify the boundary surface of one or two codebases — entities that face outward (expose an API, accept network input, make network calls). When given two projects, surfaces both boundary sets so you can trace the handshake between a backend and frontend, detect orphaned routes with no consumer, or find frontend calls with no matching backend handler. Works across any language — boundaries are detected from coordinates (exposure, layer, side effects, data sources), not framework-specific patterns.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_a: { type: 'string', description: 'First project name (e.g., the backend). Required.' },
+                project_b: { type: 'string', description: 'Second project name (e.g., the frontend). Optional — if omitted, shows only project_a\'s boundary surface.' },
+            },
+            required: ['project_a'],
+        },
+        annotations: READ_ONLY_OPEN,
+    },
     {
         name: 'query_data_targets',
+        title: 'Query Data Targets',
         description: 'Find every function that reads from or writes to a specific database table, state object, or data source. Use this when you need to understand all the code paths that touch a particular data store.',
         inputSchema: {
             type: 'object',
@@ -522,7 +566,7 @@ function getCloudUrl(path) {
 async function main() {
     const server = new Server({
         name: 'seshat',
-        version: '0.16.1',
+        version: '0.16.4',
     }, {
         capabilities: { tools: {} },
         instructions: SERVER_INSTRUCTIONS,
@@ -590,6 +634,7 @@ async function main() {
         if (name === 'sync_project') {
             let repoUrl = args?.repo_url;
             // If no URL provided, try to detect git remote
+            let headSha;
             if (!repoUrl) {
                 try {
                     const { execSync } = await import('child_process');
@@ -597,6 +642,11 @@ async function main() {
                     // Normalize SSH URLs to HTTPS
                     const sshMatch = remote.match(/^git@github\.com:(.+)\.git$/);
                     repoUrl = sshMatch ? `https://github.com/${sshMatch[1]}` : remote.replace(/\.git$/, '');
+                    // Capture current HEAD SHA for cache comparison
+                    try {
+                        headSha = execSync('git rev-parse HEAD', { timeout: 5000 }).toString().trim().slice(0, 12);
+                    }
+                    catch { /* shallow clone or no commits */ }
                 }
                 catch {
                     return {
@@ -615,7 +665,7 @@ async function main() {
                         'Content-Type': 'application/json',
                         'x-api-key': apiKey,
                     },
-                    body: JSON.stringify({ repo_url: repoUrl }),
+                    body: JSON.stringify({ repo_url: repoUrl, force: args?.force === true, head_sha: headSha }),
                 });
                 if (!res.ok) {
                     const errorText = await res.text();
@@ -715,11 +765,14 @@ async function main() {
         }
         // Determine the project hash for this workspace
         // list_projects is unscoped — it returns ALL projects for the user
+        // trace_boundaries uses project_a instead of project for its primary project
         const project_hash = name === 'list_projects'
             ? undefined
             : (args && typeof args === 'object' && 'project' in args)
                 ? String(args.project)
-                : resolveProjectName();
+                : (args && typeof args === 'object' && 'project_a' in args)
+                    ? String(args.project_a)
+                    : resolveProjectName();
         // If no project could be resolved and this isn't list_projects, tell the LLM how to fix it
         if (!project_hash && name !== 'list_projects') {
             return {
@@ -784,7 +837,7 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`Seshat MCP v0.16.1 connected. Structural intelligence ready.\n`);
+    process.stderr.write(`Seshat MCP v0.16.4 connected. Structural intelligence ready.\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

package/dist/tools/functors.d.ts

@@ -107,3 +107,7 @@ export declare function create_symbol(args: {
     project?: string;
     description?: string;
 }, loader: ProjectLoader): unknown;
+export declare function trace_boundaries(args: {
+    project_a: string;
+    project_b?: string;
+}, loaderA: ProjectLoader, loaderB?: ProjectLoader): unknown;

package/dist/tools/functors.js

@@ -1221,3 +1221,163 @@ export function create_symbol(args, loader) {
         _summary: `Registered virtual symbol '${args.id}' in ${args.source_file}. Other tools can now reason about this symbol prior to its physical creation.`,
     };
 }
+// ─── Tool: trace_boundaries (Cross-Project Boundary Surface Analysis) ────
+/**
+ * Identify the boundary surface of a codebase — entities that face
+ * outward (expose an API, accept network input, make network calls).
+ *
+ * When two loaders are provided, surfaces both boundary sets and
+ * lets the LLM reason about the handshake between them.
+ */
+const IMPORT_STRUCT_TYPES = new Set([
+    'import', 'importspecifier', 'importdeclaration', 'reexport',
+]);
+function isBoundaryEntity(e) {
+    const structType = (typeof e.struct === 'string' ? e.struct : e.struct?.type || '').toLowerCase();
+    if (IMPORT_STRUCT_TYPES.has(structType))
+        return null;
+    const ctx = e.context || {};
+    const constraints = e.constraints;
+    const sideEffects = (typeof constraints === 'object' && !Array.isArray(constraints))
+        ? constraints.sideEffects
+        : undefined;
+    // Inbound boundary: entities that receive external requests
+    // Coordinates: exposure=api, layer=route/controller, or has auth constraints
+    const isApiExposed = ctx.exposure === 'api' || ctx.exposure === 'public';
+    const isRouteLayer = ctx.layer === 'route' || ctx.layer === 'controller';
+    if (isApiExposed || isRouteLayer)
+        return 'inbound';
+    // Outbound boundary: entities that make external calls
+    // Coordinates: sideEffects includes 'network', or data sources include 'api'/'fetch'
+    const hasNetworkIO = Array.isArray(sideEffects) && sideEffects.includes('network');
+    const dataSources = e.data?.sources || [];
+    const hasApiSource = dataSources.some(s => typeof s === 'string' && ['api', 'fetch', 'network'].includes(s));
+    if (hasNetworkIO || hasApiSource)
+        return 'outbound';
+    return null;
+}
+function boundaryEntitySummary(e) {
+    const base = entitySummary(e);
+    const ctx = e.context || {};
+    const constraints = e.constraints;
+    const sideEffects = (typeof constraints === 'object' && !Array.isArray(constraints))
+        ? constraints.sideEffects
+        : undefined;
+    const dataSources = e.data?.sources || [];
+    // Add boundary-relevant coordinate data
+    if (ctx.exposure)
+        base.exposure = ctx.exposure;
+    if (sideEffects && sideEffects.length > 0)
+        base.sideEffects = sideEffects;
+    if (dataSources.length > 0)
+        base.dataSources = dataSources;
+    // Error handling info (relevant for boundary robustness)
+    const errorHandling = (typeof constraints === 'object' && !Array.isArray(constraints))
+        ? constraints.errorHandling
+        : undefined;
+    if (errorHandling)
+        base.errorHandling = errorHandling;
+    return base;
+}
+export function trace_boundaries(args, loaderA, loaderB) {
+    const entitiesA = loaderA.getEntities(args.project_a);
+    const topologyA = loaderA.getTopology(args.project_a);
+    const surfaceA = {
+        inbound: [], outbound: [],
+    };
+    for (const e of entitiesA) {
+        const direction = isBoundaryEntity(e);
+        if (direction) {
+            surfaceA[direction].push(boundaryEntitySummary(e));
+        }
+    }
+    const result = {
+        project_a: {
+            name: args.project_a,
+            totalEntities: entitiesA.length,
+            boundary: {
+                inbound: surfaceA.inbound.length,
+                outbound: surfaceA.outbound.length,
+            },
+            inbound_surface: surfaceA.inbound.slice(0, 100),
+            outbound_surface: surfaceA.outbound.slice(0, 100),
+        },
+    };
+    // Include topology routes if available (structured route data)
+    if (topologyA) {
+        const routes = [];
+        const prefixes = topologyA.prefixes;
+        if (prefixes) {
+            for (const [prefix, info] of Object.entries(prefixes)) {
+                const routeList = info.routes;
+                if (Array.isArray(routeList)) {
+                    for (const r of routeList) {
+                        routes.push({ ...r, prefix });
+                    }
+                }
+            }
+        }
+        const unregistered = topologyA.unregistered;
+        if (Array.isArray(unregistered)) {
+            routes.push(...unregistered);
+        }
+        if (routes.length > 0) {
+            result.project_a.topology_routes = routes.slice(0, 100);
+        }
+    }
+    // If second project provided, surface its boundaries too
+    if (loaderB && args.project_b) {
+        const entitiesB = loaderB.getEntities(args.project_b);
+        const topologyB = loaderB.getTopology(args.project_b);
+        const surfaceB = {
+            inbound: [], outbound: [],
+        };
+        for (const e of entitiesB) {
+            const direction = isBoundaryEntity(e);
+            if (direction) {
+                surfaceB[direction].push(boundaryEntitySummary(e));
+            }
+        }
+        result.project_b = {
+            name: args.project_b,
+            totalEntities: entitiesB.length,
+            boundary: {
+                inbound: surfaceB.inbound.length,
+                outbound: surfaceB.outbound.length,
+            },
+            inbound_surface: surfaceB.inbound.slice(0, 100),
+            outbound_surface: surfaceB.outbound.slice(0, 100),
+        };
+        if (topologyB) {
+            const routes = [];
+            const prefixes = topologyB.prefixes;
+            if (prefixes) {
+                for (const [prefix, info] of Object.entries(prefixes)) {
+                    const routeList = info.routes;
+                    if (Array.isArray(routeList)) {
+                        for (const r of routeList) {
+                            routes.push({ ...r, prefix });
+                        }
+                    }
+                }
+            }
+            const unregistered = topologyB.unregistered;
+            if (Array.isArray(unregistered)) {
+                routes.push(...unregistered);
+            }
+            if (routes.length > 0) {
+                result.project_b.topology_routes = routes.slice(0, 100);
+            }
+        }
+        // Summary for cross-project analysis
+        const aIn = surfaceA.inbound.length;
+        const aOut = surfaceA.outbound.length;
+        const bIn = surfaceB.inbound.length;
+        const bOut = surfaceB.outbound.length;
+        result._summary = `${args.project_a}: ${aIn} inbound + ${aOut} outbound boundary entities. ${args.project_b}: ${bIn} inbound + ${bOut} outbound boundary entities. Examine inbound surfaces (API handlers) against outbound surfaces (network callers) to trace the handshake.`;
+    }
+    else {
+        result._summary = `${args.project_a}: ${surfaceA.inbound.length} inbound + ${surfaceA.outbound.length} outbound boundary entities.`;
+    }
+    return result;
+}

package/package.json

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