@papyruslabsai/seshat-mcp 0.19.0 → 0.20.0

package/dist/index.js

@@ -341,6 +341,31 @@ const TOOLS = [
         },
         annotations: READ_ONLY_OPEN,
     },
+    {
+        name: 'find_entry_points',
+        title: 'Find Entry Points',
+        description: 'List the ways into the system: route/controller handlers, test entries, framework plugin registrations, and exported symbols (the public API surface), classified by kind and ranked by reach. Call it first when orienting in an unfamiliar codebase — it answers "where does execution start, and what is the public surface?" Complements list_modules (structure) and find_dead_code (its exact inverse: these are the reachability roots).',
+        inputSchema: {
+            type: 'object',
+            properties: { project: projectParam },
+        },
+        annotations: READ_ONLY_OPEN,
+    },
+    {
+        name: 'trace_data_path',
+        title: 'Trace Data Path',
+        description: 'Follow data from one function through the call graph to its sinks. From a start entity it walks callees, records the data each hop consumes/produces/mutates, and reports the chain from the start to every sink the data reaches — database writes, network egress, filesystem writes — plus the tables touched. Call it before changing a function that handles real data: it answers "where does this data end up?", the cross-call composition get_data_flow (one entity) cannot give. Flags untrusted inputs at the source.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                entity_id: { type: 'string', description: 'Entity ID or name to trace data flow from' },
+                max_depth: { type: 'number', description: 'How many call hops to follow downstream (default: 5, max: 8)' },
+            },
+            required: ['entity_id'],
+        },
+        annotations: READ_ONLY_OPEN,
+    },
     // ─── Analyst Tools (Tier 2) ───────────────────────────────────────
     {
         name: 'find_dead_code',
@@ -415,13 +440,9 @@ const TOOLS = [
         },
         annotations: READ_ONLY_OPEN,
     },
