@papyruslabsai/seshat-mcp 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,29 +1 @@
-#!/usr/bin/env node
-/**
- * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server
- *
- * 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.
- *   In multi-project mode, all tools require a `project` parameter.
- *   Use `list_projects` to see available projects.
- *
- * Single-project mode (default):
- *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
- *
- * 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)
- *   SESHAT_PROJECTS=/path/a,/path/b npx @papyruslabs/seshat-mcp  # multi-project
- *   SESHAT_PROJECTS="/home/user/projects/*" npx @papyruslabs/seshat-mcp  # glob
- */
 export {};

package/dist/index.js

@@ -1,4 +1,5 @@
-#!/usr/bin/env node
+!/usr/bin / env;
+node;
 /**
  * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server
  *
@@ -33,7 +34,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 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 { logTelemetry, isSupabaseConfigured } from './supabase.js';
+import { 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, simulate_mutation, query_data_targets, find_exposure_leaks, find_semantic_clones, create_symbol, } from './tools/functors.js';
 import { diffBundle, conflictMatrix, } from './tools/diff.js';
 // ─── Project Discovery ───────────────────────────────────────────
@@ -647,6 +649,7 @@ async function main() {
     // Handle tool calls
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
+        const startTime = Date.now();
         try {
             if (!loader.isLoaded()) {
                 return {
@@ -659,8 +662,7 @@ async function main() {
                 };
             }
             let result;
-            switch (name) {
-                // Meta
+            switch (name) { // Meta
                 case 'list_projects':
                     result = {
                         multiProject: isMulti,
@@ -759,6 +761,21 @@ async function main() {
                 default:
                     result = { error: `Unknown tool: ${name}` };
             }
+            // Log telemetry for the tool execution
+            if (isSupabaseConfigured() && name !== 'list_projects') {
+                const executionMs = Date.now() - startTime;
+                const projectHash = args && typeof args === 'object' && 'project' in args
+                    ? String(args.project)
+                    : loader.getProjectNames()[0] || 'unknown';
+                // Fire-and-forget telemetry log
+                logTelemetry({
+                    tool_name: name,
+                    project_hash: projectHash,
+                    execution_ms: executionMs,
+                    // user_id will be added by the Ptah API gateway if passing through there,
+                    // or stay null if running strictly local CLI without an injected token.
+                }).catch(() => { });
+            }
             return {
                 content: [{
                         type: 'text',

package/dist/loader.d.ts

@@ -4,14 +4,20 @@
  * Discovers and loads .seshat/_bundle.json from the current working directory.
  * Falls back to checking common alternative locations.
  */
