@papyruslabsai/seshat-mcp 0.4.1 → 0.6.0

package/dist/graph.d.ts

@@ -1,9 +1,11 @@
 /**
  * Call Graph Construction & Blast Radius Computation
  *
- * Ported from seshat-pipeline/src/incremental/blast-radius.mjs
- * Implements Theorem 9.4 (Incrementality):
+ * Computes the set of entities affected by a change:
  *   affected(e) = ancestors(e) ∪ descendants(e) ∪ {e}
+ *
+ * Ancestors = all transitive callers (upstream).
+ * Descendants = all transitive callees (downstream).
  */
 import type { JstfEntity } from './types.js';
 export interface CallGraph {
@@ -18,7 +20,7 @@ export interface BlastRadiusResult {
     descendants: string[];
 }
 /**
- * Build a bidirectional call graph from entities' ε (edges) dimension.
+ * Build a bidirectional call graph from entities' dependency data.
  */
 export declare function buildCallGraph(entities: JstfEntity[]): CallGraph;
 /**

package/dist/graph.js

@@ -1,12 +1,14 @@
 /**
  * Call Graph Construction & Blast Radius Computation
  *
- * Ported from seshat-pipeline/src/incremental/blast-radius.mjs
- * Implements Theorem 9.4 (Incrementality):
+ * Computes the set of entities affected by a change:
  *   affected(e) = ancestors(e) ∪ descendants(e) ∪ {e}
+ *
+ * Ancestors = all transitive callers (upstream).
+ * Descendants = all transitive callees (downstream).
  */
 /**
- * Build a bidirectional call graph from entities' ε (edges) dimension.
+ * Build a bidirectional call graph from entities' dependency data.
  */
 export function buildCallGraph(entities) {
     const callers = new Map();
@@ -27,7 +29,7 @@ export function buildCallGraph(entities) {
             entityByModule.get(mod).push(entity);
         }
     }
-    // Build call edges from ε dimension
+    // Build call edges from dependency data
     for (const caller of entities) {
         if (!caller.id || !caller.edges?.calls)
             continue;

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * @papyruslabs/seshat-mcp — Semantic MCP Server
+ * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server
  *
- * Exposes a codebase's 9D JSTF-T coordinate space as queryable MCP tools.
- * Reads .seshat/_bundle.json from project directories.
+ * Exposes a codebase's structure, dependencies, and constraints as queryable
+ * MCP tools. Reads pre-extracted analysis data from .seshat/_bundle.json.
  *
  * Multi-project mode:
  *   Set SESHAT_PROJECTS env var to comma-separated paths or a glob pattern.
@@ -13,25 +13,13 @@
  * Single-project mode (default):
  *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
  *
- * Tools (8 core + 9 interpretation functors + 1 meta):
- *   list_projects       — Show loaded projects with entity counts
- *   query_entities      — Search entities by name, layer, module, language
- *   get_entity          — Full 9D coordinate dump for one entity
- *   get_dependencies    — ε edge traversal (callers/callees with depth control)
- *   get_data_flow       — δ dimension: inputs, outputs, mutations
- *   find_by_constraint  — κ dimension search (AUTH, THROWS, DB_ACCESS, etc.)
- *   get_blast_radius    — Theorem 9.4: affected set for given entity IDs
- *   list_modules        — Group entities by layer, module, file, or language
- *   get_topology        — API topology (routes, plugins, auth, tables)
- *   find_dead_code      — Unreachable entities via ε-graph BFS
- *   find_layer_violations — ε edges violating architectural layer ordering
- *   get_coupling_metrics  — Module coupling/cohesion/instability from ε-graph
- *   get_auth_matrix       — Auth coverage across API-facing entities from κ
- *   find_error_gaps       — Fallible callees whose callers lack try/catch
- *   get_test_coverage     — Entities exercised by tests vs uncovered
- *   get_optimal_context   — Greedy knapsack: max relevance per token for LLM context
- *   estimate_task_cost    — Pre-work token burn projection from blast radius + source tokens
- *   report_actual_burn    — Close calibration loop: actual tokens vs prediction, drift stats
+ * 20 tools across 4 categories:
+ *   Discovery:  list_projects, query_entities, get_entity, list_modules, get_topology
+ *   Graph:      get_dependencies, get_data_flow, find_by_constraint, get_blast_radius
+ *   Analysis:   find_dead_code, find_layer_violations, get_coupling_metrics,
+ *               get_auth_matrix, find_error_gaps, get_test_coverage,
+ *               get_optimal_context, estimate_task_cost, report_actual_burn
+ *   Diff:       diff_bundle, conflict_matrix
  *
  * Usage:
  *   npx @papyruslabs/seshat-mcp                           # single project (CWD)

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * @papyruslabs/seshat-mcp — Semantic MCP Server
+ * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server
  *
- * Exposes a codebase's 9D JSTF-T coordinate space as queryable MCP tools.
- * Reads .seshat/_bundle.json from project directories.
+ * Exposes a codebase's structure, dependencies, and constraints as queryable
+ * MCP tools. Reads pre-extracted analysis data from .seshat/_bundle.json.
  *
  * Multi-project mode:
  *   Set SESHAT_PROJECTS env var to comma-separated paths or a glob pattern.
@@ -13,25 +13,13 @@
  * Single-project mode (default):
  *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
  *
- * Tools (8 core + 9 interpretation functors + 1 meta):
- *   list_projects       — Show loaded projects with entity counts
- *   query_entities      — Search entities by name, layer, module, language
- *   get_entity          — Full 9D coordinate dump for one entity
- *   get_dependencies    — ε edge traversal (callers/callees with depth control)
- *   get_data_flow       — δ dimension: inputs, outputs, mutations
- *   find_by_constraint  — κ dimension search (AUTH, THROWS, DB_ACCESS, etc.)
- *   get_blast_radius    — Theorem 9.4: affected set for given entity IDs
- *   list_modules        — Group entities by layer, module, file, or language
- *   get_topology        — API topology (routes, plugins, auth, tables)
- *   find_dead_code      — Unreachable entities via ε-graph BFS
- *   find_layer_violations — ε edges violating architectural layer ordering
- *   get_coupling_metrics  — Module coupling/cohesion/instability from ε-graph
- *   get_auth_matrix       — Auth coverage across API-facing entities from κ
- *   find_error_gaps       — Fallible callees whose callers lack try/catch
- *   get_test_coverage     — Entities exercised by tests vs uncovered
- *   get_optimal_context   — Greedy knapsack: max relevance per token for LLM context
- *   estimate_task_cost    — Pre-work token burn projection from blast radius + source tokens
- *   report_actual_burn    — Close calibration loop: actual tokens vs prediction, drift stats
+ * 20 tools across 4 categories:
+ *   Discovery:  list_projects, query_entities, get_entity, list_modules, get_topology
+ *   Graph:      get_dependencies, get_data_flow, find_by_constraint, get_blast_radius
+ *   Analysis:   find_dead_code, find_layer_violations, get_coupling_metrics,
+ *               get_auth_matrix, find_error_gaps, get_test_coverage,
+ *               get_optimal_context, estimate_task_cost, report_actual_burn
+ *   Diff:       diff_bundle, conflict_matrix
  *
  * Usage:
  *   npx @papyruslabs/seshat-mcp                           # single project (CWD)
@@ -46,7 +34,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { MultiLoader } from './loader.js';
 import { bootstrap } from './bootstrap.js';
 import { initTools, queryEntities, getEntity, getDependencies, getDataFlow, findByConstraint, getBlastRadius, listModules, getTopology, } from './tools/index.js';
-import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, estimateTaskCost, reportActualBurn, } from './tools/functors.js';
+import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, estimateTaskCost, reportActualBurn, find_runtime_violations, find_ownership_violations, query_traits, } from './tools/functors.js';
+import { diffBundle, conflictMatrix, } from './tools/diff.js';
 // ─── Project Discovery ───────────────────────────────────────────
 /**
  * Discover project directories from SESHAT_PROJECTS env var.
@@ -104,7 +93,7 @@ const TOOLS = [
     },
     {
         name: 'query_entities',
-        description: 'Search entities in the 9D semantic coordinate space. Filter by name, architectural layer (route/service/repository/component), module, or source language. Returns entity summaries with constraint tags.',
+        description: 'Search code entities by name, architectural layer (route/service/repository/component), module, or source language. Returns entity summaries with constraint tags.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -115,11 +104,11 @@ const TOOLS = [
                 },
                 layer: {
                     type: 'string',
-                    description: 'Filter by χ (context) layer: route, controller, service, repository, utility, hook, component, schema',
+                    description: 'Filter by architectural layer: route, controller, service, repository, utility, hook, component, schema',
                 },
                 module: {
                     type: 'string',
-                    description: 'Filter by χ.module (partial match)',
+                    description: 'Filter by module (partial match)',
                 },
                 language: {
                     type: 'string',
@@ -134,7 +123,7 @@ const TOOLS = [
     },
     {
         name: 'get_entity',
-        description: 'Get the full 9D semantic coordinate dump for a specific entity. Returns all dimensions: σ (struct), ε (edges), δ (data), κ (constraints), χ (context), λ (ownership), τ (traits), ρ (runtime), Σ (semantics).',
+        description: 'Get complete details for a specific code entity. Returns structure, call graph, data flow, constraints, context, ownership, type info, runtime, and logic.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -149,7 +138,7 @@ const TOOLS = [
     },
     {
         name: 'get_dependencies',
-        description: 'Traverse the ε (edges) call graph for an entity. Shows callers (who calls this), callees (what this calls), and imports. Supports depth-limited traversal for exploring transitive dependencies.',
+        description: 'Traverse the call graph for an entity. Shows callers (who calls this), callees (what this calls), and imports. Supports depth-limited traversal for exploring transitive dependencies.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -173,7 +162,7 @@ const TOOLS = [
     },
     {
         name: 'get_data_flow',
-        description: 'Get the δ (data) dimension for an entity: what data flows in (inputs/sources), what flows out (outputs/returns), and what gets mutated (database writes, state changes).',
+        description: 'Get data flow for an entity: what data flows in (inputs/sources), what flows out (outputs/returns), and what gets mutated (database writes, state changes).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -188,7 +177,7 @@ const TOOLS = [
     },
     {
         name: 'find_by_constraint',
-        description: 'Search the κ (constraints) dimension across all entities. Find functions by security properties (AUTH, VALIDATED), behavioral properties (PURE, THROWS, DB_ACCESS, NETWORK_IO), or performance characteristics.',
+        description: 'Search entities by behavioral properties. Find functions by security properties (AUTH, VALIDATED), behavioral properties (PURE, THROWS, DB_ACCESS, NETWORK_IO), or performance characteristics.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -203,7 +192,7 @@ const TOOLS = [
     },
     {
         name: 'get_blast_radius',
-        description: 'Compute the blast radius for a set of entities (Theorem 9.4). Returns all transitively affected entities — both upstream (callers) and downstream (callees) — with depth annotations showing distance from the change.',
+        description: 'Compute the blast radius for a set of entities. Returns all transitively affected entities — both upstream (callers) and downstream (callees) — with depth annotations showing distance from the change.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -219,7 +208,7 @@ const TOOLS = [
     },
     {
         name: 'list_modules',
-        description: 'List and count entities grouped by a dimension. See the architectural structure (by layer), module organization (by module), file distribution (by file), or language breakdown (by language).',
+        description: 'List and count entities grouped by a property. See the architectural structure (by layer), module organization (by module), file distribution (by file), or language breakdown (by language).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -234,7 +223,7 @@ const TOOLS = [
     },
     {
         name: 'get_topology',
-        description: 'Get the API topology: routes, plugins, auth patterns, and database tables. Built from the χ (context) and ε (edges) dimensions across all entities.',
+        description: 'Get the API topology: routes, plugins, auth patterns, and database tables. Built from architectural context and dependency analysis across all entities.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -242,10 +231,10 @@ const TOOLS = [
             },
         },
     },
-    // ─── Interpretation Functor Tools ────────────────────────────────
+    // ─── Analysis Tools ─────────────────────────────────────────────
     {
         name: 'find_dead_code',
-        description: 'Find unreachable entities (dead code candidates). BFS from entry points (routes, exported functions, tests, plugins) through the ε call graph. Entities not reachable from any entry point are flagged.',
+        description: 'Find unreachable entities (dead code candidates). BFS from entry points (routes, exported functions, tests, plugins) through the call graph. Entities not reachable from any entry point are flagged.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -259,7 +248,7 @@ const TOOLS = [
     },
     {
         name: 'find_layer_violations',
-        description: 'Detect architectural layer violations in the ε call graph. Finds backward calls (lower layer calling higher layer, e.g. repository → route) and skip-layer calls (jumping over multiple layers). Uses χ.layer for classification.',
+        description: 'Detect architectural layer violations in the call graph. Finds backward calls (lower layer calling higher layer, e.g. repository → route) and skip-layer calls (jumping over multiple layers). Uses architectural layer classification.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -269,7 +258,7 @@ const TOOLS = [
     },
     {
         name: 'get_coupling_metrics',
-        description: 'Compute coupling, cohesion, and instability metrics for modules or layers. Analyzes ε edges between and within groups. High coupling + low cohesion = candidates for refactoring.',
+        description: 'Compute coupling, cohesion, and instability metrics for modules or layers. Analyzes dependency edges between and within groups. High coupling + low cohesion = candidates for refactoring.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -284,7 +273,7 @@ const TOOLS = [
     },
     {
         name: 'get_auth_matrix',
-        description: 'Analyze authentication coverage across all API-facing entities. Shows which routes/controllers have auth requirements (from κ.auth) and which don\'t. Detects inconsistencies like DB access without auth.',
+        description: 'Analyze authentication coverage across all API-facing entities. Shows which routes/controllers have auth requirements and which don\'t. Detects inconsistencies like DB access without auth.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -294,7 +283,7 @@ const TOOLS = [
     },
     {
         name: 'find_error_gaps',
-        description: 'Find error handling gaps: fallible entities (κ.throws, network/db side effects) whose callers lack try/catch (κ.errorHandling). These are crash risk points where exceptions can propagate unhandled.',
+        description: 'Find error handling gaps: entities that throw or have network/db side effects whose callers lack try/catch. These are crash risk points where exceptions can propagate unhandled.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -304,7 +293,7 @@ const TOOLS = [
     },
     {
         name: 'get_test_coverage',
-        description: 'Compute semantic test coverage: which production entities are exercised by test entities via the ε call graph. Optionally weight uncovered entities by blast radius to prioritize what to test first.',
+        description: 'Compute semantic test coverage: which production entities are exercised by test entities via the call graph. Optionally weight uncovered entities by blast radius to prioritize what to test first.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -399,6 +388,101 @@ const TOOLS = [
             },
         },
     },
+    // ─── Semantic (9D) JSTF-T Tools ─────────────────────────────────
+    {
+        name: 'find_runtime_violations',
+        description: 'Analyze the call graph across the ρ (Runtime) dimension. Finds architectural leaks where framework-agnostic code improperly imports framework-specific code (e.g. pure logic calling React hooks) or where incompatible frameworks mix directly.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+            },
+        },
+    },
+    {
+        name: 'find_ownership_violations',
+        description: 'Analyze the codebase across the λ (Ownership/Lifetimes) dimension. Flags entities with complex memory management constraints, unsafe blocks, escaping boundaries, or illegal mutability patterns on borrowed references.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+            },
+        },
+    },
+    {
+        name: 'query_traits',
+        description: 'Search the codebase across the τ (Traits/Capabilities) dimension. Allows you to find entities by their abstract capabilities (e.g., "fallible", "asyncContext", "generator") regardless of their structural syntax.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                trait: {
+                    type: 'string',
+                    description: 'The trait or capability to search for (e.g., "fallible", "asyncContext")',
+                },
+            },
+            required: ['trait'],
+        },
+    },
+    // ─── Diff Tools ─────────────────────────────────────────────────
+    {
+        name: 'diff_bundle',
+        description: 'Compare entities between a worktree and the loaded project. Shows which entities were added, removed, or modified at the symbol level — not a line diff, but a structural diff showing changed signatures, call graphs, constraints, and logic. Extracts the worktree automatically if no bundle exists.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                worktree_path: {
+                    type: 'string',
+                    description: 'Absolute path to the worktree or branch checkout to compare against the loaded project',
+                },
+                include_unchanged: {
+                    type: 'boolean',
+                    description: 'Include unchanged entities in the output (default: false)',
+                },
+            },
+            required: ['worktree_path'],
+        },
+    },
+    {
+        name: 'conflict_matrix',
+        description: 'Given multiple tasks, classify every task pair into conflict tiers bridging JSTF-T theory and Git reality. Tier 1 (different files, safe), Tier 2 (same file, different entities, safe), Tier 3 (same entity, orthogonal Spatial Zones like imports vs logic, risky but parallelizable), Tier 4 (same entity, same Spatial Zone, MUST sequence). Passing "dimensions" per task enables Tier 3 downgrades.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                tasks: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Unique task identifier (e.g. "add-dark-mode")',
+                            },
+                            entity_ids: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Entity IDs or names that this task will modify',
+                            },
+                            dimensions: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Optional: JSTF-T dimensions this task will modify (e.g., "edges", "struct", "semantics", "constraints"). Used to downgrade conflicts via Spatial Zones.',
+                            },
+                            expand_blast_radius: {
+                                type: 'boolean',
+                                description: 'Include transitively affected entities in the conflict check (default: false)',
+                            },
+                        },
+                        required: ['id', 'entity_ids'],
+                    },
+                    description: 'Array of tasks to check for conflicts. Each task specifies which entities it will modify.',
+                },
+            },
+            required: ['tasks'],
+        },
+    },
 ];
 // ─── Server Setup ─────────────────────────────────────────────────
 async function main() {
@@ -454,7 +538,7 @@ async function main() {
     }
     const server = new Server({
         name: serverLabel,
-        version: '0.4.1',
+        version: '0.5.0',
     }, {
         capabilities: {
             tools: {},
@@ -516,7 +600,7 @@ async function main() {
                 case 'get_topology':
                     result = getTopology(args);
                     break;
-                // Interpretation Functors
+                // Analysis Tools
                 case 'find_dead_code':
                     result = findDeadCode(args);
                     break;
@@ -544,6 +628,23 @@ async function main() {
                 case 'report_actual_burn':
                     result = await reportActualBurn(args);
                     break;
+                // Semantic (9D) JSTF-T Tools
+                case 'find_runtime_violations':
+                    result = find_runtime_violations(args);
+                    break;
+                case 'find_ownership_violations':
+                    result = find_ownership_violations(args);
+                    break;
+                case 'query_traits':
+                    result = query_traits(args);
+                    break;
+                // Diff Tools
+                case 'diff_bundle':
+                    result = await diffBundle(args);
+                    break;
+                case 'conflict_matrix':
+                    result = conflictMatrix(args);
+                    break;
                 default:
                     result = { error: `Unknown tool: ${name}` };
             }

package/dist/loader.d.ts

@@ -1,5 +1,5 @@
 /**
- * JSTF-T Bundle Loader
+ * Bundle Loader
  *
  * Discovers and loads .seshat/_bundle.json from the current working directory.
  * Falls back to checking common alternative locations.

package/dist/loader.js

@@ -1,5 +1,5 @@
 /**
- * JSTF-T Bundle Loader
+ * Bundle Loader
  *
  * Discovers and loads .seshat/_bundle.json from the current working directory.
  * Falls back to checking common alternative locations.
@@ -28,8 +28,8 @@ export class BundleLoader {
         const bundle = JSON.parse(raw);
         this.entities = bundle.entities || [];
         // Remap bundle field names to internal _ prefixed names.
-        // The extraction pipeline outputs `sourceFile`, `sourceLanguage`, `_jstfFilename`
-        // but our JstfEntity type expects `_sourceFile`, `_sourceLanguage`.
+        // The extraction pipeline outputs `sourceFile`, `sourceLanguage`
+        // but the entity type expects `_sourceFile`, `_sourceLanguage`.
         for (const e of this.entities) {
             const raw = e;
             if (raw.sourceFile && !e._sourceFile) {

package/dist/tools/diff.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cross-Bundle Analysis Tools: diff_bundle + conflict_matrix
+ *
+ * diff_bundle: Compare entities between a worktree and the loaded project.
+ * conflict_matrix: Classify conflict tiers for parallel task scheduling.
+ *
+ * These tools compare TWO entity sets (base vs branch, or task vs task),
+ * unlike the single-bundle queries in index.ts and functors.ts.
+ */
+export declare function diffBundle(args: {
+    worktree_path: string;
+    project?: string;
+    include_unchanged?: boolean;
+}): Promise<unknown>;
+export declare function conflictMatrix(args: {
+    tasks: Array<{
+        id: string;
+        entity_ids: string[];
+        dimensions?: string[];
+        expand_blast_radius?: boolean;
+    }>;
+    project?: string;
+}): unknown;