@papyruslabsai/seshat-mcp 0.2.0 → 0.3.1

package/dist/graph.js

@@ -21,7 +21,10 @@ export function buildCallGraph(entities) {
         callers.set(entity.id, new Set());
         callees.set(entity.id, new Set());
         if (entity.context?.module) {
-            entityByModule.set(entity.context.module, entity);
+            const mod = entity.context.module;
+            if (!entityByModule.has(mod))
+                entityByModule.set(mod, []);
+            entityByModule.get(mod).push(entity);
         }
     }
     // Build call edges from ε dimension
@@ -42,12 +45,27 @@ export function buildCallGraph(entities) {
             }
             // Strategy 2: Method match (target = "module.method")
             else if (target.includes('.')) {
-                const [modulePart, methodPart] = target.split('.');
-                const moduleEntity = entityByModule.get(modulePart);
-                if (moduleEntity) {
-                    calleeId = moduleEntity.id;
+                const dotIdx = target.indexOf('.');
+                const modulePart = target.substring(0, dotIdx);
+                const methodPart = target.substring(dotIdx + 1);
+                // First try "module.method" as a full entity ID
+                if (entityById.has(target)) {
+                    calleeId = target;
                 }
-                // Also try "module.method" as a full ID
+                // Search within the module's entities for one named methodPart
+                if (!calleeId) {
+                    const moduleEntities = entityByModule.get(modulePart);
+                    if (moduleEntities) {
+                        const match = moduleEntities.find(e => {
+                            const name = typeof e.struct === 'string' ? e.struct : e.struct?.name;
+                            return e.id === methodPart || name === methodPart;
+                        });
+                        if (match) {
+                            calleeId = match.id;
+                        }
+                    }
+                }
+                // Also try "module.method" concatenated as an ID
                 if (!calleeId && entityById.has(`${modulePart}.${methodPart}`)) {
                     calleeId = `${modulePart}.${methodPart}`;
                 }

package/dist/index.d.ts

@@ -3,20 +3,27 @@
  * @papyruslabs/seshat-mcp — Semantic MCP Server
  *
  * Exposes a codebase's 9D JSTF-T coordinate space as queryable MCP tools.
- * Reads .seshat/_bundle.json from the current working directory.
+ * Reads .seshat/_bundle.json from project directories.
  *
- * Tools:
- *   query_entities    — Search entities by name, layer, module, language
- *   get_entity        — Full 9D coordinate dump for one entity
- *   get_dependencies  — ε edge traversal (callers/callees with depth control)
- *   get_data_flow     — δ dimension: inputs, outputs, mutations
- *   find_by_constraint — κ dimension search (AUTH, THROWS, DB_ACCESS, etc.)
- *   get_blast_radius  — Theorem 9.4: affected set for given entity IDs
- *   list_modules      — Group entities by layer, module, file, or language
- *   get_topology      — API topology (routes, plugins, auth, tables)
+ * 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.
  *
- * Interpretation Functors (composite analysis):
- *   find_dead_code      — Unreachable entities via ε-graph BFS from entry points
+ * Single-project mode (default):
+ *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
+ *
+ * Tools (8 core + 7 interpretation functors + 1 meta):
+ *   list_projects       — Show loaded projects with entity counts
+ *   query_entities      — Search entities by name, layer, module, language
+ *   get_entity          — Full 9D coordinate dump for one entity
+ *   get_dependencies    — ε edge traversal (callers/callees with depth control)
+ *   get_data_flow       — δ dimension: inputs, outputs, mutations
+ *   find_by_constraint  — κ dimension search (AUTH, THROWS, DB_ACCESS, etc.)
+ *   get_blast_radius    — Theorem 9.4: affected set for given entity IDs
+ *   list_modules        — Group entities by layer, module, file, or language
+ *   get_topology        — API topology (routes, plugins, auth, tables)
+ *   find_dead_code      — Unreachable entities via ε-graph BFS
  *   find_layer_violations — ε edges violating architectural layer ordering
  *   get_coupling_metrics  — Module coupling/cohesion/instability from ε-graph
  *   get_auth_matrix       — Auth coverage across API-facing entities from κ
@@ -25,9 +32,8 @@
  *   get_optimal_context   — Greedy knapsack: max relevance per token for LLM context
  *
  * Usage:
- *   npx @papyruslabs/seshat-mcp
- *
- * Configure in Claude Code (~/.claude/settings.json):
- *   { "mcpServers": { "seshat": { "command": "npx", "args": ["@papyruslabs/seshat-mcp"] } } }
+ *   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

@@ -3,20 +3,27 @@
  * @papyruslabs/seshat-mcp — Semantic MCP Server
  *
  * Exposes a codebase's 9D JSTF-T coordinate space as queryable MCP tools.
- * Reads .seshat/_bundle.json from the current working directory.
+ * Reads .seshat/_bundle.json from project directories.
  *
- * Tools:
- *   query_entities    — Search entities by name, layer, module, language
- *   get_entity        — Full 9D coordinate dump for one entity
- *   get_dependencies  — ε edge traversal (callers/callees with depth control)
- *   get_data_flow     — δ dimension: inputs, outputs, mutations
- *   find_by_constraint — κ dimension search (AUTH, THROWS, DB_ACCESS, etc.)
- *   get_blast_radius  — Theorem 9.4: affected set for given entity IDs
- *   list_modules      — Group entities by layer, module, file, or language
- *   get_topology      — API topology (routes, plugins, auth, tables)
+ * 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.
  *
- * Interpretation Functors (composite analysis):
- *   find_dead_code      — Unreachable entities via ε-graph BFS from entry points
+ * Single-project mode (default):
+ *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
+ *
+ * Tools (8 core + 7 interpretation functors + 1 meta):
+ *   list_projects       — Show loaded projects with entity counts
+ *   query_entities      — Search entities by name, layer, module, language
+ *   get_entity          — Full 9D coordinate dump for one entity
+ *   get_dependencies    — ε edge traversal (callers/callees with depth control)
+ *   get_data_flow       — δ dimension: inputs, outputs, mutations
+ *   find_by_constraint  — κ dimension search (AUTH, THROWS, DB_ACCESS, etc.)
+ *   get_blast_radius    — Theorem 9.4: affected set for given entity IDs
+ *   list_modules        — Group entities by layer, module, file, or language
+ *   get_topology        — API topology (routes, plugins, auth, tables)
+ *   find_dead_code      — Unreachable entities via ε-graph BFS
  *   find_layer_violations — ε edges violating architectural layer ordering
  *   get_coupling_metrics  — Module coupling/cohesion/instability from ε-graph
  *   get_auth_matrix       — Auth coverage across API-facing entities from κ
@@ -25,25 +32,80 @@
  *   get_optimal_context   — Greedy knapsack: max relevance per token for LLM context
  *
  * Usage:
- *   npx @papyruslabs/seshat-mcp
- *
- * Configure in Claude Code (~/.claude/settings.json):
- *   { "mcpServers": { "seshat": { "command": "npx", "args": ["@papyruslabs/seshat-mcp"] } } }
+ *   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
  */
+import fs from 'fs';
+import path from 'path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { BundleLoader } from './loader.js';
+import { MultiLoader } from './loader.js';
 import { initTools, queryEntities, getEntity, getDependencies, getDataFlow, findByConstraint, getBlastRadius, listModules, getTopology, } from './tools/index.js';
 import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, } from './tools/functors.js';
+// ─── Project Discovery ───────────────────────────────────────────
+/**
+ * Discover project directories from SESHAT_PROJECTS env var.
+ *
+ * - Not set → [process.cwd()] (backward compat)
+ * - Comma-separated paths → resolve each
+ * - Glob pattern (contains *) → scan parent dir for subdirs with .seshat/_bundle.json
+ */
+function discoverProjects() {
+    const env = process.env.SESHAT_PROJECTS;
+    if (!env)
+        return [process.cwd()];
+    const trimmed = env.trim();
+    // Glob pattern: /path/to/projects/*
+    if (trimmed.includes('*')) {
+        const globDir = trimmed.replace(/\/?\*$/, '');
+        const resolved = path.resolve(globDir);
+        if (!fs.existsSync(resolved)) {
+            process.stderr.write(`SESHAT_PROJECTS glob dir not found: ${resolved}\n`);
+            return [process.cwd()];
+        }
+        const dirs = [];
+        for (const entry of fs.readdirSync(resolved, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const candidate = path.join(resolved, entry.name);
+            const bundlePath = path.join(candidate, '.seshat', '_bundle.json');
+            if (fs.existsSync(bundlePath)) {
+                dirs.push(candidate);
+            }
+        }
+        if (dirs.length === 0) {
+            process.stderr.write(`SESHAT_PROJECTS: no dirs with .seshat/_bundle.json found in ${resolved}\n`);
+            return [process.cwd()];
+        }
+        return dirs;
+    }
+    // Comma-separated paths
+    return trimmed.split(',').map(p => path.resolve(p.trim())).filter(p => p.length > 0);
+}
+// ─── Project param definition (injected into all tool schemas) ───
+const projectParam = {
+    type: 'string',
+    description: 'Project name (required in multi-project mode). Use list_projects to see available projects.',
+};
 // ─── Tool Definitions ─────────────────────────────────────────────
 const TOOLS = [
+    {
+        name: 'list_projects',
+        description: 'List all loaded projects with entity counts, languages, and metadata. Call this first to see what projects are available, then pass the project name to other tools.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
     {
         name: 'query_entities',
         description: 'Search entities in the 9D semantic coordinate space. Filter by name, architectural layer (route/service/repository/component), module, or source language. Returns entity summaries with constraint tags.',
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 query: {
                     type: 'string',
                     description: 'Search term — matches against entity name, ID, source file, and module',
@@ -73,6 +135,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 id: {
                     type: 'string',
                     description: 'Entity ID or name',
@@ -87,6 +150,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 entity_id: {
                     type: 'string',
                     description: 'Entity ID or name',
@@ -110,6 +174,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 entity_id: {
                     type: 'string',
                     description: 'Entity ID or name',
@@ -124,6 +189,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 constraint: {
                     type: 'string',
                     description: 'Constraint tag to search for: AUTH, VALIDATED, PURE, THROWS, DB_ACCESS, NETWORK_IO, IMP, etc.',
@@ -138,6 +204,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 entity_ids: {
                     type: 'array',
                     items: { type: 'string' },
@@ -153,6 +220,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 group_by: {
                     type: 'string',
                     enum: ['layer', 'module', 'file', 'language'],
@@ -166,7 +234,9 @@ const TOOLS = [
         description: 'Get the API topology: routes, plugins, auth patterns, and database tables. Built from the χ (context) and ε (edges) dimensions across all entities.',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                project: projectParam,
+            },
         },
     },
     // ─── Interpretation Functor Tools ────────────────────────────────
@@ -176,6 +246,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 include_tests: {
                     type: 'boolean',
                     description: 'Include test entities in dead code results (default: false)',
@@ -188,7 +259,9 @@ const TOOLS = [
         description: 'Detect architectural layer violations in the ε call graph. Finds backward calls (lower layer calling higher layer, e.g. repository → route) and skip-layer calls (jumping over multiple layers). Uses χ.layer for classification.',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                project: projectParam,
+            },
         },
     },
     {
@@ -197,6 +270,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 group_by: {
                     type: 'string',
                     enum: ['module', 'layer'],
@@ -210,7 +284,9 @@ const TOOLS = [
         description: 'Analyze authentication coverage across all API-facing entities. Shows which routes/controllers have auth requirements (from κ.auth) and which don\'t. Detects inconsistencies like DB access without auth.',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                project: projectParam,
+            },
         },
     },
     {
@@ -218,7 +294,9 @@ const TOOLS = [
         description: 'Find error handling gaps: fallible entities (κ.throws, network/db side effects) whose callers lack try/catch (κ.errorHandling). These are crash risk points where exceptions can propagate unhandled.',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                project: projectParam,
+            },
         },
     },
     {
@@ -227,6 +305,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 weight_by_blast_radius: {
                     type: 'boolean',
                     description: 'Rank uncovered entities by blast radius to prioritize testing (default: false, slower)',
@@ -240,6 +319,7 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: projectParam,
                 target_entity: {
                     type: 'string',
                     description: 'Entity ID or name to build context around',
@@ -260,22 +340,34 @@ const TOOLS = [
 ];
 // ─── Server Setup ─────────────────────────────────────────────────
 async function main() {
-    // Load the JSTF-T bundle
-    const loader = new BundleLoader();
+    // Discover and load projects
+    const projectDirs = discoverProjects();
+    const loader = new MultiLoader(projectDirs);
     try {
         loader.load();
     }
     catch (err) {
-        // Server will start but tools will return helpful errors
         process.stderr.write(`Warning: ${err.message}\n`);
     }
     initTools(loader);
-    const manifest = loader.isLoaded() ? loader.getManifest() : null;
-    const projectName = manifest?.projectName || 'unknown';
-    const entityCount = manifest?.entityCount || 0;
+    // Build server name
+    const projectNames = loader.getProjectNames();
+    const totalEntities = loader.totalEntities();
+    const isMulti = loader.isMultiProject();
+    let serverLabel;
+    if (!loader.isLoaded()) {
+        serverLabel = 'seshat-mcp (no projects loaded)';
+    }
+    else if (isMulti) {
+        serverLabel = `seshat-mcp (${projectNames.length} projects, ${totalEntities} entities)`;
+    }
+    else {
+        const manifest = loader.getManifest();
+        serverLabel = `seshat-mcp (${manifest?.projectName || projectNames[0] || 'unknown'})`;
+    }
     const server = new Server({
-        name: `seshat-mcp (${projectName})`,
-        version: '0.2.0',
+        name: serverLabel,
+        version: '0.3.1',
     }, {
         capabilities: {
             tools: {},
@@ -294,13 +386,25 @@ async function main() {
                     content: [{
                             type: 'text',
                             text: JSON.stringify({
-                                error: 'No .seshat/_bundle.json found in the current working directory. Run the Seshat extraction pipeline first.',
+                                error: 'No projects loaded. Ensure .seshat/_bundle.json exists or set SESHAT_PROJECTS env var.',
                             }, null, 2),
                         }],
                 };
             }
             let result;
             switch (name) {
+                // Meta
+                case 'list_projects':
+                    result = {
+                        multiProject: isMulti,
+                        projects: loader.getProjectInfo(),
+                        totalEntities,
+                        hint: isMulti
+                            ? 'Pass the project name as the "project" parameter to all other tools.'
+                            : 'Single project mode — the "project" parameter is optional.',
+                    };
+                    break;
+                // Core tools
                 case 'query_entities':
                     result = queryEntities(args);
                     break;
@@ -323,23 +427,23 @@ async function main() {
                     result = listModules(args);
                     break;
                 case 'get_topology':
-                    result = getTopology();
+                    result = getTopology(args);
                     break;
                 // Interpretation Functors
                 case 'find_dead_code':
                     result = findDeadCode(args);
                     break;
                 case 'find_layer_violations':
-                    result = findLayerViolations();
+                    result = findLayerViolations(args);
                     break;
                 case 'get_coupling_metrics':
                     result = getCouplingMetrics(args);
                     break;
                 case 'get_auth_matrix':
-                    result = getAuthMatrix();
+                    result = getAuthMatrix(args);
                     break;
                 case 'find_error_gaps':
-                    result = findErrorGaps();
+                    result = findErrorGaps(args);
                     break;
                 case 'get_test_coverage':
                     result = getTestCoverage(args);
@@ -372,7 +476,13 @@ async function main() {
     // Start stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`Seshat MCP server started: ${projectName} (${entityCount} entities)\n`);
+    if (isMulti) {
+        process.stderr.write(`Seshat MCP server started: ${projectNames.length} projects (${totalEntities} entities) — ${projectNames.join(', ')}\n`);
+    }
+    else {
+        const manifest = loader.getManifest();
+        process.stderr.write(`Seshat MCP server started: ${manifest?.projectName || 'unknown'} (${totalEntities} entities)\n`);
+    }
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

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 } from './types.js';
+import type { JstfEntity, Topology, Manifest, ProjectInfo } from './types.js';
 export declare class BundleLoader {
     private entities;
     private topology;
@@ -20,3 +20,31 @@ export declare class BundleLoader {
     getEntityByName(name: string): JstfEntity | undefined;
     isLoaded(): boolean;
 }
+/**
+ * Wraps N BundleLoader instances for multi-project access.
+ * 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 {
+    private projects;
+    private projectPaths;
+    private projectEntities;
+    private loaded;
+    private dirs;
+    constructor(projectDirs: string[]);
+    load(): void;
+    /** Get the resolved project name when only one project is loaded. */
+    private defaultProject;
+    private resolveProject;
+    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;
+    totalEntities(): number;
+}

package/dist/loader.js

@@ -27,6 +27,18 @@ export class BundleLoader {
         const raw = fs.readFileSync(bundlePath, 'utf-8');
         const bundle = JSON.parse(raw);
         this.entities = bundle.entities || [];
+        // Remap bundle field names to internal _ prefixed names.
+        // The extraction pipeline outputs `sourceFile`, `sourceLanguage`, `_jstfFilename`
+        // but our JstfEntity type expects `_sourceFile`, `_sourceLanguage`.
+        for (const e of this.entities) {
+            const raw = e;
+            if (raw.sourceFile && !e._sourceFile) {
+                e._sourceFile = raw.sourceFile;
+            }
+            if (raw.sourceLanguage && !e._sourceLanguage) {
+                e._sourceLanguage = raw.sourceLanguage;
+            }
+        }
         // Load topology if available
         const topoPath = path.join(this.seshatDir, '_topology.json');
         if (fs.existsSync(topoPath)) {
@@ -67,3 +79,122 @@ export class BundleLoader {
         return this.loaded;
     }
 }
+// ─── Multi-Project Loader ─────────────────────────────────────────
+/**
+ * Wraps N BundleLoader instances for multi-project access.
+ * In single-project mode (1 dir), behaves identically to BundleLoader.
+ * In multi-project mode, `project` param is required on all accessors.
+ */
+export class MultiLoader {
+    projects = new Map();
+    projectPaths = new Map();
+    projectEntities = new Map();
+    loaded = false;
+    dirs;
+    constructor(projectDirs) {
+        this.dirs = projectDirs.length > 0 ? projectDirs : [process.cwd()];
+    }
+    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.loaded = true;
+    }
+    /** Get the resolved project name when only one project is loaded. */
+    defaultProject() {
+        if (this.projects.size === 1)
+            return [...this.projects.keys()][0];
+        return undefined;
+    }
+    resolveProject(project) {
+        return project || this.defaultProject();
+    }
+    getEntities(project) {
+        if (!this.loaded)
+            this.load();
+        const p = this.resolveProject(project);
+        if (p)
+            return this.projectEntities.get(p) || [];
+        return []; // multi-project with no project specified
+    }
+    getTopology(project) {
+        if (!this.loaded)
+            this.load();
+        const p = this.resolveProject(project);
+        if (p)
+            return this.projects.get(p)?.getTopology() || null;
+        return null;
+    }
+    getManifest(project) {
+        if (!this.loaded)
+            this.load();
+        const p = this.resolveProject(project);
+        if (p)
+            return this.projects.get(p)?.getManifest() || null;
+        return null;
+    }
+    getEntityById(id, project) {
+        return this.getEntities(project).find(e => e.id === id);
+    }
+    getEntityByName(name, project) {
+        return this.getEntities(project).find(e => {
+            const structName = typeof e.struct === 'string' ? e.struct : e.struct?.name;
+            return e.id === name || structName === name;
+        });
+    }
+    getProjectNames() {
+        if (!this.loaded)
+            this.load();
+        return [...this.projects.keys()];
+    }
+    getProjectInfo() {
+        if (!this.loaded)
+            this.load();
+        const result = [];
+        for (const [name, loader] of this.projects) {
+            const manifest = loader.getManifest();
+            result.push({
+                name,
+                path: this.projectPaths.get(name) || '',
+                entityCount: loader.getEntities().length,
+                languages: manifest?.languages || [],
+                commitSha: manifest?.commitSha || '',
+                extractedAt: manifest?.extractedAt || '',
+                layers: manifest?.layers || {},
+            });
+        }
+        return result;
+    }
+    isMultiProject() {
+        return this.projects.size > 1;
+    }
+    isLoaded() {
+        return this.loaded && this.projects.size > 0;
+    }
+    hasProject(name) {
+        return this.projects.has(name);
+    }
+    totalEntities() {
+        let total = 0;
+        for (const entities of this.projectEntities.values()) {
+            total += entities.length;
+        }
+        return total;
+    }
+}

package/dist/tools/functors.d.ts

@@ -7,18 +7,28 @@
  */
 export declare function findDeadCode(args: {
     include_tests?: boolean;
+    project?: string;
+}): unknown;
+export declare function findLayerViolations(args?: {
+    project?: string;
 }): unknown;
-export declare function findLayerViolations(): unknown;
 export declare function getCouplingMetrics(args: {
     group_by?: 'module' | 'layer';
+    project?: string;
+}): unknown;
+export declare function getAuthMatrix(args?: {
+    project?: string;
+}): unknown;
+export declare function findErrorGaps(args?: {
+    project?: string;
 }): unknown;
-export declare function getAuthMatrix(): unknown;
-export declare function findErrorGaps(): unknown;
 export declare function getTestCoverage(args: {
     weight_by_blast_radius?: boolean;
+    project?: string;
 }): unknown;
 export declare function getOptimalContext(args: {
     target_entity: string;
     max_tokens?: number;
     strategy?: 'bfs' | 'blast_radius';
+    project?: string;
 }): unknown;

package/dist/tools/functors.js

@@ -6,7 +6,7 @@
  * from the primitive dimensions (sigma, epsilon, delta, kappa, chi, tau, rho).
  */
 import { computeBlastRadius } from '../graph.js';
-import { getLoader, getGraph, entityLayer, entitySummary, } from './index.js';
+import { getLoader, getGraph, validateProject, entityLayer, entitySummary, } from './index.js';
 // ─── Layer ordering for violation detection ──────────────────────
 const LAYER_ORDER = {
     route: 0,
@@ -22,10 +22,13 @@ const LAYER_ORDER = {
 };
 // ─── Functor 1: find_dead_code ───────────────────────────────────
 export function findDeadCode(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
     const { include_tests = false } = args;
     const loader = getLoader();
-    const g = getGraph();
-    const entities = loader.getEntities();
+    const g = getGraph(args.project);
+    const entities = loader.getEntities(args.project);
     // Entry points: routes, exported functions, test files, plugin registrations
     const entryPointIds = new Set();
     for (const e of entities) {
@@ -88,8 +91,11 @@ export function findDeadCode(args) {
     };
 }
 // ─── Functor 2: find_layer_violations ────────────────────────────
-export function findLayerViolations() {
-    const g = getGraph();
+export function findLayerViolations(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const g = getGraph(args?.project);
     const violations = [];
     for (const [callerId, calleeIds] of g.callees) {
         const callerEntity = g.entityById.get(callerId);
@@ -142,10 +148,13 @@ export function findLayerViolations() {
 }
 // ─── Functor 3: get_coupling_metrics ─────────────────────────────
 export function getCouplingMetrics(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
     const { group_by = 'module' } = args;
     const loader = getLoader();
-    const g = getGraph();
-    const entities = loader.getEntities();
+    const g = getGraph(args.project);
+    const entities = loader.getEntities(args.project);
     // Group entities
     const groups = new Map();
     for (const e of entities) {
@@ -209,9 +218,12 @@ export function getCouplingMetrics(args) {
     };
 }
 // ─── Functor 4: get_auth_matrix ──────────────────────────────────
-export function getAuthMatrix() {
+export function getAuthMatrix(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
     const loader = getLoader();
-    const entities = loader.getEntities();
+    const entities = loader.getEntities(args?.project);
     const apiEntities = entities.filter(e => {
         const layer = entityLayer(e);
         return layer === 'route' || layer === 'controller' ||
@@ -264,10 +276,13 @@ export function getAuthMatrix() {
     };
 }
 // ─── Functor 5: find_error_gaps ──────────────────────────────────
-export function findErrorGaps() {
+export function findErrorGaps(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
     const loader = getLoader();
-    const g = getGraph();
-    const entities = loader.getEntities();
+    const g = getGraph(args?.project);
+    const entities = loader.getEntities(args?.project);
     // Find all fallible entities (throws === true or has THROWS tag)
     const fallibleIds = new Set();
     for (const e of entities) {
@@ -328,10 +343,13 @@ export function findErrorGaps() {
 }
 // ─── Functor 6: get_test_coverage ────────────────────────────────
 export function getTestCoverage(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
     const { weight_by_blast_radius = false } = args;
     const loader = getLoader();
-    const g = getGraph();
-    const entities = loader.getEntities();
+    const g = getGraph(args.project);
+    const entities = loader.getEntities(args.project);
     // Partition into test and non-test entities
     const testIds = new Set();
     const productionEntities = [];
@@ -402,10 +420,13 @@ export function getTestCoverage(args) {
 }
 // ─── Functor 7: get_optimal_context ──────────────────────────────
 export function getOptimalContext(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
     const { target_entity, max_tokens = 8000, strategy = 'bfs' } = args;
     const loader = getLoader();
-    const g = getGraph();
-    const entity = loader.getEntityById(target_entity) || loader.getEntityByName(target_entity);
+    const g = getGraph(args.project);
+    const entity = loader.getEntityById(target_entity, args.project) || loader.getEntityByName(target_entity, args.project);
     if (!entity) {
         return { error: `Entity not found: ${target_entity}` };
     }

package/dist/tools/index.d.ts

@@ -3,13 +3,22 @@
  *
  * Each tool exposes a dimension or computation over the 9D JSTF-T coordinate space.
  * Tools operate on the in-memory entity bundle loaded from .seshat/_bundle.json.
+ *
+ * Multi-project: when multiple projects are loaded, each tool accepts an optional
+ * `project` parameter. In multi-project mode, `project` is required.
  */
 import type { JstfEntity } from '../types.js';
-import { BundleLoader } from '../loader.js';
+import { MultiLoader } from '../loader.js';
 import { type CallGraph } from '../graph.js';
-export declare function initTools(bundleLoader: BundleLoader): void;
-export declare function getLoader(): BundleLoader;
-export declare function getGraph(): CallGraph;
+export declare function initTools(multiLoader: MultiLoader): void;
+export declare function getLoader(): MultiLoader;
+export declare function getGraph(project?: string): 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 entityName(e: JstfEntity): string;
 export declare function entityLayer(e: JstfEntity): string;
 export declare function entitySummary(e: JstfEntity): Record<string, unknown>;
@@ -20,6 +29,7 @@ export declare function normalizeConstraints(constraints: JstfEntity['constraint
  */
 export declare function constraintMatches(constraints: JstfEntity['constraints'], target: string): boolean;
 export declare function queryEntities(args: {
+    project?: string;
     query?: string;
     layer?: string;
     module?: string;
@@ -28,23 +38,31 @@ export declare function queryEntities(args: {
 }): unknown;
 export declare function getEntity(args: {
     id: string;
+    project?: string;
 }): unknown;
 export declare function getDependencies(args: {
     entity_id: string;
     direction?: 'callers' | 'callees' | 'both';
     depth?: number;
+    project?: string;
 }): 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;
 export declare function findByConstraint(args: {
     constraint: string;
+    project?: string;
 }): unknown;
 export declare function getBlastRadius(args: {
     entity_ids: string[];
+    project?: string;
 }): unknown;
 export declare function listModules(args: {
     group_by?: 'layer' | 'module' | 'file' | 'language';
+    project?: string;
+}): unknown;
+export declare function getTopology(args?: {
+    project?: string;
 }): unknown;
-export declare function getTopology(): unknown;

package/dist/tools/index.js

@@ -3,23 +3,43 @@
  *
  * Each tool exposes a dimension or computation over the 9D JSTF-T coordinate space.
  * Tools operate on the in-memory entity bundle loaded from .seshat/_bundle.json.
+ *
+ * Multi-project: when multiple projects are loaded, each tool accepts an optional
+ * `project` parameter. In multi-project mode, `project` is required.
  */
 import { buildCallGraph, computeBlastRadius } from '../graph.js';
 // Lazy-initialized shared state
 let loader;
-let graph = null;
-export function initTools(bundleLoader) {
-    loader = bundleLoader;
-    graph = null; // Reset graph cache when loader changes
+let graphCache = new Map();
+export function initTools(multiLoader) {
+    loader = multiLoader;
+    graphCache = new Map();
 }
 export function getLoader() {
     return loader;
 }
-export function getGraph() {
-    if (!graph) {
-        graph = buildCallGraph(loader.getEntities());
+export function getGraph(project) {
+    const key = project || '__default__';
+    if (!graphCache.has(key)) {
+        graphCache.set(key, buildCallGraph(loader.getEntities(project)));
+    }
+    return graphCache.get(key);
+}
+/**
+ * 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) {
+    if (!loader.isMultiProject())
+        return null; // single project, always OK
+    if (!project) {
+        return `Multiple projects loaded. You must specify a "project" parameter. Available: ${loader.getProjectNames().join(', ')}`;
+    }
+    if (!loader.hasProject(project)) {
+        return `Project "${project}" not found. Available: ${loader.getProjectNames().join(', ')}`;
     }
-    return graph;
+    return null;
 }
 // ─── Helper: Extract entity name from struct ─────────────────────
 export function entityName(e) {
@@ -54,7 +74,8 @@ export function entityLayer(e) {
         return 'model';
     if (src.includes('/schema') || explicit === 'schema')
         return 'schema';
-    if (src.includes('/test') || src.includes('.test.') || src.includes('.spec.'))
+    if (src.includes('/test/') || src.includes('/tests/') || src.includes('/__tests__/') ||
+        src.includes('.test.') || src.includes('.spec.'))
         return 'test';
     return explicit || 'other';
 }
@@ -63,6 +84,7 @@ export function entitySummary(e) {
     return {
         id: e.id,
         name: entityName(e),
+        ...(e._project ? { project: e._project } : {}),
         layer: entityLayer(e),
         module: e.context?.module || null,
         sourceFile: e._sourceFile || null,
@@ -70,7 +92,10 @@ export function entitySummary(e) {
         async: typeof e.struct !== 'string' ? e.struct?.async : undefined,
         exported: typeof e.struct !== 'string' ? e.struct?.exported : undefined,
         constraints: constraintTags.length > 0 ? constraintTags : undefined,
-        callCount: Array.isArray(e.edges?.calls) ? e.edges.calls.length : 0,
+        callExpressions: Array.isArray(e.edges?.calls) ? e.edges.calls.length : 0,
+        uniqueCallees: Array.isArray(e.edges?.calls)
+            ? new Set(e.edges.calls.map(c => c.target)).size
+            : 0,
     };
 }
 export function normalizeConstraints(constraints) {
@@ -142,8 +167,11 @@ export function constraintMatches(constraints, target) {
 }
 // ─── 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();
+    let results = loader.getEntities(args.project);
     if (layer) {
         results = results.filter(e => entityLayer(e).toLowerCase() === layer.toLowerCase());
     }
@@ -173,7 +201,10 @@ export function queryEntities(args) {
 }
 // ─── Tool: get_entity ─────────────────────────────────────────────
 export function getEntity(args) {
-    const entity = loader.getEntityById(args.id) || loader.getEntityByName(args.id);
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const entity = loader.getEntityById(args.id, args.project) || loader.getEntityByName(args.id, args.project);
     if (!entity) {
         return { error: `Entity not found: ${args.id}` };
     }
@@ -181,6 +212,7 @@ export function getEntity(args) {
     return {
         id: entity.id,
         name: entityName(entity),
+        ...(entity._project ? { project: entity._project } : {}),
         sourceFile: entity._sourceFile,
         sourceLanguage: entity._sourceLanguage,
         jstfFilename: entity._jstfFilename,
@@ -199,9 +231,12 @@ export function getEntity(args) {
 }
 // ─── Tool: get_dependencies ───────────────────────────────────────
 export function getDependencies(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
     const { entity_id, direction = 'both', depth = 2 } = args;
-    const g = getGraph();
-    const entity = loader.getEntityById(entity_id) || loader.getEntityByName(entity_id);
+    const g = getGraph(args.project);
+    const entity = loader.getEntityById(entity_id, args.project) || loader.getEntityByName(entity_id, args.project);
     if (!entity) {
         return { error: `Entity not found: ${entity_id}` };
     }
@@ -252,7 +287,10 @@ export function collectTransitive(adjacency, startId, maxDepth) {
 }
 // ─── Tool: get_data_flow ──────────────────────────────────────────
 export function getDataFlow(args) {
-    const entity = loader.getEntityById(args.entity_id) || loader.getEntityByName(args.entity_id);
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const entity = loader.getEntityById(args.entity_id, args.project) || loader.getEntityByName(args.entity_id, args.project);
     if (!entity) {
         return { error: `Entity not found: ${args.entity_id}` };
     }
@@ -265,8 +303,11 @@ export function getDataFlow(args) {
 }
 // ─── Tool: find_by_constraint ─────────────────────────────────────
 export function findByConstraint(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
     const target = args.constraint;
-    const results = loader.getEntities().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,
@@ -275,12 +316,15 @@ export function findByConstraint(args) {
 }
 // ─── Tool: get_blast_radius ───────────────────────────────────────
 export function getBlastRadius(args) {
-    const g = getGraph();
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const g = getGraph(args.project);
     // Resolve names to IDs
     const resolvedIds = new Set();
     const notFound = [];
     for (const nameOrId of args.entity_ids) {
-        const entity = loader.getEntityById(nameOrId) || loader.getEntityByName(nameOrId);
+        const entity = loader.getEntityById(nameOrId, args.project) || loader.getEntityByName(nameOrId, args.project);
         if (entity) {
             resolvedIds.add(entity.id);
         }
@@ -309,8 +353,11 @@ export function getBlastRadius(args) {
 }
 // ─── Tool: list_modules ───────────────────────────────────────────
 export function listModules(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
     const { group_by = 'layer' } = args;
-    const entities = loader.getEntities();
+    const entities = loader.getEntities(args.project);
     const groups = new Map();
     for (const e of entities) {
         let key;
@@ -342,8 +389,11 @@ export function listModules(args) {
     };
 }
 // ─── Tool: get_topology ───────────────────────────────────────────
-export function getTopology() {
-    const topology = loader.getTopology();
+export function getTopology(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const topology = loader.getTopology(args?.project);
     if (!topology) {
         return { error: 'No topology data found. The _topology.json file may not have been generated.' };
     }

package/dist/types.d.ts

@@ -11,6 +11,7 @@ export interface JstfEntity {
     _jstfFilename?: string;
     _sourceFile?: string | null;
     _sourceLanguage?: string;
+    _project?: string;
     /** σ — Structure: function shape, signature, modifiers */
     struct?: {
         name?: string;
@@ -145,3 +146,12 @@ export interface Manifest {
     languages: string[];
     layers: Record<string, number>;
 }
+export interface ProjectInfo {
+    name: string;
+    path: string;
+    entityCount: number;
+    languages: string[];
+    commitSha: string;
+    extractedAt: string;
+    layers: Record<string, number>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Semantic MCP server — exposes a codebase's 9D JSTF-T coordinate space as queryable tools",
   "type": "module",
   "bin": {