@papyruslabsai/seshat-mcp 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -15,6 +15,15 @@
  *   list_modules      — Group entities by layer, module, file, or language
  *   get_topology      — API topology (routes, plugins, auth, tables)
  *
+ * Interpretation Functors (composite analysis):
+ *   find_dead_code      — Unreachable entities via ε-graph BFS from entry points
+ *   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
+ *
  * Usage:
  *   npx @papyruslabs/seshat-mcp
  *

package/dist/index.js

@@ -15,6 +15,15 @@
  *   list_modules      — Group entities by layer, module, file, or language
  *   get_topology      — API topology (routes, plugins, auth, tables)
  *
+ * Interpretation Functors (composite analysis):
+ *   find_dead_code      — Unreachable entities via ε-graph BFS from entry points
+ *   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
+ *
  * Usage:
  *   npx @papyruslabs/seshat-mcp
  *
@@ -26,6 +35,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { BundleLoader } from './loader.js';
 import { initTools, queryEntities, getEntity, getDependencies, getDataFlow, findByConstraint, getBlastRadius, listModules, getTopology, } from './tools/index.js';
+import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, } from './tools/functors.js';
 // ─── Tool Definitions ─────────────────────────────────────────────
 const TOOLS = [
     {
@@ -159,6 +169,94 @@ const TOOLS = [
             properties: {},
         },
     },
+    // ─── Interpretation Functor 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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                include_tests: {
+                    type: 'boolean',
+                    description: 'Include test entities in dead code results (default: false)',
+                },
+            },
+        },
+    },
+    {
+        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.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                group_by: {
+                    type: 'string',
+                    enum: ['module', 'layer'],
+                    description: 'Group entities by module or layer (default: module)',
+                },
+            },
+        },
+    },
+    {
+        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.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        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.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                weight_by_blast_radius: {
+                    type: 'boolean',
+                    description: 'Rank uncovered entities by blast radius to prioritize testing (default: false, slower)',
+                },
+            },
+        },
+    },
+    {
+        name: 'get_optimal_context',
+        description: 'Compute the optimal set of related entities to include in an LLM context window for a target entity. Uses greedy knapsack: maximizes relevance per token. Returns entities ranked by relevance with token estimates.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target_entity: {
+                    type: 'string',
+                    description: 'Entity ID or name to build context around',
+                },
+                max_tokens: {
+                    type: 'number',
+                    description: 'Token budget for the context window (default: 8000)',
+                },
+                strategy: {
+                    type: 'string',
+                    enum: ['bfs', 'blast_radius'],
+                    description: 'Traversal strategy: bfs (faster, local neighborhood) or blast_radius (full affected set)',
+                },
+            },
+            required: ['target_entity'],
+        },
+    },
 ];
 // ─── Server Setup ─────────────────────────────────────────────────
 async function main() {
@@ -177,7 +275,7 @@ async function main() {
     const entityCount = manifest?.entityCount || 0;
     const server = new Server({
         name: `seshat-mcp (${projectName})`,
-        version: '0.1.0',
+        version: '0.2.0',
     }, {
         capabilities: {
             tools: {},
@@ -227,6 +325,28 @@ async function main() {
                 case 'get_topology':
                     result = getTopology();
                     break;
+                // Interpretation Functors
+                case 'find_dead_code':
+                    result = findDeadCode(args);
+                    break;
+                case 'find_layer_violations':
+                    result = findLayerViolations();
+                    break;
+                case 'get_coupling_metrics':
+                    result = getCouplingMetrics(args);
+                    break;
+                case 'get_auth_matrix':
+                    result = getAuthMatrix();
+                    break;
+                case 'find_error_gaps':
+                    result = findErrorGaps();
+                    break;
+                case 'get_test_coverage':
+                    result = getTestCoverage(args);
+                    break;
+                case 'get_optimal_context':
+                    result = getOptimalContext(args);
+                    break;
                 default:
                     result = { error: `Unknown tool: ${name}` };
             }

package/dist/tools/functors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Interpretation Functor Tools
+ *
+ * Each functor is I: J -> D — projecting the 9D JSTF-T coordinate space
+ * onto a domain-specific judgment. These are composite analyses built
+ * from the primitive dimensions (sigma, epsilon, delta, kappa, chi, tau, rho).
+ */
+export declare function findDeadCode(args: {
+    include_tests?: boolean;
+}): unknown;
+export declare function findLayerViolations(): unknown;
+export declare function getCouplingMetrics(args: {
+    group_by?: 'module' | 'layer';
+}): unknown;
+export declare function getAuthMatrix(): unknown;
+export declare function findErrorGaps(): unknown;
+export declare function getTestCoverage(args: {
+    weight_by_blast_radius?: boolean;
+}): unknown;
+export declare function getOptimalContext(args: {
+    target_entity: string;
+    max_tokens?: number;
+    strategy?: 'bfs' | 'blast_radius';
+}): unknown;

package/dist/tools/functors.js

@@ -0,0 +1,533 @@
+/**
+ * Interpretation Functor Tools
+ *
+ * Each functor is I: J -> D — projecting the 9D JSTF-T coordinate space
+ * onto a domain-specific judgment. These are composite analyses built
+ * from the primitive dimensions (sigma, epsilon, delta, kappa, chi, tau, rho).
+ */
+import { computeBlastRadius } from '../graph.js';
+import { getLoader, getGraph, entityLayer, entitySummary, } from './index.js';
+// ─── Layer ordering for violation detection ──────────────────────
+const LAYER_ORDER = {
+    route: 0,
+    controller: 1,
+    middleware: 2,
+    service: 3,
+    hook: 4,
+    repository: 5,
+    model: 6,
+    schema: 7,
+    utility: 8,
+    component: 1, // UI components are peers to controllers
+};
+// ─── Functor 1: find_dead_code ───────────────────────────────────
+export function findDeadCode(args) {
+    const { include_tests = false } = args;
+    const loader = getLoader();
+    const g = getGraph();
+    const entities = loader.getEntities();
+    // Entry points: routes, exported functions, test files, plugin registrations
+    const entryPointIds = new Set();
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        const layer = entityLayer(e);
+        // Routes and controllers are entry points
+        if (layer === 'route' || layer === 'controller') {
+            entryPointIds.add(e.id);
+            continue;
+        }
+        // Test entities are entry points
+        if (layer === 'test') {
+            entryPointIds.add(e.id);
+            continue;
+        }
+        // Plugin registrations
+        if (e.context?.exposure === 'framework') {
+            entryPointIds.add(e.id);
+            continue;
+        }
+        // Exported functions at the top level are entry points
+        if (typeof e.struct !== 'string' && e.struct?.exported) {
+            entryPointIds.add(e.id);
+        }
+    }
+    // BFS from all entry points through callees
+    const reachable = new Set(entryPointIds);
+    const queue = [...entryPointIds];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const calleeSet = g.callees.get(current);
+        if (!calleeSet)
+            continue;
+        for (const calleeId of calleeSet) {
+            if (!reachable.has(calleeId)) {
+                reachable.add(calleeId);
+                queue.push(calleeId);
+            }
+        }
+    }
+    // Unreachable = dead code candidates
+    let deadEntities = entities.filter(e => e.id && !reachable.has(e.id));
+    if (!include_tests) {
+        deadEntities = deadEntities.filter(e => entityLayer(e) !== 'test');
+    }
+    // Group by layer for overview
+    const byLayer = new Map();
+    for (const e of deadEntities) {
+        const l = entityLayer(e);
+        byLayer.set(l, (byLayer.get(l) || 0) + 1);
+    }
+    return {
+        totalEntities: entities.length,
+        entryPoints: entryPointIds.size,
+        reachable: reachable.size,
+        deadCount: deadEntities.length,
+        deadByLayer: Object.fromEntries([...byLayer.entries()].sort((a, b) => b[1] - a[1])),
+        dead: deadEntities.slice(0, 100).map(entitySummary),
+    };
+}
+// ─── Functor 2: find_layer_violations ────────────────────────────
+export function findLayerViolations() {
+    const g = getGraph();
+    const violations = [];
+    for (const [callerId, calleeIds] of g.callees) {
+        const callerEntity = g.entityById.get(callerId);
+        if (!callerEntity)
+            continue;
+        const callerLayer = entityLayer(callerEntity);
+        const callerOrder = LAYER_ORDER[callerLayer];
+        if (callerOrder === undefined)
+            continue;
+        for (const calleeId of calleeIds) {
+            const calleeEntity = g.entityById.get(calleeId);
+            if (!calleeEntity)
+                continue;
+            const calleeLayer = entityLayer(calleeEntity);
+            const calleeOrder = LAYER_ORDER[calleeLayer];
+            if (calleeOrder === undefined)
+                continue;
+            // Skip same-layer calls
+            if (callerLayer === calleeLayer)
+                continue;
+            // Backward call: lower layer calling higher layer
+            if (callerOrder > calleeOrder) {
+                violations.push({
+                    from: entitySummary(callerEntity),
+                    to: entitySummary(calleeEntity),
+                    type: `backward: ${callerLayer}(${callerOrder}) -> ${calleeLayer}(${calleeOrder})`,
+                });
+            }
+            // Skip-layer: jumping over more than 1 layer
+            else if (calleeOrder - callerOrder > 2) {
+                violations.push({
+                    from: entitySummary(callerEntity),
+                    to: entitySummary(calleeEntity),
+                    type: `skip-layer: ${callerLayer}(${callerOrder}) -> ${calleeLayer}(${calleeOrder})`,
+                });
+            }
+        }
+    }
+    // Group violations by type
+    const byType = new Map();
+    for (const v of violations) {
+        const typePrefix = v.type.split(':')[0];
+        byType.set(typePrefix, (byType.get(typePrefix) || 0) + 1);
+    }
+    return {
+        totalViolations: violations.length,
+        byType: Object.fromEntries(byType),
+        violations: violations.slice(0, 100),
+    };
+}
+// ─── Functor 3: get_coupling_metrics ─────────────────────────────
+export function getCouplingMetrics(args) {
+    const { group_by = 'module' } = args;
+    const loader = getLoader();
+    const g = getGraph();
+    const entities = loader.getEntities();
+    // Group entities
+    const groups = new Map();
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        const key = group_by === 'module'
+            ? (e.context?.module || 'unknown')
+            : entityLayer(e);
+        if (!groups.has(key))
+            groups.set(key, new Set());
+        groups.get(key).add(e.id);
+    }
+    const metrics = [];
+    for (const [groupName, memberIds] of groups) {
+        let internalEdges = 0;
+        let outgoingEdges = 0;
+        let incomingEdges = 0;
+        for (const memberId of memberIds) {
+            const calleeSet = g.callees.get(memberId);
+            if (calleeSet) {
+                for (const calleeId of calleeSet) {
+                    if (memberIds.has(calleeId)) {
+                        internalEdges++;
+                    }
+                    else {
+                        outgoingEdges++;
+                    }
+                }
+            }
+            const callerSet = g.callers.get(memberId);
+            if (callerSet) {
+                for (const callerId of callerSet) {
+                    if (!memberIds.has(callerId)) {
+                        incomingEdges++;
+                    }
+                }
+            }
+        }
+        const size = memberIds.size;
+        const maxInternalEdges = size * (size - 1); // directed
+        const cohesion = maxInternalEdges > 0 ? internalEdges / maxInternalEdges : 0;
+        const totalExternal = outgoingEdges + incomingEdges;
+        const coupling = totalExternal;
+        const instability = totalExternal > 0 ? outgoingEdges / totalExternal : 0;
+        metrics.push({
+            group: groupName,
+            size,
+            internalEdges,
+            externalEdges: totalExternal,
+            cohesion: Math.round(cohesion * 1000) / 1000,
+            coupling,
+            instability: Math.round(instability * 1000) / 1000,
+        });
+    }
+    // Sort by coupling (most coupled first)
+    metrics.sort((a, b) => b.coupling - a.coupling);
+    return {
+        groupBy: group_by,
+        groupCount: metrics.length,
+        metrics: metrics.slice(0, 50),
+    };
+}
+// ─── Functor 4: get_auth_matrix ──────────────────────────────────
+export function getAuthMatrix() {
+    const loader = getLoader();
+    const entities = loader.getEntities();
+    const apiEntities = entities.filter(e => {
+        const layer = entityLayer(e);
+        return layer === 'route' || layer === 'controller' ||
+            e.context?.exposure === 'api';
+    });
+    const withAuth = [];
+    const withoutAuth = [];
+    const inconsistencies = [];
+    for (const e of apiEntities) {
+        const constraints = e.constraints;
+        const hasAuth = constraints && !Array.isArray(constraints) &&
+            constraints.auth && constraints.auth !== 'none';
+        const summary = entitySummary(e);
+        if (hasAuth) {
+            withAuth.push({
+                ...summary,
+                auth: constraints.auth,
+            });
+        }
+        else {
+            withoutAuth.push(summary);
+        }
+        // Check for inconsistencies: has auth decorator but marked as public
+        if (hasAuth && e.context?.visibility === 'public') {
+            inconsistencies.push({
+                entity: summary,
+                issue: 'Has auth requirements but visibility is public',
+            });
+        }
+        // Has DB access but no auth
+        if (!hasAuth) {
+            const sideEffects = constraints && !Array.isArray(constraints)
+                ? constraints.sideEffects : undefined;
+            if (Array.isArray(sideEffects) && sideEffects.some((s) => s === 'db' || s === 'database')) {
+                inconsistencies.push({
+                    entity: summary,
+                    issue: 'DB access without auth — potential security gap',
+                });
+            }
+        }
+    }
+    return {
+        totalApiEntities: apiEntities.length,
+        withAuth: withAuth.length,
+        withoutAuth: withoutAuth.length,
+        inconsistencies: inconsistencies.length,
+        authenticated: withAuth.slice(0, 50),
+        unauthenticated: withoutAuth.slice(0, 50),
+        issues: inconsistencies.slice(0, 50),
+    };
+}
+// ─── Functor 5: find_error_gaps ──────────────────────────────────
+export function findErrorGaps() {
+    const loader = getLoader();
+    const g = getGraph();
+    const entities = loader.getEntities();
+    // Find all fallible entities (throws === true or has THROWS tag)
+    const fallibleIds = new Set();
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        // Check kappa.throws
+        const constraints = e.constraints;
+        if (constraints && !Array.isArray(constraints) && constraints.throws) {
+            fallibleIds.add(e.id);
+            continue;
+        }
+        // Check tau.self.fallible
+        const traits = e.traits;
+        if (traits && !Array.isArray(traits) && traits.self?.fallible) {
+            fallibleIds.add(e.id);
+            continue;
+        }
+        // Check for network/db side effects (implicitly fallible)
+        if (constraints && !Array.isArray(constraints) && Array.isArray(constraints.sideEffects)) {
+            const effects = constraints.sideEffects;
+            if (effects.some((s) => s === 'network' || s === 'db' || s === 'database' || s === 'filesystem' || s === 'fs')) {
+                fallibleIds.add(e.id);
+            }
+        }
+    }
+    // Find callers of fallible entities that lack error handling
+    const gaps = [];
+    for (const fallibleId of fallibleIds) {
+        const callerSet = g.callers.get(fallibleId);
+        if (!callerSet)
+            continue;
+        const fallibleEntity = g.entityById.get(fallibleId);
+        if (!fallibleEntity)
+            continue;
+        for (const callerId of callerSet) {
+            const callerEntity = g.entityById.get(callerId);
+            if (!callerEntity)
+                continue;
+            // Check if caller has error handling
+            const callerConstraints = callerEntity.constraints;
+            const hasErrorHandling = callerConstraints && !Array.isArray(callerConstraints) &&
+                callerConstraints.errorHandling &&
+                (callerConstraints.errorHandling.tryCatch || callerConstraints.errorHandling.catchClause);
+            if (!hasErrorHandling) {
+                gaps.push({
+                    caller: entitySummary(callerEntity),
+                    fallibleCallee: entitySummary(fallibleEntity),
+                    issue: 'Calls fallible function without try/catch',
+                });
+            }
+        }
+    }
+    return {
+        totalFallible: fallibleIds.size,
+        errorGaps: gaps.length,
+        gaps: gaps.slice(0, 100),
+    };
+}
+// ─── Functor 6: get_test_coverage ────────────────────────────────
+export function getTestCoverage(args) {
+    const { weight_by_blast_radius = false } = args;
+    const loader = getLoader();
+    const g = getGraph();
+    const entities = loader.getEntities();
+    // Partition into test and non-test entities
+    const testIds = new Set();
+    const productionEntities = [];
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        if (entityLayer(e) === 'test') {
+            testIds.add(e.id);
+        }
+        else {
+            productionEntities.push(e);
+        }
+    }
+    // BFS from test entities through callees to find what they exercise
+    const exercised = new Set();
+    const queue = [...testIds];
+    const visited = new Set(testIds);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const calleeSet = g.callees.get(current);
+        if (!calleeSet)
+            continue;
+        for (const calleeId of calleeSet) {
+            if (!visited.has(calleeId)) {
+                visited.add(calleeId);
+                if (!testIds.has(calleeId)) {
+                    exercised.add(calleeId);
+                }
+                queue.push(calleeId);
+            }
+        }
+    }
+    const covered = productionEntities.filter(e => exercised.has(e.id));
+    const uncovered = productionEntities.filter(e => !exercised.has(e.id));
+    const result = {
+        totalProduction: productionEntities.length,
+        totalTests: testIds.size,
+        coveredCount: covered.length,
+        uncoveredCount: uncovered.length,
+        coveragePercent: productionEntities.length > 0
+            ? Math.round((covered.length / productionEntities.length) * 1000) / 10
+            : 0,
+    };
+    if (weight_by_blast_radius && uncovered.length > 0) {
+        // Compute blast radius for each uncovered entity to prioritize what to test
+        const prioritized = uncovered
+            .map(e => {
+            const br = computeBlastRadius(g, new Set([e.id]));
+            return {
+                ...entitySummary(e),
+                blastRadius: br.affected.length,
+            };
+        })
+            .sort((a, b) => b.blastRadius - a.blastRadius);
+        result.uncoveredByPriority = prioritized.slice(0, 50);
+    }
+    else {
+        // Group uncovered by layer
+        const byLayer = new Map();
+        for (const e of uncovered) {
+            const l = entityLayer(e);
+            byLayer.set(l, (byLayer.get(l) || 0) + 1);
+        }
+        result.uncoveredByLayer = Object.fromEntries([...byLayer.entries()].sort((a, b) => b[1] - a[1]));
+        result.uncovered = uncovered.slice(0, 50).map(entitySummary);
+    }
+    return result;
+}
+// ─── Functor 7: get_optimal_context ──────────────────────────────
+export function getOptimalContext(args) {
+    const { target_entity, max_tokens = 8000, strategy = 'bfs' } = args;
+    const loader = getLoader();
+    const g = getGraph();
+    const entity = loader.getEntityById(target_entity) || loader.getEntityByName(target_entity);
+    if (!entity) {
+        return { error: `Entity not found: ${target_entity}` };
+    }
+    const targetId = entity.id;
+    // Estimate tokens for an entity based on its dimensions
+    function estimateTokens(e) {
+        let tokens = 50; // Base: name, id, layer
+        if (e.struct && typeof e.struct !== 'string') {
+            tokens += 20; // signature
+            tokens += (e.struct.params?.length || 0) * 10;
+        }
+        if (e.edges?.calls)
+            tokens += e.edges.calls.length * 8;
+        if (e.edges?.imports)
+            tokens += e.edges.imports.length * 6;
+        if (e.data?.inputs)
+            tokens += e.data.inputs.length * 10;
+        if (e.constraints && typeof e.constraints === 'object' && !Array.isArray(e.constraints)) {
+            tokens += 30;
+        }
+        return tokens;
+    }
+    const candidates = [];
+    if (strategy === 'blast_radius') {
+        // Use blast radius to get all related entities with depth
+        const br = computeBlastRadius(g, new Set([targetId]));
+        for (const id of br.affected) {
+            if (id === targetId)
+                continue;
+            const e = g.entityById.get(id);
+            if (!e)
+                continue;
+            const depth = Math.abs(br.depthMap[id] || 99);
+            const tokens = estimateTokens(e);
+            // Relevance decays with distance; direct callers/callees are most valuable
+            const relevance = 1 / (1 + depth);
+            candidates.push({
+                entity: entitySummary(e),
+                relevance: Math.round(relevance * 1000) / 1000,
+                distance: depth,
+                direction: (br.depthMap[id] || 0) < 0 ? 'upstream' : 'downstream',
+                tokens,
+            });
+        }
+    }
+    else {
+        // BFS from target in both directions with distance tracking
+        const distances = new Map();
+        // BFS callees (downstream)
+        const downQueue = [[targetId, 0]];
+        const downVisited = new Set([targetId]);
+        while (downQueue.length > 0) {
+            const [current, d] = downQueue.shift();
+            if (d > 5)
+                continue;
+            const calleeSet = g.callees.get(current);
+            if (!calleeSet)
+                continue;
+            for (const id of calleeSet) {
+                if (!downVisited.has(id)) {
+                    downVisited.add(id);
+                    distances.set(id, { dist: d + 1, dir: 'downstream' });
+                    downQueue.push([id, d + 1]);
+                }
+            }
+        }
+        // BFS callers (upstream)
+        const upQueue = [[targetId, 0]];
+        const upVisited = new Set([targetId]);
+        while (upQueue.length > 0) {
+            const [current, d] = upQueue.shift();
+            if (d > 5)
+                continue;
+            const callerSet = g.callers.get(current);
+            if (!callerSet)
+                continue;
+            for (const id of callerSet) {
+                if (!upVisited.has(id)) {
+                    upVisited.add(id);
+                    // Only override if not already found with shorter distance
+                    if (!distances.has(id) || distances.get(id).dist > d + 1) {
+                        distances.set(id, { dist: d + 1, dir: 'upstream' });
+                    }
+                    upQueue.push([id, d + 1]);
+                }
+            }
+        }
+        for (const [id, { dist, dir }] of distances) {
+            const e = g.entityById.get(id);
+            if (!e)
+                continue;
+            const tokens = estimateTokens(e);
+            const relevance = 1 / (1 + dist);
+            candidates.push({
+                entity: entitySummary(e),
+                relevance: Math.round(relevance * 1000) / 1000,
+                distance: dist,
+                direction: dir,
+                tokens,
+            });
+        }
+    }
+    // Greedy knapsack: sort by relevance/token ratio, fill until budget
+    candidates.sort((a, b) => (b.relevance / b.tokens) - (a.relevance / a.tokens));
+    const selected = [];
+    const targetTokens = estimateTokens(entity);
+    let usedTokens = targetTokens; // Reserve space for the target itself
+    for (const candidate of candidates) {
+        if (usedTokens + candidate.tokens > max_tokens)
+            continue;
+        selected.push(candidate);
+        usedTokens += candidate.tokens;
+    }
+    return {
+        target: {
+            ...entitySummary(entity),
+            tokens: targetTokens,
+        },
+        maxTokens: max_tokens,
+        usedTokens,
+        contextEntities: selected.length,
+        totalCandidates: candidates.length,
+        context: selected,
+    };
+}