-    {
-        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,
-    },
+    // find_runtime_violations RETIRED 2026-06-12 (BUILD-LIST B1): built against
+    // the v1 runtime-tagging model; the server now answers it with an honest
+    // retirement notice for old clients. Discipline-aware rebuild planned.
     {
         name: 'find_ownership_violations',
         title: 'Find Ownership Violations',
@@ -631,7 +652,7 @@ function getCloudUrl(path) {
 async function main() {
     const server = new Server({
         name: 'seshat',
-        version: '0.16.10',
+        version: '0.20.0',
     }, {
         capabilities: { tools: {} },
         instructions: SERVER_INSTRUCTIONS,

package/dist/tools/functors.d.ts

@@ -16,6 +16,32 @@ export declare function findDeadCode(args: {
     include_tests?: boolean;
     project?: string;
 }, loader: ProjectLoader): unknown;
+/**
+ * The ways into the system — the reachability roots find_dead_code already
+ * computes, surfaced as a tool and classified by KIND. An entry point is a
+ * route/controller, a test, a framework plugin registration, or an exported
+ * symbol (the library's public API surface). entryPointCount here reconciles
+ * with find_dead_code's `entryPoints` (same seed definition).
+ */
+export declare function findEntryPoints(args: {
+    project?: string;
+}, loader: ProjectLoader): unknown;
+/**
+ * Follow data from one entity through the call graph to its sinks. Composes
+ * the data dimension (inputs/outputs/mutations/db) with call edges: from a
+ * start entity, walk callees up to max_depth, record the data ops at each hop,
+ * and report the chain from the start to every sink it reaches (db write,
+ * network egress, fs write). Answers "I'm touching this function — where does
+ * its data end up?" — the cross-edge composition get_data_flow can't give for
+ * a single entity. Pairs with trace_boundaries (observability) and
+ * query_data_targets (who-touches-a-target); this one is the path itself.
+ */
+export declare function traceDataPath(args: {
+    entity?: string;
+    entity_id?: string;
+    project?: string;
+    max_depth?: number;
+}, loader: ProjectLoader): unknown;
 export declare function findLayerViolations(args: {
     project?: string;
 }, loader: ProjectLoader): unknown;

package/dist/tools/functors.js

@@ -7,7 +7,7 @@
  */
 import path from 'path';
 import { computeBlastRadius } from '../graph.js';
-import { getGraph, validateProject, entityName, entityLayer, entitySummary, } from './index.js';
+import { getGraph, validateProject, entityName, entityLayer, entitySummary, normalizeConstraints, } from './index.js';
 import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, } from '../supabase.js';
 import { extractDbOps } from './dbops.js';
 // ─── Layer ordering for violation detection ──────────────────────
@@ -164,6 +164,166 @@ export function findDeadCode(args, loader) {
         } : {}),
     };
 }
+// ─── Tool: find_entry_points (B6) ────────────────────────────────
+/**
+ * The ways into the system — the reachability roots find_dead_code already
+ * computes, surfaced as a tool and classified by KIND. An entry point is a
+ * route/controller, a test, a framework plugin registration, or an exported
+ * symbol (the library's public API surface). entryPointCount here reconciles
+ * with find_dead_code's `entryPoints` (same seed definition).
+ */
+export function findEntryPoints(args, loader) {
+    const projErr = validateProject(args.project, loader);
+    if (projErr)
+        return { error: projErr };
+    const g = getGraph(args.project, loader);
+    const entities = loader.getEntities(args.project);
+    // route/controller first (runtime entries), then plugins, tests, exports.
+    const KIND_RANK = { route: 0, plugin: 1, test: 2, export: 3 };
+    const entryPoints = [];
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        const layer = entityLayer(e);
+        let kind = null;
+        if (layer === 'route' || layer === 'controller')
+            kind = 'route';
+        else if (layer === 'test')
+            kind = 'test';
+        else if (e.context?.exposure === 'framework')
+            kind = 'plugin';
+        else if (typeof e.struct !== 'string' && e.struct?.exported)
+            kind = 'export';
+        if (!kind)
+            continue;
+        entryPoints.push({ ...entitySummary(e), kind, directCallees: g.callees.get(e.id)?.size || 0 });
+    }
+    const byKind = {};
+    for (const ep of entryPoints)
+        byKind[ep.kind] = (byKind[ep.kind] || 0) + 1;
+    entryPoints.sort((a, b) => (KIND_RANK[a.kind] - KIND_RANK[b.kind]) ||
+        (b.directCallees - a.directCallees));
+    return {
+        totalEntities: entities.length,
+        entryPointCount: entryPoints.length,
+        byKind,
+        entryPoints: entryPoints.slice(0, 100),
+    };
+}
+// ─── Tool: trace_data_path (B6, δ×ε compose) ─────────────────────
+/**
+ * Follow data from one entity through the call graph to its sinks. Composes
+ * the data dimension (inputs/outputs/mutations/db) with call edges: from a
+ * start entity, walk callees up to max_depth, record the data ops at each hop,
+ * and report the chain from the start to every sink it reaches (db write,
+ * network egress, fs write). Answers "I'm touching this function — where does
+ * its data end up?" — the cross-edge composition get_data_flow can't give for
+ * a single entity. Pairs with trace_boundaries (observability) and
+ * query_data_targets (who-touches-a-target); this one is the path itself.
+ */
+export function traceDataPath(args, loader) {
+    const projErr = validateProject(args.project, loader);
+    if (projErr)
+        return { error: projErr };
+    const ref = args.entity_id || args.entity;
+    if (!ref)
+        return { error: 'trace_data_path requires an entity (id or name)' };
+    const start = loader.getEntityById(ref, args.project) || loader.getEntityByName(ref, args.project);
+    if (!start || !start.id)
+        return { error: `Entity not found: ${ref}` };
+    const g = getGraph(args.project, loader);
+    const maxDepth = Math.min(Math.max(args.max_depth ?? 5, 1), 8);
+    const dataOf = (e) => {
+        const arr = (v) => (Array.isArray(v) ? v : []);
+        const data = (e.data || {});
+        const inputs = arr(data.inputs).length ? arr(data.inputs) : arr(data.sources);
+        const untrusted = inputs.filter((i) => i && typeof i === 'object' && i.untrusted).length;
+        const tags = normalizeConstraints(e.constraints);
+        const egress = [];
+        if (tags.includes('NETWORK_IO'))
+            egress.push('network');
+        if (tags.includes('FS_ACCESS'))
+            egress.push('fs');
+        return {
+            in: inputs.length,
+            out: (arr(data.outputs).length ? arr(data.outputs) : arr(data.returns)).length,
+            mut: arr(data.mutations).length,
+            untrusted,
+            db: extractDbOps(e).map((o) => ({ table: o.table, op: o.type === 'db_mutate' ? 'write' : 'read' })),
+            egress,
+        };
+    };
+    // A node is a sink when data leaves the program through it.
+    const sinkKind = (d) => {
+        if (d.db.some((o) => o.op === 'write'))
+            return 'db-write';
+        if (d.egress.includes('network'))
+            return 'network';
+        if (d.egress.includes('fs'))
+            return 'fs';
+        return null;
+    };
+    // BFS downstream over callees; keep one parent per node to reconstruct paths.
+    const nodes = new Map();
+    const order = [];
+    const queue = [[start.id, 0, null]];
+    const seen = new Set([start.id]);
+    while (queue.length > 0) {
+        const [id, depth, parent] = queue.shift();
+        const e = g.entityById.get(id);
+        if (!e)
+            continue;
+        const data = dataOf(e);
+        nodes.set(id, { entity: e, data, depth, parent, sink: sinkKind(data) });
+        order.push(id);
+        if (depth >= maxDepth)
+            continue;
+        for (const callee of g.callees.get(id) || []) {
+            if (!seen.has(callee)) {
+                seen.add(callee);
+                queue.push([callee, depth + 1, id]);
+            }
+        }
+    }
+    const pathTo = (id) => {
+        const chain = [];
+        let cur = id;
+        const guard = new Set();
+        while (cur != null && !guard.has(cur)) {
+            guard.add(cur);
+            chain.unshift(cur);
+            cur = nodes.get(cur)?.parent ?? null;
+        }
+        return chain;
+    };
+    const sinkIds = order.filter((id) => nodes.get(id).sink);
+    const chainNode = (id) => {
+        const n = nodes.get(id);
+        return { ...entitySummary(n.entity), depth: n.depth, data: n.data, sink: n.sink };
+    };
+    const paths = sinkIds.slice(0, 30).map((id) => ({
+        sinkKind: nodes.get(id).sink,
+        chain: pathTo(id).map(chainNode),
+    }));
+    const tableOps = new Map();
+    for (const id of order) {
+        for (const op of nodes.get(id).data.db) {
+            if (!tableOps.has(op.table))
+                tableOps.set(op.table, new Set());
+            tableOps.get(op.table).add(op.op);
+        }
+    }
+    return {
+        entity: { id: start.id, name: entityName(start) },
+        maxDepth,
+        reached: Math.max(0, order.length - 1),
+        sinkCount: sinkIds.length,
+        untrustedAtSource: nodes.get(start.id).data.untrusted,
+        tables: [...tableOps.entries()].map(([table, ops]) => ({ table, ops: [...ops].sort() })),
+        paths,
+        pathsTruncated: sinkIds.length > 30 ? sinkIds.length - 30 : 0,
+    };
+}
 // ─── Tool: find_layer_violations ─────────────────────────────────
 export function findLayerViolations(args, loader) {
     const projErr = validateProject(args?.project, loader);

package/package.json

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