@papyruslabsai/seshat-mcp 0.11.1 → 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
  *
@@ -34,7 +35,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { MultiLoader } from './loader.js';
 import { bootstrap } from './bootstrap.js';
 import { logTelemetry, isSupabaseConfigured } from './supabase.js';
-import { initTools, queryEntities, getEntity, getDependencies, getDataFlow, findByConstraint, getBlastRadius, listModules, getTopology, } from './tools/index.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 ───────────────────────────────────────────

package/dist/loader.d.ts

@@ -4,7 +4,7 @@
  * 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;
@@ -31,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;

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,7 +7,7 @@
  */
 import path from 'path';
 import { computeBlastRadius } from '../graph.js';
-import { getLoader, getGraph, validateProject, entityName, entityLayer, entitySummary, } from './index.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 = {
@@ -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.',
@@ -830,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);
@@ -871,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) {
@@ -911,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') {
@@ -955,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) {
@@ -1036,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 = [];
@@ -1051,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;
             }
         }
@@ -1091,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);
@@ -1126,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();
@@ -1173,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.1",
+  "version": "0.12.0",
   "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
   "type": "module",
   "bin": {