@papyruslabsai/seshat-mcp 0.6.0 → 0.8.0

package/dist/graph.js

@@ -31,59 +31,111 @@ export function buildCallGraph(entities) {
     }
     // Build call edges from dependency data
     for (const caller of entities) {
-        if (!caller.id || !caller.edges?.calls)
+        if (!caller.id || !caller.edges)
             continue;
+        // Process direct function/method calls
         const callsArray = caller.edges.calls;
-        if (!Array.isArray(callsArray))
-            continue;
-        for (const call of callsArray) {
-            if (!call.target)
-                continue;
-            const target = call.target;
-            let calleeId = null;
-            // Strategy 1: Exact match
-            if (entityById.has(target)) {
-                calleeId = target;
-            }
-            // Strategy 2: Method match (target = "module.method")
-            else if (target.includes('.')) {
-                const dotIdx = target.indexOf('.');
-                const modulePart = target.substring(0, dotIdx);
-                const methodPart = target.substring(dotIdx + 1);
-                // First try "module.method" as a full entity ID
+        if (Array.isArray(callsArray)) {
+            for (const call of callsArray) {
+                if (!call.target)
+                    continue;
+                const target = call.target;
+                let calleeId = null;
+                // Strategy 1: Exact match
                 if (entityById.has(target)) {
                     calleeId = target;
                 }
-                // Search within the module's entities for one named methodPart
+                // Strategy 2: Method match (target = "module.method")
+                else if (target.includes('.')) {
+                    const dotIdx = target.indexOf('.');
+                    const modulePart = target.substring(0, dotIdx);
+                    const methodPart = target.substring(dotIdx + 1);
+                    // First try "module.method" as a full entity ID
+                    if (entityById.has(target)) {
+                        calleeId = target;
+                    }
+                    // Search within the module's entities for one named methodPart
+                    if (!calleeId) {
+                        const moduleEntities = entityByModule.get(modulePart);
+                        if (moduleEntities) {
+                            const match = moduleEntities.find(e => {
+                                const name = typeof e.struct === 'string' ? e.struct : e.struct?.name;
+                                return e.id === methodPart || name === methodPart;
+                            });
+                            if (match) {
+                                calleeId = match.id;
+                            }
+                        }
+                    }
+                    // Also try "module.method" concatenated as an ID
+                    if (!calleeId && entityById.has(`${modulePart}.${methodPart}`)) {
+                        calleeId = `${modulePart}.${methodPart}`;
+                    }
+                }
+                // Strategy 3: Prefix match
                 if (!calleeId) {
-                    const moduleEntities = entityByModule.get(modulePart);
-                    if (moduleEntities) {
-                        const match = moduleEntities.find(e => {
-                            const name = typeof e.struct === 'string' ? e.struct : e.struct?.name;
-                            return e.id === methodPart || name === methodPart;
-                        });
-                        if (match) {
-                            calleeId = match.id;
+                    for (const [id] of entityById) {
+                        if (id.endsWith(`.${target}`) || id === target) {
+                            calleeId = id;
+                            break;
                         }
                     }
                 }
-                // Also try "module.method" concatenated as an ID
-                if (!calleeId && entityById.has(`${modulePart}.${methodPart}`)) {
-                    calleeId = `${modulePart}.${methodPart}`;
+                if (calleeId && calleeId !== caller.id) {
+                    callees.get(caller.id)?.add(calleeId);
+                    callers.get(calleeId)?.add(caller.id);
                 }
             }
-            // Strategy 3: Prefix match
-            if (!calleeId) {
-                for (const [id] of entityById) {
-                    if (id.endsWith(`.${target}`) || id === target) {
+        }
+        // Process lexical imports (wiring file-level dependencies into the graph)
+        const importsArray = caller.edges.imports;
+        if (Array.isArray(importsArray)) {
+            for (const imp of importsArray) {
+                // If it's a module-level entity, we link to the module
+                let calleeId = null;
+                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;
                     }
                 }
+                if (calleeId && calleeId !== caller.id) {
+                    callees.get(caller.id)?.add(calleeId);
+                    callers.get(calleeId)?.add(caller.id);
+                }
             }
-            if (calleeId && calleeId !== caller.id) {
-                callees.get(caller.id)?.add(calleeId);
-                callers.get(calleeId)?.add(caller.id);
+        }
+        // Process IoC / Dynamic Dispatch (calledBy)
+        const calledByArray = caller.edges.calledBy;
+        if (Array.isArray(calledByArray)) {
+            for (const cb of calledByArray) {
+                const source = cb.source;
+                if (!source)
+                    continue;
+                let callerId = null;
+                if (entityById.has(source)) {
+                    callerId = source;
+                }
+                else {
+                    for (const [id] of entityById) {
+                        if (id.endsWith(`.${source}`) || id === source) {
+                            callerId = id;
+                            break;
+                        }
+                    }
+                }
+                // 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.
+                if (callerId && callerId !== caller.id) {
+                    callees.get(callerId)?.add(caller.id); // true caller calls this entity
+                    callers.get(caller.id)?.add(callerId); // this entity is called by true caller
+                }
             }
         }
     }

package/dist/index.js

@@ -34,7 +34,7 @@ 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, find_runtime_violations, find_ownership_violations, query_traits, } from './tools/functors.js';
+import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, estimateTaskCost, reportActualBurn, find_runtime_violations, find_ownership_violations, query_traits, simulate_mutation, query_data_targets, find_exposure_leaks, find_semantic_clones, } from './tools/functors.js';
 import { diffBundle, conflictMatrix, } from './tools/diff.js';
 // ─── Project Discovery ───────────────────────────────────────────
 /**
@@ -424,6 +424,75 @@ const TOOLS = [
             required: ['trait'],
         },
     },
+    {
+        name: 'simulate_mutation',
+        description: 'The Semantic Physics Engine. Proposes a hypothetical change to an entity\'s dimensions (like adding a "fallible" or "auth" trait) and simulates the topological fallout upstream and downstream. Returns a blueprint of exactly which other entities will break and what fixes they require.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                entity_id: {
+                    type: 'string',
+                    description: 'The target entity to mutate.',
+                },
+                mutation: {
+                    type: 'object',
+                    description: 'The hypothetical change to apply.',
+                    properties: {
+                        dimension: { type: 'string', enum: ['constraints', 'traits'] },
+                        change: {
+                            type: 'object',
+                            properties: {
+                                add: { type: 'array', items: { type: 'string' } },
+                                remove: { type: 'array', items: { type: 'string' } },
+                            },
+                        },
+                    },
+                    required: ['dimension', 'change'],
+                },
+            },
+            required: ['entity_id', 'mutation'],
+        },
+    },
+    {
+        name: 'query_data_targets',
+        description: 'Search the codebase across the δ (Data) dimension to find all entities that read or write to a specific database table, state object, or data source. This acts as a reverse-index for data flow, essential for planning migrations or state refactors.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                target_name: {
+                    type: 'string',
+                    description: 'The name of the database table, state object, or data source to query (e.g., "users", "auth_token").',
+                },
+            },
+            required: ['target_name'],
+        },
+    },
+    {
+        name: 'find_exposure_leaks',
+        description: 'Analyze the call graph across the χ (Context) dimension to find architectural visibility leaks. Flags paths where a "public" or "api" entity directly accesses a "private" entity, potentially leaking sensitive data or bypassing internal service boundaries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+            },
+        },
+    },
+    {
+        name: 'find_semantic_clones',
+        description: 'Analyze the codebase across the Σ (Semantics) dimension to find duplicated logic blocks. Normalizes variables and compares abstract syntax tree shapes to identify identical algorithms written across different files or even different languages.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                min_complexity: {
+                    type: 'number',
+                    description: 'Minimum number of logic expressions required to constitute a match (default: 5).',
+                },
+            },
+        },
+    },
     // ─── Diff Tools ─────────────────────────────────────────────────
     {
         name: 'diff_bundle',
@@ -638,6 +707,18 @@ async function main() {
                 case 'query_traits':
                     result = query_traits(args);
                     break;
+                case 'simulate_mutation':
+                    result = simulate_mutation(args);
+                    break;
+                case 'query_data_targets':
+                    result = query_data_targets(args);
+                    break;
+                case 'find_exposure_leaks':
+                    result = find_exposure_leaks(args);
+                    break;
+                case 'find_semantic_clones':
+                    result = find_semantic_clones(args);
+                    break;
                 // Diff Tools
                 case 'diff_bundle':
                     result = await diffBundle(args);

package/dist/tools/functors.d.ts

@@ -76,3 +76,25 @@ export declare function query_traits(args: {
     trait: string;
     project?: string;
 }): unknown;
+export declare function simulate_mutation(args: {
+    entity_id: string;
+    mutation: {
+        dimension: 'constraints' | 'traits';
+        change: {
+            add?: string[];
+            remove?: string[];
+        };
+    };
+    project?: string;
+}): unknown;
+export declare function query_data_targets(args: {
+    target_name: string;
+    project?: string;
+}): unknown;
+export declare function find_exposure_leaks(args?: {
+    project?: string;
+}): unknown;
+export declare function find_semantic_clones(args?: {
+    project?: string;
+    min_complexity?: number;
+}): unknown;

package/dist/tools/functors.js

@@ -6,7 +6,7 @@
  * coupling metrics, auth coverage, etc.) from the entity data.
  */
 import { computeBlastRadius } from '../graph.js';
-import { getLoader, getGraph, validateProject, entityLayer, entitySummary, } from './index.js';
+import { getLoader, getGraph, validateProject, entityName, entityLayer, entitySummary, } from './index.js';
 import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, listPredictions, } from '../supabase.js';
 // ─── Layer ordering for violation detection ──────────────────────
 const LAYER_ORDER = {
@@ -992,3 +992,221 @@ export function query_traits(args) {
         entities: results.slice(0, 100).map(entitySummary),
     };
 }
+// ─── Tool: simulate_mutation (The Physics Engine) ────────────────
+export function simulate_mutation(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const g = getGraph(args.project);
+    const targetEntity = loader.getEntityById(args.entity_id, args.project)
+        || loader.getEntityByName(args.entity_id, args.project);
+    if (!targetEntity) {
+        return { error: `Entity not found: ${args.entity_id}` };
+    }
+    const targetId = targetEntity.id;
+    const { dimension, change } = args.mutation;
+    const addedTags = (change.add || []).map(t => t.toLowerCase());
+    // We are currently simulating topological fallout for newly ADDED constraints/traits.
+    // Example: If we add "fallible" or "auth", who upstream breaks because they don't handle it?
+    const fallout = [];
+    // Simulate Fallout: Traversal Upstream (Callers)
+    const upQueue = [[targetId, 0]];
+    const upVisited = new Set([targetId]);
+    while (upQueue.length > 0) {
+        const [currentId, depth] = upQueue.shift();
+        if (depth > 5)
+            continue; // bound simulation depth
+        const callerSet = g.callers.get(currentId);
+        if (!callerSet)
+            continue;
+        for (const callerId of callerSet) {
+            if (upVisited.has(callerId))
+                continue;
+            upVisited.add(callerId);
+            const callerEntity = g.entityById.get(callerId);
+            if (!callerEntity)
+                continue;
+            const callerConstraints = callerEntity.constraints;
+            const callerTraits = callerEntity.traits;
+            // Rule 1: Fallible Simulation
+            if (addedTags.includes('fallible') || addedTags.includes('throws')) {
+                const hasErrorHandling = callerConstraints?.errorHandling &&
+                    (callerConstraints.errorHandling.tryCatch || callerConstraints.errorHandling.catchClause);
+                if (!hasErrorHandling) {
+                    fallout.push({
+                        entity: entitySummary(callerEntity),
+                        distance: depth + 1,
+                        reason: `Calls a newly fallible pipeline but lacks error handling.`,
+                        requiredFix: `Wrap call to ${currentId} in try/catch or propagate error.`,
+                    });
+                    // Error propagates up if not caught, so we continue queueing
+                    upQueue.push([callerId, depth + 1]);
+                }
+            }
+            // Rule 2: Auth / Security Simulation
+            else if (addedTags.includes('auth') || addedTags.includes('secure')) {
+                // Does the caller provide Auth? Check constraints.auth or if they are a known auth middleware
+                const hasAuth = callerConstraints?.auth || callerTraits?.self?.authContext;
+                const isMiddleware = entityLayer(callerEntity) === 'middleware';
+                if (!hasAuth && !isMiddleware) {
+                    fallout.push({
+                        entity: entitySummary(callerEntity),
+                        distance: depth + 1,
+                        reason: `Upstream path is unauthenticated but downstream requires auth.`,
+                        requiredFix: `Add authentication context to ${entityName(callerEntity)} or its router.`,
+                    });
+                    upQueue.push([callerId, depth + 1]);
+                }
+            }
+            // Generic unhandled propagation
+            else {
+                upQueue.push([callerId, depth + 1]);
+            }
+        }
+    }
+    return {
+        target: entitySummary(targetEntity),
+        mutation: args.mutation,
+        affectedEntitiesCount: fallout.length,
+        _summary: `Simulating adding [${addedTags.join(', ')}] to ${entityName(targetEntity)}. This structurally breaks ${fallout.length} upstream entities.`,
+        fallout,
+    };
+}
+// ─── Tool: query_data_targets (δ Dimension Reverse-Index) ────────
+export function query_data_targets(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const entities = loader.getEntities(args.project);
+    const target = args.target_name.toLowerCase();
+    const readers = [];
+    const writers = [];
+    for (const e of entities) {
+        if (!e.data)
+            continue;
+        let isReader = false;
+        let isWriter = false;
+        // Check tables
+        if (Array.isArray(e.data.tables) && e.data.tables.some(t => String(t).toLowerCase() === target)) {
+            // By default, if they touch a table but don't specify mutation, we assume read
+            isReader = true;
+        }
+        // Check inputs (sources)
+        if (Array.isArray(e.data.inputs)) {
+            if (e.data.inputs.some(i => i && typeof i === 'object' && String(i.name || i.source).toLowerCase() === target)) {
+                isReader = true;
+            }
+        }
+        else if (Array.isArray(e.data.sources)) {
+            if (e.data.sources.some(s => String(s).toLowerCase() === target)) {
+                isReader = true;
+            }
+        }
+        // Check mutations
+        if (Array.isArray(e.data.mutations)) {
+            if (e.data.mutations.some(m => m && typeof m === 'object' && String(m.target).toLowerCase() === target)) {
+                isWriter = true;
+            }
+        }
+        if (isWriter) {
+            writers.push(entitySummary(e));
+        }
+        else if (isReader) {
+            readers.push(entitySummary(e));
+        }
+    }
+    return {
+        target: args.target_name,
+        totalInteractions: readers.length + writers.length,
+        writersCount: writers.length,
+        readersCount: readers.length,
+        _summary: `Found ${writers.length} entities mutating and ${readers.length} entities reading data target '${args.target_name}' (δ dimension reverse-index)`,
+        writers: writers.slice(0, 50),
+        readers: readers.slice(0, 50),
+    };
+}
+// ─── Tool: find_exposure_leaks (χ Context Dimension) ─────────────
+export function find_exposure_leaks(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const g = getGraph(args?.project);
+    const leaks = [];
+    for (const [callerId, calleeIds] of g.callees) {
+        const callerEntity = g.entityById.get(callerId);
+        if (!callerEntity)
+            continue;
+        const callerVisibility = callerEntity.context?.visibility || callerEntity.context?.exposure;
+        if (callerVisibility !== 'public' && callerVisibility !== 'api')
+            continue;
+        for (const calleeId of calleeIds) {
+            const calleeEntity = g.entityById.get(calleeId);
+            if (!calleeEntity)
+                continue;
+            const calleeVisibility = calleeEntity.context?.visibility;
+            if (calleeVisibility === 'private') {
+                leaks.push({
+                    publicCaller: entitySummary(callerEntity),
+                    privateCallee: entitySummary(calleeEntity),
+                    issue: `Exposure Leak: Public/API entity directly calls deeply private entity.`,
+                });
+            }
+        }
+    }
+    return {
+        totalLeaks: leaks.length,
+        _summary: `Found ${leaks.length} architectural visibility leaks where public edges bypass internal boundaries to reach private entities (χ dimension)`,
+        leaks: leaks.slice(0, 100),
+    };
+}
+// ─── Tool: find_semantic_clones (Σ Logic Dimension) ──────────────
+import { createHash } from 'crypto';
+export function find_semantic_clones(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const entities = loader.getEntities(args?.project);
+    const { min_complexity = 5 } = args || {};
+    const logicHashes = new Map();
+    for (const e of entities) {
+        if (!e.semantics || !Array.isArray(e.semantics) || e.semantics.length < min_complexity) {
+            continue;
+        }
+        // A highly simplified logic stringification that ignores specific variable names
+        // but captures the structural AST shape. 
+        // In a production scenario, you would normalize variable identifiers ($1, $2) here.
+        const shapeString = JSON.stringify(e.semantics, (key, value) => {
+            // Omit line numbers and exact variable names to find structural clones
+            if (key === 'loc' || key === 'name' || key === 'value' || key === 'id')
+                return undefined;
+            return value;
+        });
+        const hash = createHash('sha256').update(shapeString).digest('hex');
+        if (!logicHashes.has(hash))
+            logicHashes.set(hash, []);
+        logicHashes.get(hash).push(e);
+    }
+    const clones = [];
+    for (const [hash, group] of logicHashes.entries()) {
+        if (group.length > 1) {
+            clones.push({
+                count: group.length,
+                entities: group.map(e => entitySummary(e)),
+            });
+        }
+    }
+    // Sort by highest duplication count
+    clones.sort((a, b) => b.count - a.count);
+    let totalDuplicatedEntities = 0;
+    for (const c of clones)
+        totalDuplicatedEntities += c.count;
+    return {
+        cloneGroupsFound: clones.length,
+        totalDuplicatedEntities,
+        _summary: `Found ${clones.length} semantic clone groups involving ${totalDuplicatedEntities} total entities (Σ dimension analysis)`,
+        cloneGroups: clones.slice(0, 50),
+    };
+}

package/package.json

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