package/dist/tools/index.d.ts

@@ -4,8 +4,21 @@
  * Each tool exposes a dimension or computation over the 9D JSTF-T coordinate space.
  * Tools operate on the in-memory entity bundle loaded from .seshat/_bundle.json.
  */
+import type { JstfEntity } from '../types.js';
 import { BundleLoader } from '../loader.js';
+import { type CallGraph } from '../graph.js';
 export declare function initTools(bundleLoader: BundleLoader): void;
+export declare function getLoader(): BundleLoader;
+export declare function getGraph(): CallGraph;
+export declare function entityName(e: JstfEntity): string;
+export declare function entityLayer(e: JstfEntity): string;
+export declare function entitySummary(e: JstfEntity): Record<string, unknown>;
+export declare function normalizeConstraints(constraints: JstfEntity['constraints']): string[];
+/**
+ * Deep search constraints — matches against raw constraint object fields too,
+ * not just normalized tags.
+ */
+export declare function constraintMatches(constraints: JstfEntity['constraints'], target: string): boolean;
 export declare function queryEntities(args: {
     query?: string;
     layer?: string;
@@ -21,6 +34,7 @@ export declare function getDependencies(args: {
     direction?: 'callers' | 'callees' | 'both';
     depth?: number;
 }): unknown;
+export declare function collectTransitive(adjacency: Map<string, Set<string>>, startId: string, maxDepth: number): string[];
 export declare function getDataFlow(args: {
     entity_id: string;
 }): unknown;

package/dist/tools/index.js

@@ -12,19 +12,22 @@ export function initTools(bundleLoader) {
     loader = bundleLoader;
     graph = null; // Reset graph cache when loader changes
 }
-function getGraph() {
+export function getLoader() {
+    return loader;
+}
+export function getGraph() {
     if (!graph) {
         graph = buildCallGraph(loader.getEntities());
     }
     return graph;
 }
 // ─── Helper: Extract entity name from struct ─────────────────────
-function entityName(e) {
+export function entityName(e) {
     if (typeof e.struct === 'string')
         return e.struct;
     return e.struct?.name || e.id || 'anonymous';
 }
-function entityLayer(e) {
+export function entityLayer(e) {
     // Use explicit layer if specific enough
     const explicit = e.context?.layer?.toLowerCase();
     if (explicit && explicit !== 'module' && explicit !== 'unknown')
@@ -55,7 +58,7 @@ function entityLayer(e) {
         return 'test';
     return explicit || 'other';
 }
-function entitySummary(e) {
+export function entitySummary(e) {
     const constraintTags = normalizeConstraints(e.constraints);
     return {
         id: e.id,
@@ -70,7 +73,7 @@ function entitySummary(e) {
         callCount: Array.isArray(e.edges?.calls) ? e.edges.calls.length : 0,
     };
 }
-function normalizeConstraints(constraints) {
+export function normalizeConstraints(constraints) {
     if (!constraints)
         return [];
     if (Array.isArray(constraints))
@@ -124,7 +127,7 @@ function normalizeConstraints(constraints) {
  * Deep search constraints — matches against raw constraint object fields too,
  * not just normalized tags.
  */
-function constraintMatches(constraints, target) {
+export function constraintMatches(constraints, target) {
     // First check normalized tags
     const tags = normalizeConstraints(constraints);
     if (tags.some(t => t.toUpperCase().includes(target.toUpperCase())))
@@ -226,7 +229,7 @@ export function getDependencies(args) {
     }
     return result;
 }
-function collectTransitive(adjacency, startId, maxDepth) {
+export function collectTransitive(adjacency, startId, maxDepth) {
     const visited = new Set();
     const queue = [[startId, 0]];
     visited.add(startId);

package/dist/types.d.ts

@@ -55,6 +55,7 @@ export interface JstfEntity {
             target: string;
             operation?: string;
         }>;
+        tables?: string[];
         sources?: unknown[];
         returns?: unknown[];
         [key: string]: unknown;
@@ -67,14 +68,27 @@ export interface JstfEntity {
             field: string;
             rule: string;
         }>;
+        auth?: string[] | 'none';
+        authRequired?: boolean;
+        purity?: string;
+        throws?: boolean;
+        sideEffects?: string[];
+        errorHandling?: {
+            tryCatch?: boolean;
+            catchClause?: boolean;
+            finally?: boolean;
+            errorBoundary?: boolean;
+        };
         [key: string]: unknown;
     } | string[];
     /** χ — Context: architectural position, visibility, layer */
     context?: {
         layer?: string;
+        layerSource?: string;
         module?: string;
         path?: string;
         exposure?: string;
+        visibility?: string;
         traffic?: string;
         criticality?: string;
         [key: string]: unknown;
@@ -82,7 +96,18 @@ export interface JstfEntity {
     /** λ — Ownership: memory ownership, lifetimes, borrowing */
     ownership?: Record<string, unknown>;
     /** τ — Traits: type capabilities, bounds, markers */
-    traits?: string[] | Record<string, unknown>;
+    traits?: string[] | {
+        self?: {
+            asyncContext?: boolean;
+            fallible?: boolean;
+            [key: string]: unknown;
+        };
+        params?: Record<string, {
+            bounds?: string[];
+            markers?: string[];
+        }>;
+        [key: string]: unknown;
+    };
     /** ρ — Runtime: reactive model, async platform, framework */
     runtime?: {
         async?: string;

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.1.0",
-  "description": "Semantic MCP server — exposes a codebase's 9D JSTF-T coordinate space as queryable tools",
-  "type": "module",
-  "bin": {
-    "seshat-mcp": "./dist/index.js"
-  },
-  "main": "./dist/index.js",
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1"
-  },
-  "devDependencies": {
-    "typescript": "^5.5.0",
-    "@types/node": "^20.0.0"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "files": [
-    "dist/"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/papyruslabs-ai/seshat.git",
-    "directory": "packages/seshat-mcp"
-  },
-  "keywords": ["mcp", "jstf", "semantic", "code-analysis", "seshat"],
-  "license": "MIT"
-}
+{
+  "name": "@papyruslabsai/seshat-mcp",
+  "version": "0.2.0",
+  "description": "Semantic MCP server — exposes a codebase's 9D JSTF-T coordinate space as queryable tools",
+  "type": "module",
+  "bin": {
+    "seshat-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/papyruslabs-ai/seshat.git",
+    "directory": "packages/seshat-mcp"
+  },
+  "keywords": ["mcp", "jstf", "semantic", "code-analysis", "seshat"],
+  "license": "MIT"
+}