-import type { JstfEntity, Topology, Manifest, ProjectInfo } from './types.js';
+import type { JstfEntity, Topology, Manifest, ProjectInfo, ProjectLoader } from './types.js';
 export declare class BundleLoader {
     private entities;
     private topology;
     private manifest;
     private loaded;
     private seshatDir;
+    private bundleMtime;
     constructor(cwd?: string);
+    /**
+     * Check if the bundle file on disk has changed since last load.
+     * If so, reload transparently. Called by all accessors.
+     */
+    private ensureFresh;
     load(): void;
     getEntities(): JstfEntity[];
     getTopology(): Topology | null;
@@ -25,7 +31,7 @@ export declare class BundleLoader {
  * In single-project mode (1 dir), behaves identically to BundleLoader.
  * In multi-project mode, `project` param is required on all accessors.
  */
-export declare class MultiLoader {
+export declare class MultiLoader implements ProjectLoader {
     private projects;
     private projectPaths;
     private projectEntities;
@@ -33,6 +39,7 @@ export declare class MultiLoader {
     private dirs;
     constructor(projectDirs: string[]);
     load(): void;
+    private loadProject;
     /** Get the resolved project name when only one project is loaded. */
     private defaultProject;
     private resolveProject;

package/dist/loader.js

@@ -12,10 +12,32 @@ export class BundleLoader {
     manifest = null;
     loaded = false;
     seshatDir;
+    bundleMtime = 0;
     constructor(cwd) {
         const root = cwd || process.cwd();
         this.seshatDir = path.join(root, '.seshat');
     }
+    /**
+     * Check if the bundle file on disk has changed since last load.
+     * If so, reload transparently. Called by all accessors.
+     */
+    ensureFresh() {
+        if (!this.loaded) {
+            this.load();
+            return;
+        }
+        const bundlePath = path.join(this.seshatDir, '_bundle.json');
+        try {
+            const currentMtime = fs.statSync(bundlePath).mtimeMs;
+            if (currentMtime !== this.bundleMtime) {
+                process.stderr.write(`[seshat] Bundle changed on disk, reloading…\n`);
+                this.load();
+            }
+        }
+        catch {
+            // File may have been deleted — keep stale data rather than crash
+        }
+    }
     load() {
         const bundlePath = path.join(this.seshatDir, '_bundle.json');
         if (!fs.existsSync(bundlePath)) {
@@ -24,6 +46,7 @@ export class BundleLoader {
                 `  node ci/extract-and-generate.mjs <repo-path> .seshat <project-name>\n` +
                 `Or add the CI workflow to auto-generate on push to main.`);
         }
+        this.bundleMtime = fs.statSync(bundlePath).mtimeMs;
         const raw = fs.readFileSync(bundlePath, 'utf-8');
         const bundle = JSON.parse(raw);
         this.entities = bundle.entities || [];
@@ -52,18 +75,15 @@ export class BundleLoader {
         this.loaded = true;
     }
     getEntities() {
-        if (!this.loaded)
-            this.load();
+        this.ensureFresh();
         return this.entities;
     }
     getTopology() {
-        if (!this.loaded)
-            this.load();
+        this.ensureFresh();
         return this.topology;
     }
     getManifest() {
-        if (!this.loaded)
-            this.load();
+        this.ensureFresh();
         return this.manifest;
     }
     getEntityById(id) {
@@ -96,26 +116,29 @@ export class MultiLoader {
     }
     load() {
         for (const dir of this.dirs) {
-            const loader = new BundleLoader(dir);
-            try {
-                loader.load();
-                const manifest = loader.getManifest();
-                const name = manifest?.projectName || path.basename(dir);
-                this.projects.set(name, loader);
-                this.projectPaths.set(name, dir);
-                // Stamp entities with _project
-                const entities = loader.getEntities();
-                for (const e of entities) {
-                    e._project = name;
-                }
-                this.projectEntities.set(name, entities);
-            }
-            catch (err) {
-                process.stderr.write(`Warning: Skipping ${dir}: ${err.message}\n`);
-            }
+            this.loadProject(dir);
         }
         this.loaded = true;
     }
+    loadProject(dir) {
+        const loader = new BundleLoader(dir);
+        try {
+            loader.load();
+            const manifest = loader.getManifest();
+            const name = manifest?.projectName || path.basename(dir);
+            this.projects.set(name, loader);
+            this.projectPaths.set(name, dir);
+            // Stamp entities with _project
+            const entities = loader.getEntities();
+            for (const e of entities) {
+                e._project = name;
+            }
+            this.projectEntities.set(name, entities);
+        }
+        catch (err) {
+            process.stderr.write(`Warning: Skipping ${dir}: ${err.message}\n`);
+        }
+    }
     /** Get the resolved project name when only one project is loaded. */
     defaultProject() {
         if (this.projects.size === 1)
@@ -129,9 +152,22 @@ export class MultiLoader {
         if (!this.loaded)
             this.load();
         const p = this.resolveProject(project);
-        if (p)
-            return this.projectEntities.get(p) || [];
-        return []; // multi-project with no project specified
+        if (!p)
+            return [];
+        // Delegate to BundleLoader (which checks mtime via ensureFresh),
+        // then re-stamp and cache if the reference changed.
+        const loader = this.projects.get(p);
+        if (!loader)
+            return [];
+        const fresh = loader.getEntities();
+        const cached = this.projectEntities.get(p);
+        if (fresh !== cached) {
+            for (const e of fresh) {
+                e._project = p;
+            }
+            this.projectEntities.set(p, fresh);
+        }
+        return fresh;
     }
     getTopology(project) {
         if (!this.loaded)

package/dist/supabase.d.ts

@@ -55,6 +55,31 @@ export interface TokenPredictionRow {
     session_id: string | null;
     notes: string | null;
 }
+export interface McpTelemetryLog {
+    user_id?: string;
+    tool_name: string;
+    project_hash: string;
+    execution_ms: number;
+}
+export interface JstfSnapshotInsert {
+    user_id?: string;
+    project_hash: string;
+    commit_sha: string;
+    language_primary: string;
+    total_entities: number;
+    metric_typeless_interfaces: number;
+    metric_max_in_degree: number;
+    metric_circular_dependencies: number;
+    metric_untracked_data_transformations: number;
+    metric_exposure_leaks: number;
+    metric_layer_violations: number;
+    metric_ownership_violations: number;
+    metric_impure_ratio: number;
+    metric_runtime_violations: number;
+    metric_semantic_clones: number;
+    metric_core_fragility_score: number;
+    bundle_payload: unknown;
+}
 /**
  * Insert a prediction row. Returns the row ID or null on failure.
  */
@@ -70,4 +95,5 @@ export declare function abandonPrediction(predictionId: string): Promise<boolean
 /**
  * List recent predictions for a project (for calibration analysis).
  */
-export declare function listPredictions(project?: string, limit?: number): Promise<TokenPredictionRow[]>;
+export declare function logTelemetry(log: McpTelemetryLog): Promise<void>;
+export declare function insertJstfSnapshot(snapshot: JstfSnapshotInsert): Promise<boolean>;

package/dist/supabase.js

@@ -18,7 +18,9 @@ export function isSupabaseConfigured() {
     return SUPABASE_URL.length > 0 && SUPABASE_KEY.length > 0;
 }
 // ─── REST helpers ────────────────────────────────────────────────
-const TABLE = 'mcp_token_predictions';
+const TABLE_PREDICTIONS = 'mcp_token_predictions';
+const TABLE_TELEMETRY = 'mcp_telemetry_logs';
+const TABLE_SNAPSHOTS = 'jstf_snapshots';
 async function supabaseRequest(method, path, body, headers) {
     if (!isSupabaseConfigured()) {
         return { ok: false, status: 0, error: 'Supabase not configured' };
@@ -59,7 +61,7 @@ async function supabaseRequest(method, path, body, headers) {
  * Insert a prediction row. Returns the row ID or null on failure.
  */
 export async function insertPrediction(row) {
-    const result = await supabaseRequest('POST', TABLE, row);
+    const result = await supabaseRequest('POST', TABLE_PREDICTIONS, row);
     if (!result.ok) {
         process.stderr.write(`[seshat] Prediction log failed: ${result.error}\n`);
         return null;
@@ -72,7 +74,7 @@ export async function insertPrediction(row) {
  */
 export async function updateActualBurn(predictionId, actual) {
     // First fetch the prediction to compute drift
-    const fetchResult = await supabaseRequest('GET', `${TABLE}?id=eq.${predictionId}&select=predicted_total,status`);
+    const fetchResult = await supabaseRequest('GET', `${TABLE_PREDICTIONS}?id=eq.${predictionId}&select=predicted_total,status`);
     if (!fetchResult.ok) {
         process.stderr.write(`[seshat] Fetch prediction failed: ${fetchResult.error}\n`);
         return null;
@@ -98,7 +100,7 @@ export async function updateActualBurn(predictionId, actual) {
         status: 'completed',
         ...(actual.notes ? { notes: actual.notes } : {}),
     };
-    const updateResult = await supabaseRequest('PATCH', `${TABLE}?id=eq.${predictionId}`, updateBody);
+    const updateResult = await supabaseRequest('PATCH', `${TABLE_PREDICTIONS}?id=eq.${predictionId}`, updateBody);
     if (!updateResult.ok) {
         process.stderr.write(`[seshat] Update actual burn failed: ${updateResult.error}\n`);
         return null;
@@ -109,16 +111,22 @@ export async function updateActualBurn(predictionId, actual) {
  * Abandon a prediction (task was cancelled or not completed).
  */
 export async function abandonPrediction(predictionId) {
-    const result = await supabaseRequest('PATCH', `${TABLE}?id=eq.${predictionId}&status=eq.predicted`, { status: 'abandoned' });
+    const result = await supabaseRequest('PATCH', `${TABLE_PREDICTIONS}?id=eq.${predictionId}&status=eq.predicted`, { status: 'abandoned' });
     return result.ok;
 }
 /**
  * List recent predictions for a project (for calibration analysis).
  */
-export async function listPredictions(project, limit = 20) {
-    const filter = project ? `&project=eq.${encodeURIComponent(project)}` : '';
-    const result = await supabaseRequest('GET', `${TABLE}?select=*${filter}&order=created_at.desc&limit=${limit}`);
-    if (!result.ok)
-        return [];
-    return result.data || [];
+export async function logTelemetry(log) {
+    const result = await supabaseRequest('POST', TABLE_TELEMETRY, log);
+    if (!result.ok) {
+        process.stderr.write(`[seshat] Telemetry log failed: ${result.error}\n`);
+    }
+}
+export async function insertJstfSnapshot(snapshot) {
+    const result = await supabaseRequest('POST', TABLE_SNAPSHOTS, snapshot);
+    if (!result.ok) {
+        process.stderr.write(`[seshat] JSTF snapshot failed: ${result.error}\n`);
+    }
+    return result.ok;
 }

package/dist/tools/diff.d.ts

@@ -11,7 +11,7 @@ export declare function diffBundle(args: {
     worktree_path: string;
     project?: string;
     include_unchanged?: boolean;
-}): Promise<unknown>;
+}, loader: ProjectLoader): Promise<unknown>;
 export declare function conflictMatrix(args: {
     tasks: Array<{
         id: string;
@@ -20,4 +20,4 @@ export declare function conflictMatrix(args: {
         expand_blast_radius?: boolean;
     }>;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;

package/dist/tools/diff.js

@@ -11,7 +11,7 @@ import fs from 'fs';
 import path from 'path';
 import { bootstrap } from '../bootstrap.js';
 import { computeBlastRadius } from '../graph.js';
-import { getLoader, getGraph, validateProject, entityName, entityLayer, } from './index.js';
+import { getGraph, validateProject, entityName, entityLayer, } from './index.js';
 // ─── Entity Identity ─────────────────────────────────────────────
 // Ported from api-v2/translator/seshat-pipeline/src/incremental/diff-engine.mjs
 /**
@@ -145,11 +145,10 @@ function compareEntityFields(baseEntity, branchEntity) {
     return changed;
 }
 // ─── Tool: diff_bundle ───────────────────────────────────────────
-export async function diffBundle(args) {
-    const projErr = validateProject(args.project);
+export async function diffBundle(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
     const baseEntities = loader.getEntities(args.project);
     const baseManifest = loader.getManifest(args.project);
     if (baseEntities.length === 0) {
@@ -366,11 +365,10 @@ function buildExecutionPlan(taskIds, tier3Edges) {
     };
 }
 // ─── Tool: conflict_matrix ────────────────────────────────────────
-export function conflictMatrix(args) {
-    const projErr = validateProject(args.project);
+export function conflictMatrix(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
     const { tasks } = args;
     if (!tasks || tasks.length < 2) {
         return { error: 'At least 2 tasks are required to compute a conflict matrix.' };
@@ -402,7 +400,7 @@ export function conflictMatrix(args) {
         }
         // Expand blast radius if requested
         if (task.expand_blast_radius && entityIds.size > 0) {
-            const g = getGraph(args.project);
+            const g = getGraph(args.project, loader);
             const blastResult = computeBlastRadius(g, entityIds);
             for (const affectedId of blastResult.affected) {
                 if (!entityIds.has(affectedId)) {

package/dist/tools/functors.d.ts

@@ -15,14 +15,14 @@ export declare function estimateTokens(e: JstfEntity): number;
 export declare function findDeadCode(args: {
     include_tests?: boolean;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function findLayerViolations(args?: {
     project?: string;
 }): unknown;
 export declare function getCouplingMetrics(args: {
     group_by?: 'module' | 'layer';
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function getAuthMatrix(args?: {
     project?: string;
 }): unknown;
@@ -32,13 +32,13 @@ export declare function findErrorGaps(args?: {
 export declare function getTestCoverage(args: {
     weight_by_blast_radius?: boolean;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function getOptimalContext(args: {
     target_entity: string;
     max_tokens?: number;
     strategy?: 'bfs' | 'blast_radius';
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 /**
  * Estimate token cost of a code change BEFORE starting work.
  * Computes blast radius, sums source token counts, and projects total burn.
@@ -48,7 +48,7 @@ export declare function estimateTaskCost(args: {
     target_entities: string[];
     context_budget?: number;
     project?: string;
-}): Promise<unknown>;
+}, loader: ProjectLoader): Promise<unknown>;
 /**
  * Close the calibration feedback loop by reporting actual token usage
  * against a prior prediction from estimate_task_cost.
@@ -65,7 +65,7 @@ export declare function reportActualBurn(args: {
     action?: 'complete' | 'abandon' | 'list';
     project?: string;
     notes?: string;
-}): Promise<unknown>;
+}, loader: ProjectLoader): Promise<unknown>;
 export declare function find_runtime_violations(args?: {
     project?: string;
 }): unknown;
@@ -75,7 +75,7 @@ export declare function find_ownership_violations(args?: {
 export declare function query_traits(args: {
     trait: string;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function simulate_mutation(args: {
     entity_id: string;
     mutation: {
@@ -86,11 +86,11 @@ export declare function simulate_mutation(args: {
         };
     };
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function query_data_targets(args: {
     target_name: string;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function find_exposure_leaks(args?: {
     project?: string;
 }): unknown;
@@ -104,4 +104,4 @@ export declare function create_symbol(args: {
     layer?: string;
     project?: string;
     description?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;

package/dist/tools/functors.js

@@ -7,8 +7,8 @@
  */
 import path from 'path';
 import { computeBlastRadius } from '../graph.js';
-import { getLoader, getGraph, validateProject, entityName, entityLayer, entitySummary, } from './index.js';
-import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, listPredictions, } from '../supabase.js';
+import { getGraph, validateProject, entityName, entityLayer, entitySummary, } from './index.js';
+import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, } from '../supabase.js';
 // ─── Layer ordering for violation detection ──────────────────────
 const LAYER_ORDER = {
     route: 0,
@@ -82,13 +82,12 @@ function dominantEstimator(entities) {
     return 'heuristic';
 }
 // ─── Tool: find_dead_code ────────────────────────────────────────
-export function findDeadCode(args) {
-    const projErr = validateProject(args.project);
+export function findDeadCode(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const { include_tests = false } = args;
-    const loader = getLoader();
-    const g = getGraph(args.project);
+    const g = getGraph(args.project, loader);
     const entities = loader.getEntities(args.project);
     // Entry points: routes, exported functions, test files, plugin registrations
     const entryPointIds = new Set();
@@ -132,9 +131,9 @@ export function findDeadCode(args) {
         }
     }
     // Unreachable = dead code candidates
-    let deadEntities = entities.filter(e => e.id && !reachable.has(e.id));
+    let deadEntities = entities.filter((e) => e.id && !reachable.has(e.id));
     if (!include_tests) {
-        deadEntities = deadEntities.filter(e => entityLayer(e) !== 'test');
+        deadEntities = deadEntities.filter((e) => entityLayer(e) !== 'test');
     }
     // Group by layer for overview
     const byLayer = new Map();
@@ -153,10 +152,10 @@ export function findDeadCode(args) {
 }
 // ─── Tool: find_layer_violations ─────────────────────────────────
 export function findLayerViolations(args) {
-    const projErr = validateProject(args?.project);
+    const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
-    const g = getGraph(args?.project);
+    const g = getGraph(args?.project, loader);
     const violations = [];
     for (const [callerId, calleeIds] of g.callees) {
         const callerEntity = g.entityById.get(callerId);
@@ -208,13 +207,12 @@ export function findLayerViolations(args) {
     };
 }
 // ─── Tool: get_coupling_metrics ──────────────────────────────────
-export function getCouplingMetrics(args) {
-    const projErr = validateProject(args.project);
+export function getCouplingMetrics(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const { group_by = 'module' } = args;
-    const loader = getLoader();
-    const g = getGraph(args.project);
+    const g = getGraph(args.project, loader);
     const entities = loader.getEntities(args.project);
     // Group entities
     const groups = new Map();
@@ -281,12 +279,11 @@ export function getCouplingMetrics(args) {
 }
 // ─── Tool: get_auth_matrix ───────────────────────────────────────
 export function getAuthMatrix(args) {
-    const projErr = validateProject(args?.project);
+    const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
     const entities = loader.getEntities(args?.project);
-    const apiEntities = entities.filter(e => {
+    const apiEntities = entities.filter((e) => {
         const layer = entityLayer(e);
         return layer === 'route' || layer === 'controller' ||
             e.context?.exposure === 'api';
@@ -339,11 +336,10 @@ export function getAuthMatrix(args) {
 }
 // ─── Tool: find_error_gaps ───────────────────────────────────────
 export function findErrorGaps(args) {
-    const projErr = validateProject(args?.project);
+    const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
-    const g = getGraph(args?.project);
+    const g = getGraph(args?.project, loader);
     const entities = loader.getEntities(args?.project);
     // Find all fallible entities (throws === true or has THROWS tag)
     const fallibleIds = new Set();
@@ -405,13 +401,12 @@ export function findErrorGaps(args) {
     };
 }
 // ─── Tool: get_test_coverage ─────────────────────────────────────
-export function getTestCoverage(args) {
-    const projErr = validateProject(args.project);
+export function getTestCoverage(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const { weight_by_blast_radius = false } = args;
-    const loader = getLoader();
-    const g = getGraph(args.project);
+    const g = getGraph(args.project, loader);
     const entities = loader.getEntities(args.project);
     // Partition into test and non-test entities
     const testIds = new Set();
@@ -445,8 +440,8 @@ export function getTestCoverage(args) {
             }
         }
     }
-    const covered = productionEntities.filter(e => exercised.has(e.id));
-    const uncovered = productionEntities.filter(e => !exercised.has(e.id));
+    const covered = productionEntities.filter((e) => exercised.has(e.id));
+    const uncovered = productionEntities.filter((e) => !exercised.has(e.id));
     const coveragePercent = productionEntities.length > 0
         ? Math.round((covered.length / productionEntities.length) * 1000) / 10
         : 0;
@@ -484,13 +479,12 @@ export function getTestCoverage(args) {
     return result;
 }
 // ─── Tool: get_optimal_context ───────────────────────────────────
-export function getOptimalContext(args) {
-    const projErr = validateProject(args.project);
+export function getOptimalContext(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const { target_entity, max_tokens = 8000, strategy = 'bfs' } = args;
-    const loader = getLoader();
-    const g = getGraph(args.project);
+    const g = getGraph(args.project, loader);
     const entity = loader.getEntityById(target_entity, args.project) || loader.getEntityByName(target_entity, args.project);
     if (!entity) {
         return { error: `Entity not found: ${target_entity}` };
@@ -605,13 +599,12 @@ export function getOptimalContext(args) {
  * Computes blast radius, sums source token counts, and projects total burn.
  * Logs prediction to Supabase when configured (for calibration feedback loop).
  */
-export async function estimateTaskCost(args) {
-    const projErr = validateProject(args.project);
+export async function estimateTaskCost(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const { target_entities, context_budget = 200000 } = args;
-    const loader = getLoader();
-    const g = getGraph(args.project);
+    const g = getGraph(args.project, loader);
     // Resolve target entities
     const resolvedTargets = [];
     const unresolvedNames = [];
@@ -674,7 +667,7 @@ export async function estimateTaskCost(args) {
         let outgoing = 0;
         let incoming = 0;
         const entities = loader.getEntities(args.project);
-        const modIds = new Set(entities.filter(e => e.context?.module === mod).map(e => e.id));
+        const modIds = new Set(entities.filter((e) => e.context?.module === mod).map(e => e.id));
         for (const id of modIds) {
             const calleeSet = g.callees.get(id);
             if (calleeSet) {
@@ -772,7 +765,7 @@ export async function estimateTaskCost(args) {
  * Can also abandon a prediction (task was cancelled/not completed),
  * or list recent predictions for calibration analysis.
  */
-export async function reportActualBurn(args) {
+export async function reportActualBurn(args, loader) {
     if (!isSupabaseConfigured()) {
         return {
             error: 'Supabase not configured. Set SESHAT_SUPABASE_URL and SESHAT_SUPABASE_KEY env vars.',
@@ -782,48 +775,9 @@ export async function reportActualBurn(args) {
     const { action = 'complete' } = args;
     // List mode: show recent predictions for calibration analysis
     if (action === 'list') {
-        const rows = await listPredictions(args.project);
-        if (rows.length === 0) {
-            return { message: 'No predictions found.', predictions: [] };
-        }
-        const summary = rows.map((r) => ({
-            id: r.id,
-            project: r.project,
-            targets: r.target_entities,
-            predicted: r.predicted_total,
-            actual: r.actual_total_tokens,
-            drift: r.drift_ratio,
-            estimator: r.estimator_used,
-            status: r.status,
-            createdAt: r.created_at,
-        }));
-        // Compute aggregate calibration stats for completed predictions
-        const completed = rows.filter((r) => r.status === 'completed' && r.drift_ratio != null);
-        let calibration;
-        if (completed.length >= 3) {
-            const drifts = completed.map((r) => r.drift_ratio);
-            const meanDrift = drifts.reduce((a, b) => a + b, 0) / drifts.length;
-            const sortedDrifts = [...drifts].sort((a, b) => a - b);
-            const medianDrift = sortedDrifts[Math.floor(sortedDrifts.length / 2)];
-            const maxOvershoot = Math.max(...drifts);
-            const maxUndershoot = Math.min(...drifts);
-            calibration = {
-                completedSamples: completed.length,
-                meanDrift: Math.round(meanDrift * 1000) / 1000,
-                medianDrift: Math.round(medianDrift * 1000) / 1000,
-                maxOvershoot: Math.round(maxOvershoot * 1000) / 1000,
-                maxUndershoot: Math.round(maxUndershoot * 1000) / 1000,
-                _interpretation: meanDrift > 0.2
-                    ? 'Predictions underestimate — consider increasing iteration multiplier.'
-                    : meanDrift < -0.2
-                        ? 'Predictions overestimate — consider decreasing iteration multiplier.'
-                        : 'Predictions are well-calibrated (within 20% mean drift).',
-            };
-        }
         return {
-            total: rows.length,
-            predictions: summary,
-            ...(calibration ? { calibration } : {}),
+            message: 'List predictions has been migrated to the Ptah Dashboard.',
+            predictions: []
         };
     }
     // Complete or abandon requires prediction_id
@@ -869,10 +823,10 @@ export async function reportActualBurn(args) {
 }
 // ─── Tool: find_runtime_violations (Runtime Context) ────────────
 export function find_runtime_violations(args) {
-    const projErr = validateProject(args?.project);
+    const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
-    const g = getGraph(args?.project);
+    const g = getGraph(args?.project, loader);
     const violations = [];
     for (const [callerId, calleeIds] of g.callees) {
         const callerEntity = g.entityById.get(callerId);
@@ -910,10 +864,9 @@ export function find_runtime_violations(args) {
 }
 // ─── Tool: find_ownership_violations (Ownership & Lifetimes) ─────
 export function find_ownership_violations(args) {
-    const projErr = validateProject(args?.project);
+    const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
     const entities = loader.getEntities(args?.project);
     const violations = [];
     for (const e of entities) {
@@ -950,19 +903,18 @@ export function find_ownership_violations(args) {
     };
 }
 // ─── Tool: query_traits (Trait Search) ───────────────────────────
-export function query_traits(args) {
-    const projErr = validateProject(args.project);
+export function query_traits(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const target = args.trait.toLowerCase();
-    const loader = getLoader();
     const entities = loader.getEntities(args.project);
-    const results = entities.filter(e => {
+    const results = entities.filter((e) => {
         if (!e.traits)
             return false;
         // Handle array of strings [ 'asyncContext', 'generator' ]
         if (Array.isArray(e.traits)) {
-            return e.traits.some(t => t.toLowerCase().includes(target));
+            return e.traits.some((t) => t.toLowerCase().includes(target));
         }
         // Handle structured traits { self: { fallible: true } }
         if (typeof e.traits === 'object') {
@@ -994,12 +946,11 @@ export function query_traits(args) {
     };
 }
 // ─── Tool: simulate_mutation (Impact Simulator) ──────────────────
-export function simulate_mutation(args) {
-    const projErr = validateProject(args.project);
+export function simulate_mutation(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
-    const g = getGraph(args.project);
+    const g = getGraph(args.project, loader);
     const targetEntity = loader.getEntityById(args.entity_id, args.project)
         || loader.getEntityByName(args.entity_id, args.project);
     if (!targetEntity) {
@@ -1075,11 +1026,10 @@ export function simulate_mutation(args) {
     };
 }
 // ─── Tool: query_data_targets (Data Flow Analysis) ──────────────
-export function query_data_targets(args) {
-    const projErr = validateProject(args.project);
+export function query_data_targets(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
     const entities = loader.getEntities(args.project);
     const target = args.target_name.toLowerCase();
     const readers = [];
@@ -1090,24 +1040,24 @@ export function query_data_targets(args) {
         let isReader = false;
         let isWriter = false;
         // Check tables
-        if (Array.isArray(e.data.tables) && e.data.tables.some(t => String(t).toLowerCase() === target)) {
+        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)) {
+            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)) {
+            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)) {
+            if (e.data.mutations.some((m) => m && typeof m === 'object' && String(m.target).toLowerCase() === target)) {
                 isWriter = true;
             }
         }
@@ -1130,10 +1080,10 @@ export function query_data_targets(args) {
 }
 // ─── Tool: find_exposure_leaks (Architectural Visibility) ───────
 export function find_exposure_leaks(args) {
-    const projErr = validateProject(args?.project);
+    const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
-    const g = getGraph(args?.project);
+    const g = getGraph(args?.project, loader);
     const leaks = [];
     for (const [callerId, calleeIds] of g.callees) {
         const callerEntity = g.entityById.get(callerId);
@@ -1165,10 +1115,9 @@ export function find_exposure_leaks(args) {
 // ─── Tool: find_semantic_clones (Logic Analysis) ────────────────
 import { createHash } from 'crypto';
 export function find_semantic_clones(args) {
-    const projErr = validateProject(args?.project);
+    const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
     const entities = loader.getEntities(args?.project);
     const { min_complexity = 5 } = args || {};
     const logicHashes = new Map();
@@ -1212,11 +1161,10 @@ export function find_semantic_clones(args) {
     };
 }
 // ─── Tool: create_symbol (Virtual Entry) ─────────────────────────
-export function create_symbol(args) {
-    const projErr = validateProject(args.project);
+export function create_symbol(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
-    const loader = getLoader();
     // Create a skeleton JSTF-T entity
     const virtualEntity = {
         id: args.id,

package/dist/tools/index.d.ts

@@ -8,17 +8,14 @@
  * `project` parameter. In multi-project mode, `project` is required.
  */
 import type { JstfEntity } from '../types.js';
-import { MultiLoader } from '../loader.js';
 import { type CallGraph } from '../graph.js';
-export declare function initTools(multiLoader: MultiLoader): void;
-export declare function getLoader(): MultiLoader;
-export declare function getGraph(project?: string): CallGraph;
+export declare function getGraph(project: string | undefined, loader: ProjectLoader): CallGraph;
 /**
  * Validate project param. Returns error string if invalid, null if OK.
  * In single-project mode, project is optional (defaults to the only project).
  * In multi-project mode, project is required.
  */
-export declare function validateProject(project?: string): string | null;
+export declare function validateProject(project: string | undefined, loader: ProjectLoader): string | null;
 export declare function entityName(e: JstfEntity): string;
 export declare function entityLayer(e: JstfEntity): string;
 export declare function entitySummary(e: JstfEntity): Record<string, unknown>;
@@ -35,34 +32,34 @@ export declare function queryEntities(args: {
     module?: string;
     language?: string;
     limit?: number;
-}): unknown;
+}, loader: ProjectLoader): Promise<unknown>;
 export declare function getEntity(args: {
     id: string;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function getDependencies(args: {
     entity_id: string;
     direction?: 'callers' | 'callees' | 'both';
     depth?: number;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function collectTransitive(adjacency: Map<string, Set<string>>, startId: string, maxDepth: number): string[];
 export declare function getDataFlow(args: {
     entity_id: string;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function findByConstraint(args: {
     constraint: string;
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function getBlastRadius(args: {
     entity_ids: string[];
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function listModules(args: {
     group_by?: 'layer' | 'module' | 'file' | 'language';
     project?: string;
-}): unknown;
-export declare function getTopology(args?: {
+}, loader: ProjectLoader): unknown;
+export declare function getTopology(args: {
     project?: string;
-}): unknown;
+} | undefined, loader: ProjectLoader): unknown;

package/dist/tools/index.js

@@ -8,29 +8,15 @@
  * `project` parameter. In multi-project mode, `project` is required.
  */
 import { buildCallGraph, computeBlastRadius } from '../graph.js';
-// Lazy-initialized shared state
-let loader;
-let graphCache = new Map();
-export function initTools(multiLoader) {
-    loader = multiLoader;
-    graphCache = new Map();
-}
-export function getLoader() {
-    return loader;
-}
-export function getGraph(project) {
-    const key = project || '__default__';
-    if (!graphCache.has(key)) {
-        graphCache.set(key, buildCallGraph(loader.getEntities(project)));
-    }
-    return graphCache.get(key);
+export function getGraph(project, loader) {
+    return buildCallGraph(loader.getEntities(project));
 }
 /**
  * Validate project param. Returns error string if invalid, null if OK.
  * In single-project mode, project is optional (defaults to the only project).
  * In multi-project mode, project is required.
  */
-export function validateProject(project) {
+export function validateProject(project, loader) {
     if (!loader.isMultiProject())
         return null; // single project, always OK
     if (!project) {
@@ -155,7 +141,7 @@ export function normalizeConstraints(constraints) {
 export function constraintMatches(constraints, target) {
     // First check normalized tags
     const tags = normalizeConstraints(constraints);
-    if (tags.some(t => t.toUpperCase().includes(target.toUpperCase())))
+    if (tags.some((t) => t.toUpperCase().includes(target.toUpperCase())))
         return true;
     // Also search raw constraint values for substring match
     if (constraints && typeof constraints === 'object' && !Array.isArray(constraints)) {
@@ -166,42 +152,40 @@ export function constraintMatches(constraints, target) {
     return false;
 }
 // ─── Tool: query_entities ─────────────────────────────────────────
-export function queryEntities(args) {
-    const projErr = validateProject(args.project);
-    if (projErr)
-        return { error: projErr };
-    const { query, layer, module, language, limit = 50 } = args;
-    let results = loader.getEntities(args.project);
-    if (layer) {
-        results = results.filter(e => entityLayer(e).toLowerCase() === layer.toLowerCase());
-    }
-    if (module) {
-        results = results.filter(e => e.context?.module?.toLowerCase().includes(module.toLowerCase()));
+export async function queryEntities(args, loader) {
+    const apiKey = process.env.SESHAT_API_KEY;
+    if (!apiKey) {
+        return { error: 'SESHAT_API_KEY environment variable is missing. You must provide an API key to use Ptah Cloud tools.' };
     }
-    if (language) {
-        results = results.filter(e => e._sourceLanguage?.toLowerCase() === language.toLowerCase());
-    }
-    if (query) {
-        const q = query.toLowerCase();
-        results = results.filter(e => {
-            const name = entityName(e).toLowerCase();
-            const file = (e._sourceFile || '').toLowerCase();
-            const mod = (e.context?.module || '').toLowerCase();
-            const id = (e.id || '').toLowerCase();
-            return name.includes(q) || file.includes(q) || mod.includes(q) || id.includes(q);
+    // We are hardcoding the project_hash to 'seshat-fabric' for this local test, 
+    // but in production the MCP would pass args.project or read from the manifest.
+    const project_hash = args.project || 'seshat-fabric';
+    try {
+        const res = await fetch('http://localhost:3001/api/mcp/execute', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey
+            },
+            body: JSON.stringify({
+                tool: 'query_entities',
+                project_hash: project_hash,
+                args
+            })
         });
+        if (!res.ok) {
+            const errorText = await res.text();
+            return { error: `Cloud API Error (${res.status}): ${errorText}` };
+        }
+        return await res.json();
+    }
+    catch (error) {
+        return { error: `Failed to connect to Ptah Cloud: ${error.message}` };
     }
-    const total = results.length;
-    const entities = results.slice(0, limit).map(entitySummary);
-    return {
-        total,
-        showing: entities.length,
-        entities,
-    };
 }
 // ─── Tool: get_entity ─────────────────────────────────────────────
-export function getEntity(args) {
-    const projErr = validateProject(args.project);
+export function getEntity(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const entity = loader.getEntityById(args.id, args.project) || loader.getEntityByName(args.id, args.project);
@@ -226,12 +210,12 @@ export function getEntity(args) {
     };
 }
 // ─── Tool: get_dependencies ───────────────────────────────────────
-export function getDependencies(args) {
-    const projErr = validateProject(args.project);
+export function getDependencies(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const { entity_id, direction = 'both', depth = 2 } = args;
-    const g = getGraph(args.project);
+    const g = getGraph(args.project, loader);
     const entity = loader.getEntityById(entity_id, args.project) || loader.getEntityByName(entity_id, args.project);
     if (!entity) {
         return { error: `Entity not found: ${entity_id}` };
@@ -282,8 +266,8 @@ export function collectTransitive(adjacency, startId, maxDepth) {
     return [...visited];
 }
 // ─── Tool: get_data_flow ──────────────────────────────────────────
-export function getDataFlow(args) {
-    const projErr = validateProject(args.project);
+export function getDataFlow(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const entity = loader.getEntityById(args.entity_id, args.project) || loader.getEntityByName(args.entity_id, args.project);
@@ -298,12 +282,12 @@ export function getDataFlow(args) {
     };
 }
 // ─── Tool: find_by_constraint ─────────────────────────────────────
-export function findByConstraint(args) {
-    const projErr = validateProject(args.project);
+export function findByConstraint(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const target = args.constraint;
-    const results = loader.getEntities(args.project).filter(e => constraintMatches(e.constraints, target));
+    const results = loader.getEntities(args.project).filter((e) => constraintMatches(e.constraints, target));
     return {
         constraint: args.constraint,
         total: results.length,
@@ -311,11 +295,11 @@ export function findByConstraint(args) {
     };
 }
 // ─── Tool: get_blast_radius ───────────────────────────────────────
-export function getBlastRadius(args) {
-    const projErr = validateProject(args.project);
+export function getBlastRadius(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
-    const g = getGraph(args.project);
+    const g = getGraph(args.project, loader);
     // Resolve names to IDs
     const resolvedIds = new Set();
     const notFound = [];
@@ -348,8 +332,8 @@ export function getBlastRadius(args) {
     };
 }
 // ─── Tool: list_modules ───────────────────────────────────────────
-export function listModules(args) {
-    const projErr = validateProject(args.project);
+export function listModules(args, loader) {
+    const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
     const { group_by = 'layer' } = args;
@@ -385,8 +369,8 @@ export function listModules(args) {
     };
 }
 // ─── Tool: get_topology ───────────────────────────────────────────
-export function getTopology(args) {
-    const projErr = validateProject(args?.project);
+export function getTopology(args, loader) {
+    const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
     const topology = loader.getTopology(args?.project);

package/dist/types.d.ts

@@ -158,3 +158,17 @@ export interface ProjectInfo {
     extractedAt: string;
     layers: Record<string, number>;
 }
+export interface ProjectLoader {
+    getEntities(project?: string): JstfEntity[];
+    getTopology(project?: string): Topology | null;
+    getManifest(project?: string): Manifest | null;
+    getEntityById(id: string, project?: string): JstfEntity | undefined;
+    getEntityByName(name: string, project?: string): JstfEntity | undefined;
+    getProjectNames(): string[];
+    getProjectInfo(): ProjectInfo[];
+    isMultiProject(): boolean;
+    isLoaded(): boolean;
+    hasProject(name: string): boolean;
+    registerVirtualEntity(entity: JstfEntity, project?: string): void;
+    totalEntities(): number;
+}

package/package.json

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