@papyruslabsai/seshat-mcp 0.12.0 → 0.12.2

package/dist/index.d.ts

@@ -1 +1,9 @@
+#!/usr/bin/env node
+/**
+ * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server (Cloud Proxy)
+ *
+ * This CLI server declares the full suite of Seshat tools to Claude/AI clients,
+ * but executes all logic remotely on the Ptah Cloud API for zero-conflict
+ * collaboration and deep analytics.
+ */
 export {};

package/dist/index.js

@@ -1,97 +1,73 @@
-!/usr/bin / env;
-node;
+#!/usr/bin/env node
 /**
- * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server
+ * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server (Cloud Proxy)
  *
- * 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
+ * This CLI server declares the full suite of Seshat tools to Claude/AI clients,
+ * but executes all logic remotely on the Ptah Cloud API for zero-conflict
+ * collaboration and deep analytics.
  */
 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 { MultiLoader } from './loader.js';
-import { bootstrap } from './bootstrap.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 ───────────────────────────────────────────
-/**
- * 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);
+const TIER_ORDER = ['cartographer', 'analyst', 'architect'];
+const TOOL_TIERS = {
+    // Cartographer (free) — explore and navigate
+    list_projects: 'cartographer',
+    query_entities: 'cartographer',
+    get_entity: 'cartographer',
+    get_dependencies: 'cartographer',
+    get_data_flow: 'cartographer',
+    find_by_constraint: 'cartographer',
+    get_blast_radius: 'cartographer',
+    list_modules: 'cartographer',
+    get_topology: 'cartographer',
+    get_optimal_context: 'cartographer',
+    // Analyst (tier 2) — audit and analyze
+    find_dead_code: 'analyst',
+    find_layer_violations: 'analyst',
+    get_coupling_metrics: 'analyst',
+    get_auth_matrix: 'analyst',
+    find_error_gaps: 'analyst',
+    get_test_coverage: 'analyst',
+    find_runtime_violations: 'analyst',
+    find_ownership_violations: 'analyst',
+    query_traits: 'analyst',
+    find_exposure_leaks: 'analyst',
+    find_semantic_clones: 'analyst',
+    // Architect (tier 3) — simulate, estimate, and act
+    estimate_task_cost: 'architect',
+    simulate_mutation: 'architect',
+    create_symbol: 'architect',
+    diff_bundle: 'architect',
+    conflict_matrix: 'architect',
+    query_data_targets: 'architect',
+};
+const TIER_LABELS = {
+    cartographer: 'Cartographer (Free)',
+    analyst: 'Analyst (Tier 2)',
+    architect: 'Architect (Tier 3)',
+};
+function tierAtLeast(userTier, requiredTier) {
+    return TIER_ORDER.indexOf(userTier) >= TIER_ORDER.indexOf(requiredTier);
 }
-// ─── Project param definition (injected into all tool schemas) ───
+// ─── Project param definition ───
 const projectParam = {
     type: 'string',
     description: 'Project name (required in multi-project mode). Use list_projects to see available projects.',
 };
 // ─── Tool Definitions ─────────────────────────────────────────────
 const TOOLS = [
+    {
+        name: 'get_account_status',
+        description: 'Check your Ptah account: current tier, Ptah Credits balance, and which tools are available or locked. Call this to see what you can do and what upgrades are available.',
+        inputSchema: { type: 'object', properties: {} },
+    },
     {
         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: {},
-        },
+        inputSchema: { type: 'object', properties: {} },
     },
     {
         name: 'query_entities',
@@ -100,26 +76,11 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                query: {
-                    type: 'string',
-                    description: 'Search term — matches against entity name, ID, source file, and module',
-                },
-                layer: {
-                    type: 'string',
-                    description: 'Filter by architectural layer: route, controller, service, repository, utility, hook, component, schema',
-                },
-                module: {
-                    type: 'string',
-                    description: 'Filter by module (partial match)',
-                },
-                language: {
-                    type: 'string',
-                    description: 'Filter by source language: javascript, typescript, python, go, rust, etc.',
-                },
-                limit: {
-                    type: 'number',
-                    description: 'Max results to return (default: 50)',
-                },
+                query: { type: 'string', description: 'Search term — matches against entity name, ID, source file, and module' },
+                layer: { type: 'string', description: 'Filter by architectural layer: route, controller, service, repository, utility, hook, component, schema' },
+                module: { type: 'string', description: 'Filter by module (partial match)' },
+                language: { type: 'string', description: 'Filter by source language: javascript, typescript, python, go, rust, etc.' },
+                limit: { type: 'number', description: 'Max results to return (default: 50)' },
             },
         },
     },
@@ -130,10 +91,7 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                id: {
-                    type: 'string',
-                    description: 'Entity ID or name',
-                },
+                id: { type: 'string', description: 'Entity ID or name' },
             },
             required: ['id'],
         },
@@ -145,19 +103,9 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                entity_id: {
-                    type: 'string',
-                    description: 'Entity ID or name',
-                },
-                direction: {
-                    type: 'string',
-                    enum: ['callers', 'callees', 'both'],
-                    description: 'Which direction to traverse (default: both)',
-                },
-                depth: {
-                    type: 'number',
-                    description: 'How many levels deep to traverse (default: 2)',
-                },
+                entity_id: { type: 'string', description: 'Entity ID or name' },
+                direction: { type: 'string', enum: ['callers', 'callees', 'both'], description: 'Which direction to traverse (default: both)' },
+                depth: { type: 'number', description: 'How many levels deep to traverse (default: 2)' },
             },
             required: ['entity_id'],
         },
@@ -169,10 +117,7 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                entity_id: {
-                    type: 'string',
-                    description: 'Entity ID or name',
-                },
+                entity_id: { type: 'string', description: 'Entity ID or name' },
             },
             required: ['entity_id'],
         },
@@ -184,10 +129,7 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                constraint: {
-                    type: 'string',
-                    description: 'Constraint tag to search for: AUTH, VALIDATED, PURE, THROWS, DB_ACCESS, NETWORK_IO, IMP, etc.',
-                },
+                constraint: { type: 'string', description: 'Constraint tag to search for: AUTH, VALIDATED, PURE, THROWS, DB_ACCESS, NETWORK_IO, IMP, etc.' },
             },
             required: ['constraint'],
         },
@@ -199,11 +141,7 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                entity_ids: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Array of entity IDs or names to compute blast radius for',
-                },
+                entity_ids: { type: 'array', items: { type: 'string' }, description: 'Array of entity IDs or names to compute blast radius for' },
             },
             required: ['entity_ids'],
         },
@@ -215,25 +153,33 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                group_by: {
-                    type: 'string',
-                    enum: ['layer', 'module', 'file', 'language'],
-                    description: 'How to group entities (default: layer)',
-                },
+                group_by: { type: 'string', enum: ['layer', 'module', 'file', 'language'], description: 'How to group entities (default: layer)' },
             },
         },
     },
     {
         name: 'get_topology',
         description: 'Get the API topology: routes, plugins, auth patterns, and database tables. Built from architectural context and dependency analysis across all entities.',
+        inputSchema: {
+            type: 'object',
+            properties: { project: projectParam },
+        },
+    },
+    {
+        name: 'get_optimal_context',
+        description: 'Compute the optimal set of related entities to include in an LLM context window for a target entity. Uses greedy knapsack: maximizes relevance per token. Returns entities ranked by relevance with token estimates.',
         inputSchema: {
             type: 'object',
             properties: {
                 project: projectParam,
+                target_entity: { type: 'string', description: 'Entity ID or name to build context around' },
+                max_tokens: { type: 'number', description: 'Token budget for the context window (default: 8000)' },
+                strategy: { type: 'string', enum: ['bfs', 'blast_radius'], description: 'Traversal strategy: bfs (faster, local neighborhood) or blast_radius (full affected set)' },
             },
+            required: ['target_entity'],
         },
     },
-    // ─── Analysis Tools ─────────────────────────────────────────────
+    // ─── Analyst Tools (Tier 2) ───────────────────────────────────────
     {
         name: 'find_dead_code',
         description: 'Find unreachable entities (dead code candidates). BFS from entry points (routes, exported functions, tests, plugins) through the call graph. Entities not reachable from any entry point are flagged.',
@@ -241,21 +187,16 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                include_tests: {
-                    type: 'boolean',
-                    description: 'Include test entities in dead code results (default: false)',
-                },
+                include_tests: { type: 'boolean', description: 'Include test entities in dead code results (default: false)' },
             },
         },
     },
     {
         name: 'find_layer_violations',
-        description: 'Detect architectural layer violations in the call graph. Finds backward calls (lower layer calling higher layer, e.g. repository → route) and skip-layer calls (jumping over multiple layers). Uses architectural layer classification.',
+        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).',
         inputSchema: {
             type: 'object',
-            properties: {
-                project: projectParam,
-            },
+            properties: { project: projectParam },
         },
     },
     {
@@ -265,11 +206,7 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                group_by: {
-                    type: 'string',
-                    enum: ['module', 'layer'],
-                    description: 'Group entities by module or layer (default: module)',
-                },
+                group_by: { type: 'string', enum: ['module', 'layer'], description: 'Group entities by module or layer (default: module)' },
             },
         },
     },
@@ -278,9 +215,7 @@ const TOOLS = [
         description: 'Analyze authentication coverage across all API-facing entities. Shows which routes/controllers have auth requirements and which don\'t. Detects inconsistencies like DB access without auth.',
         inputSchema: {
             type: 'object',
-            properties: {
-                project: projectParam,
-            },
+            properties: { project: projectParam },
         },
     },
     {
@@ -288,9 +223,7 @@ const TOOLS = [
         description: 'Find error handling gaps: entities that throw or have network/db side effects whose callers lack try/catch. These are crash risk points where exceptions can propagate unhandled.',
         inputSchema: {
             type: 'object',
-            properties: {
-                project: projectParam,
-            },
+            properties: { project: projectParam },
         },
     },
     {
@@ -300,143 +233,70 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                weight_by_blast_radius: {
-                    type: 'boolean',
-                    description: 'Rank uncovered entities by blast radius to prioritize testing (default: false, slower)',
-                },
+                weight_by_blast_radius: { type: 'boolean', description: 'Rank uncovered entities by blast radius to prioritize testing (default: false, slower)' },
             },
         },
     },
     {
-        name: 'get_optimal_context',
-        description: 'Compute the optimal set of related entities to include in an LLM context window for a target entity. Uses greedy knapsack: maximizes relevance per token. Returns entities ranked by relevance with token estimates.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                project: projectParam,
-                target_entity: {
-                    type: 'string',
-                    description: 'Entity ID or name to build context around',
-                },
-                max_tokens: {
-                    type: 'number',
-                    description: 'Token budget for the context window (default: 8000)',
-                },
-                strategy: {
-                    type: 'string',
-                    enum: ['bfs', 'blast_radius'],
-                    description: 'Traversal strategy: bfs (faster, local neighborhood) or blast_radius (full affected set)',
-                },
-            },
-            required: ['target_entity'],
-        },
+        name: 'find_runtime_violations',
+        description: 'Analyze the call graph for runtime environment leaks. Finds architectural boundary issues where framework-agnostic code improperly imports framework-specific code.',
+        inputSchema: { type: 'object', properties: { project: projectParam } },
     },
     {
-        name: 'estimate_task_cost',
-        description: 'Estimate token cost of a code change BEFORE starting work. Computes blast radius, sums source token counts across affected entities, and projects total token burn including iteration cycles. Call this before planning to check if a task fits within your token budget.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                project: projectParam,
-                target_entities: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Entity IDs or names that will be modified',
-                },
-                context_budget: {
-                    type: 'number',
-                    description: 'LLM context window token budget (default: 200000)',
-                },
-            },
-            required: ['target_entities'],
-        },
+        name: 'find_ownership_violations',
+        description: 'Analyze the codebase for memory and lifecycle constraints. Flags entities with complex ownership rules, unsafe blocks, escaping boundaries, or illegal mutability patterns on borrowed references.',
+        inputSchema: { type: 'object', properties: { project: projectParam } },
     },
     {
-        name: 'report_actual_burn',
-        description: 'Close the calibration feedback loop: report actual token usage against a prior prediction from estimate_task_cost. Computes drift (actual - predicted) / predicted. Also supports listing recent predictions with aggregate calibration stats, or abandoning predictions for cancelled tasks.',
+        name: 'query_traits',
+        description: 'Search the codebase for specific functional capabilities. Allows you to find entities by their abstract traits (e.g., "fallible", "asyncContext", "generator") regardless of their structural syntax.',
         inputSchema: {
             type: 'object',
             properties: {
-                prediction_id: {
-                    type: 'string',
-                    description: 'The prediction ID returned by estimate_task_cost. Required for complete/abandon actions.',
-                },
-                actual_input_tokens: {
-                    type: 'number',
-                    description: 'Actual input tokens consumed (from LLM usage metadata).',
-                },
-                actual_output_tokens: {
-                    type: 'number',
-                    description: 'Actual output tokens consumed (from LLM usage metadata).',
-                },
-                actual_total_tokens: {
-                    type: 'number',
-                    description: 'Actual total tokens consumed (input + output).',
-                },
-                model: {
-                    type: 'string',
-                    description: 'Model used (e.g. claude-opus-4-6, claude-sonnet-4-6).',
-                },
-                action: {
-                    type: 'string',
-                    enum: ['complete', 'abandon', 'list'],
-                    description: 'Action: "complete" reports actuals (default), "abandon" marks prediction as cancelled, "list" shows recent predictions with calibration stats.',
-                },
                 project: projectParam,
-                notes: {
-                    type: 'string',
-                    description: 'Optional notes about the task outcome.',
-                },
+                trait: { type: 'string', description: 'The trait or capability to search for (e.g., "fallible", "asyncContext")' },
             },
+            required: ['trait'],
         },
     },
-    // ─── Analysis & Impact Tools ───────────────────────────────────
     {
-        name: 'find_runtime_violations',
-        description: 'Analyze the call graph for runtime environment leaks. Finds architectural boundary issues where framework-agnostic code improperly imports framework-specific code (e.g. pure logic calling React hooks) or where incompatible frameworks mix directly.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                project: projectParam,
-            },
-        },
+        name: 'find_exposure_leaks',
+        description: 'Analyze the call graph for architectural visibility leaks. Flags paths where a "public" or "api" entity directly accesses a "private" internal entity.',
+        inputSchema: { type: 'object', properties: { project: projectParam } },
     },
     {
-        name: 'find_ownership_violations',
-        description: 'Analyze the codebase for memory and lifecycle constraints. Flags entities with complex ownership rules, unsafe blocks, escaping boundaries, or illegal mutability patterns on borrowed references.',
+        name: 'find_semantic_clones',
+        description: 'Analyze the codebase for duplicated logic blocks. Normalizes variables and compares code structure to identify identical algorithms written across different files or even different languages.',
         inputSchema: {
             type: 'object',
             properties: {
                 project: projectParam,
+                min_complexity: { type: 'number', description: 'Minimum number of logic expressions required to constitute a match (default: 5).' },
             },
         },
     },
+    // ─── Architect Tools (Tier 3) ─────────────────────────────────────
     {
-        name: 'query_traits',
-        description: 'Search the codebase for specific functional capabilities. Allows you to find entities by their abstract traits (e.g., "fallible", "asyncContext", "generator") regardless of their structural syntax.',
+        name: 'estimate_task_cost',
+        description: 'Estimate token cost of a code change BEFORE starting work. Computes blast radius, sums source token counts across affected entities, and projects total token burn including iteration cycles. Call this before planning to check if a task fits within your token budget.',
         inputSchema: {
             type: 'object',
             properties: {
                 project: projectParam,
-                trait: {
-                    type: 'string',
-                    description: 'The trait or capability to search for (e.g., "fallible", "asyncContext")',
-                },
+                target_entities: { type: 'array', items: { type: 'string' }, description: 'Entity IDs or names that will be modified' },
+                context_budget: { type: 'number', description: 'LLM context window token budget (default: 200000)' },
             },
-            required: ['trait'],
+            required: ['target_entities'],
         },
     },
     {
         name: 'simulate_mutation',
-        description: 'The Impact Simulator. Proposes a hypothetical change to an entity (like adding a "fallible" or "auth" requirement) and simulates the architectural fallout upstream and downstream. Returns a blueprint of exactly which other entities will break and what fixes they require.',
+        description: 'The Impact Simulator. Proposes a hypothetical change to an entity and simulates the architectural fallout upstream and downstream. Returns a blueprint of exactly which other entities will break and what fixes they require.',
         inputSchema: {
             type: 'object',
             properties: {
                 project: projectParam,
-                entity_id: {
-                    type: 'string',
-                    description: 'The target entity to analyze.',
-                },
+                entity_id: { type: 'string', description: 'The target entity to analyze.' },
                 mutation: {
                     type: 'object',
                     description: 'The hypothetical change to apply.',
@@ -456,73 +316,21 @@ const TOOLS = [
             required: ['entity_id', 'mutation'],
         },
     },
-    {
-        name: 'query_data_targets',
-        description: 'Search the codebase for data interactions to find all entities that read or write to a specific database table, state object, or data source. This acts as a reverse-index for data flow, essential for planning migrations or state refactors.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                project: projectParam,
-                target_name: {
-                    type: 'string',
-                    description: 'The name of the database table, state object, or data source to query (e.g., "users", "auth_token").',
-                },
-            },
-            required: ['target_name'],
-        },
-    },
-    {
-        name: 'find_exposure_leaks',
-        description: 'Analyze the call graph for architectural visibility leaks. Flags paths where a "public" or "api" entity directly accesses a "private" internal entity, potentially leaking sensitive data or bypassing internal service boundaries.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                project: projectParam,
-            },
-        },
-    },
-    {
-        name: 'find_semantic_clones',
-        description: 'Analyze the codebase for duplicated logic blocks. Normalizes variables and compares code structure to identify identical algorithms written across different files or even different languages.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                project: projectParam,
-                min_complexity: {
-                    type: 'number',
-                    description: 'Minimum number of logic expressions required to constitute a match (default: 5).',
-                },
-            },
-        },
-    },
     {
         name: 'create_symbol',
-        description: 'Register a new code symbol in the architectural graph. This does not write to disk, but allows the Impact Simulator and Conflict Matrix to reason about a symbol that is pending creation. Essential for planning new features that introduce new files or modules.',
+        description: 'Register a new code symbol in the architectural graph. This does not write to disk, but allows the Impact Simulator and Conflict Matrix to reason about a symbol that is pending creation.',
         inputSchema: {
             type: 'object',
             properties: {
                 project: projectParam,
-                id: {
-                    type: 'string',
-                    description: 'The unique ID or name for the new symbol.',
-                },
-                source_file: {
-                    type: 'string',
-                    description: 'The relative path to the file where this symbol will be created.',
-                },
-                layer: {
-                    type: 'string',
-                    description: 'The architectural layer (e.g., "service", "route", "component").',
-                },
-                description: {
-                    type: 'string',
-                    description: 'Brief description of the symbol\'s purpose.',
-                },
+                id: { type: 'string', description: 'The unique ID or name for the new symbol.' },
+                source_file: { type: 'string', description: 'The relative path to the file where this symbol will be created.' },
+                layer: { type: 'string', description: 'The architectural layer (e.g., "service", "route", "component").' },
+                description: { type: 'string', description: 'Brief description of the symbol\'s purpose.' },
             },
             required: ['id', 'source_file'],
         },
     },
-    // ─── Diff Tools ─────────────────────────────────────────────────  
     {
         name: 'diff_bundle',
         description: 'Compare code structure between a worktree and the loaded project. Shows which symbols were added, removed, or modified — not a line diff, but a structural diff showing changed signatures, dependencies, and implementation logic.',
@@ -530,14 +338,8 @@ const TOOLS = [
             type: 'object',
             properties: {
                 project: projectParam,
-                worktree_path: {
-                    type: 'string',
-                    description: 'Absolute path to the worktree or branch checkout to compare against the loaded project',
-                },
-                include_unchanged: {
-                    type: 'boolean',
-                    description: 'Include unchanged entities in the output (default: false)',
-                },
+                worktree_path: { type: 'string', description: 'Absolute path to the worktree or branch checkout to compare against the loaded project' },
+                include_unchanged: { type: 'boolean', description: 'Include unchanged entities in the output (default: false)' },
             },
             required: ['worktree_path'],
         },
@@ -554,24 +356,10 @@ const TOOLS = [
                     items: {
                         type: 'object',
                         properties: {
-                            id: {
-                                type: 'string',
-                                description: 'Unique task identifier (e.g. "add-dark-mode")',
-                            },
-                            entity_ids: {
-                                type: 'array',
-                                items: { type: 'string' },
-                                description: 'Symbol names or IDs that this task will modify',
-                            },
-                            dimensions: {
-                                type: 'array',
-                                items: { type: 'string' },
-                                description: 'Optional: Code scopes this task will modify. (Legacy support, no longer required for Tier 2 safety).',
-                            },
-                            expand_blast_radius: {
-                                type: 'boolean',
-                                description: 'Include transitively affected symbols in the conflict check (default: false)',
-                            },
+                            id: { type: 'string', description: 'Unique task identifier (e.g. "add-dark-mode")' },
+                            entity_ids: { type: 'array', items: { type: 'string' }, description: 'Symbol names or IDs that this task will modify' },
+                            dimensions: { type: 'array', items: { type: 'string' }, description: 'Optional: Code scopes this task will modify.' },
+                            expand_blast_radius: { type: 'boolean', description: 'Include transitively affected symbols in the conflict check (default: false)' },
                         },
                         required: ['id', 'entity_ids'],
                     },
@@ -581,230 +369,187 @@ const TOOLS = [
             required: ['tasks'],
         },
     },
+    {
+        name: 'query_data_targets',
+        description: 'Search the codebase for data interactions to find all entities that read or write to a specific database table, state object, or data source.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                target_name: { type: 'string', description: 'The name of the database table, state object, or data source to query (e.g., "users", "auth_token").' },
+            },
+            required: ['target_name'],
+        },
+    },
 ];
-// ─── Server Setup ─────────────────────────────────────────────────
-async function main() {
-    // Discover and load projects
-    const projectDirs = discoverProjects();
-    let loader = new MultiLoader(projectDirs);
-    try {
-        loader.load();
+// ─── Project Resolution (Fallback) ────────────────────────────────
+function resolveProjectName() {
+    // If SESHAT_PROJECTS is set to a single name, use it
+    if (process.env.SESHAT_PROJECTS && !process.env.SESHAT_PROJECTS.includes(',') && !process.env.SESHAT_PROJECTS.includes('*')) {
+        return path.basename(process.env.SESHAT_PROJECTS);
     }
-    catch (err) {
-        process.stderr.write(`Warning: ${err.message}\n`);
+    // Fallback to reading local manifest if it exists
+    const manifestPath = path.join(process.cwd(), '.seshat', 'manifest.json');
+    if (fs.existsSync(manifestPath)) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+            if (manifest.projectName)
+                return manifest.projectName;
+        }
+        catch { }
     }
-    // Auto-bootstrap: if no projects loaded, try to extract from CWD
-    if (!loader.isLoaded() && !process.env.SESHAT_PROJECTS) {
-        const cwd = process.cwd();
-        const seshatDir = path.join(cwd, '.seshat');
-        // Only bootstrap when .seshat/ doesn't exist at all (not corruption)
-        if (!fs.existsSync(seshatDir)) {
-            process.stderr.write(`[seshat-mcp] No .seshat/ found — attempting auto-bootstrap...\n`);
-            const result = await bootstrap(cwd);
-            if (result.success) {
-                // Re-create loader and retry
-                loader = new MultiLoader([cwd]);
-                try {
-                    loader.load();
-                    process.stderr.write(`[seshat-mcp] Auto-bootstrap succeeded: ${loader.totalEntities()} entities loaded\n`);
-                }
-                catch (err) {
-                    process.stderr.write(`[seshat-mcp] Auto-bootstrap produced files but load failed: ${err.message}\n`);
+    // Ultimate fallback to directory name
+    return path.basename(process.cwd());
+}
+// ─── Cloud API helper ─────────────────────────────────────────────
+function getCloudUrl(path) {
+    const base = process.env.PTAH_CLOUD_URL || 'https://api.papyruslabs.ai';
+    // If PTAH_CLOUD_URL includes a full path (legacy), strip it back to the base
+    const baseUrl = base.replace(/\/api\/mcp\/execute\/?$/, '');
+    return `${baseUrl}${path}`;
+}
+// ─── Server Setup ─────────────────────────────────────────────────
+async function main() {
+    const server = new Server({
+        name: 'seshat-mcp-cloud-proxy',
+        version: '0.12.2',
+    }, {
+        capabilities: { tools: {} },
+    });
+    // ─── #3: Dynamic ListTools with tier annotations ──────────────
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const apiKey = process.env.SESHAT_API_KEY;
+        let userTier = 'cartographer';
+        let credits = 0;
+        // Attempt to fetch account status from the cloud for tier-aware descriptions
+        if (apiKey) {
+            try {
+                const res = await fetch(getCloudUrl('/api/mcp/account'), {
+                    method: 'GET',
+                    headers: { 'x-api-key': apiKey },
+                });
+                if (res.ok) {
+                    const account = await res.json();
+                    userTier = account.tier || 'cartographer';
+                    credits = account.credits || 0;
                 }
             }
-            else {
-                process.stderr.write(`[seshat-mcp] Auto-bootstrap failed: ${result.error || 'unknown error'}\n`);
-                process.stderr.write(`[seshat-mcp] Starting with 0 entities. Run extraction manually or push to trigger CI.\n`);
+            catch {
+                // If the account endpoint is unavailable, fall back to showing all tools unlabeled
             }
         }
-    }
-    initTools(loader);
-    // 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: serverLabel,
-        version: '0.5.0',
-    }, {
-        capabilities: {
-            tools: {},
-        },
+        const annotatedTools = TOOLS.map((tool) => {
+            const requiredTier = TOOL_TIERS[tool.name];
+            if (!requiredTier)
+                return tool; // get_account_status — always available
+            const hasAccess = tierAtLeast(userTier, requiredTier);
+            if (hasAccess)
+                return tool;
+            // Annotate locked tools with tier requirement
+            return {
+                ...tool,
+                description: `[LOCKED — requires ${TIER_LABELS[requiredTier]}] ${tool.description}`,
+            };
+        });
+        return { tools: annotatedTools };
     });
-    // List available tools
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: TOOLS,
-    }));
-    // Handle tool calls
+    // ─── CallTool handler with #1 (_meta piggyback) and #2 (get_account_status) ──
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
-        const startTime = Date.now();
-        try {
-            if (!loader.isLoaded()) {
+        const apiKey = process.env.SESHAT_API_KEY;
+        if (!apiKey) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: 'SESHAT_API_KEY environment variable is required to use Ptah Cloud tools.' }, null, 2) }],
+                isError: true,
+            };
+        }
+        // ─── #2: get_account_status tool ──────────────────────────────
+        if (name === 'get_account_status') {
+            try {
+                const res = await fetch(getCloudUrl('/api/mcp/account'), {
+                    method: 'GET',
+                    headers: { 'x-api-key': apiKey },
+                });
+                if (!res.ok) {
+                    const errorText = await res.text();
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({ error: `Failed to fetch account status (${res.status}): ${errorText}` }, null, 2) }],
+                        isError: true,
+                    };
+                }
+                const account = await res.json();
+                const userTier = account.tier || 'cartographer';
+                const credits = account.credits || 0;
+                // Build tool availability breakdown
+                const toolsByTier = {
+                    cartographer: { available: [], locked: [] },
+                    analyst: { available: [], locked: [] },
+                    architect: { available: [], locked: [] },
+                };
+                for (const [toolName, requiredTier] of Object.entries(TOOL_TIERS)) {
+                    const bucket = tierAtLeast(userTier, requiredTier) ? 'available' : 'locked';
+                    toolsByTier[requiredTier][bucket].push(toolName);
+                }
                 return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                error: 'No projects loaded. Ensure .seshat/_bundle.json exists or set SESHAT_PROJECTS env var.',
-                            }, null, 2),
-                        }],
+                    content: [{ type: 'text', text: JSON.stringify({
+                                tier: userTier,
+                                tier_label: TIER_LABELS[userTier],
+                                ptah_credits: credits,
+                                tools: toolsByTier,
+                                upgrade_url: 'https://ptah.papyruslabs.ai/settings/billing',
+                            }, 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;
-                case 'get_entity':
-                    result = getEntity(args);
-                    break;
-                case 'get_dependencies':
-                    result = getDependencies(args);
-                    break;
-                case 'get_data_flow':
-                    result = getDataFlow(args);
-                    break;
-                case 'find_by_constraint':
-                    result = findByConstraint(args);
-                    break;
-                case 'get_blast_radius':
-                    result = getBlastRadius(args);
-                    break;
-                case 'list_modules':
-                    result = listModules(args);
-                    break;
-                case 'get_topology':
-                    result = getTopology(args);
-                    break;
-                // Analysis Tools
-                case 'find_dead_code':
-                    result = findDeadCode(args);
-                    break;
-                case 'find_layer_violations':
-                    result = findLayerViolations(args);
-                    break;
-                case 'get_coupling_metrics':
-                    result = getCouplingMetrics(args);
-                    break;
-                case 'get_auth_matrix':
-                    result = getAuthMatrix(args);
-                    break;
-                case 'find_error_gaps':
-                    result = findErrorGaps(args);
-                    break;
-                case 'get_test_coverage':
-                    result = getTestCoverage(args);
-                    break;
-                case 'get_optimal_context':
-                    result = getOptimalContext(args);
-                    break;
-                case 'estimate_task_cost':
-                    result = await estimateTaskCost(args);
-                    break;
-                case 'report_actual_burn':
-                    result = await reportActualBurn(args);
-                    break;
-                // Analysis & Impact Tools
-                case 'find_runtime_violations':
-                    result = find_runtime_violations(args);
-                    break;
-                case 'find_ownership_violations':
-                    result = find_ownership_violations(args);
-                    break;
-                case 'query_traits':
-                    result = query_traits(args);
-                    break;
-                case 'simulate_mutation':
-                    result = simulate_mutation(args);
-                    break;
-                case 'query_data_targets':
-                    result = query_data_targets(args);
-                    break;
-                case 'find_exposure_leaks':
-                    result = find_exposure_leaks(args);
-                    break;
-                case 'find_semantic_clones':
-                    result = find_semantic_clones(args);
-                    break;
-                case 'create_symbol':
-                    result = create_symbol(args);
-                    break;
-                // Diff Tools
-                case 'diff_bundle':
-                    result = await diffBundle(args);
-                    break;
-                case 'conflict_matrix':
-                    result = conflictMatrix(args);
-                    break;
-                default:
-                    result = { error: `Unknown tool: ${name}` };
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ error: `Account status check failed: ${err.message}` }, null, 2) }],
+                    isError: true,
+                };
             }
-            // 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(() => { });
+        }
+        // Determine the project hash for this workspace
+        const project_hash = (args && typeof args === 'object' && 'project' in args)
+            ? String(args.project)
+            : resolveProjectName();
+        try {
+            // Proxy the tool call to the cloud
+            const res = await fetch(getCloudUrl('/api/mcp/execute'), {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': apiKey
+                },
+                body: JSON.stringify({
+                    tool: name,
+                    project_hash,
+                    args
+                })
+            });
+            if (!res.ok) {
+                const errorText = await res.text();
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ error: `Cloud API Error (${res.status}): ${errorText}` }, null, 2) }],
+                    isError: true
+                };
             }
+            const result = await res.json();
+            // ─── #1: _meta piggyback — append account context to every response ──
+            // The cloud API includes _meta in its response when available.
+            // If it doesn't, we pass through the result as-is.
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify(result, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             };
         }
         catch (err) {
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            error: `Tool ${name} failed: ${err.message}`,
-                        }, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify({ error: `Cloud proxy failed: ${err.message}` }, null, 2) }],
                 isError: true,
             };
         }
     });
-    // Start stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    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`);
-    }
+    process.stderr.write(`Seshat Cloud Proxy started. Routing requests to Ptah API...\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

package/dist/tools/diff.d.ts

@@ -7,6 +7,7 @@
  * These tools compare TWO entity sets (base vs branch, or task vs task),
  * unlike the single-bundle queries in index.ts and functors.ts.
  */
+import type { ProjectLoader } from '../types.js';
 export declare function diffBundle(args: {
     worktree_path: string;
     project?: string;

package/dist/tools/functors.d.ts

@@ -5,7 +5,7 @@
  * Each tool computes derived insights (dead code, layer violations,
  * coupling metrics, auth coverage, etc.) from the entity data.
  */
-import type { JstfEntity } from '../types.js';
+import type { JstfEntity, ProjectLoader } from '../types.js';
 /**
  * Estimate the token cost of loading an entity's source code into an LLM context.
  * Uses real sourceTokens from the extraction pipeline when available (v0.3.2+),
@@ -16,19 +16,19 @@ export declare function findDeadCode(args: {
     include_tests?: boolean;
     project?: string;
 }, loader: ProjectLoader): unknown;
-export declare function findLayerViolations(args?: {
+export declare function findLayerViolations(args: {
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function getCouplingMetrics(args: {
     group_by?: 'module' | 'layer';
     project?: string;
 }, loader: ProjectLoader): unknown;
-export declare function getAuthMatrix(args?: {
+export declare function getAuthMatrix(args: {
     project?: string;
-}): unknown;
-export declare function findErrorGaps(args?: {
+}, loader: ProjectLoader): unknown;
+export declare function findErrorGaps(args: {
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function getTestCoverage(args: {
     weight_by_blast_radius?: boolean;
     project?: string;
@@ -66,12 +66,12 @@ export declare function reportActualBurn(args: {
     project?: string;
     notes?: string;
 }, loader: ProjectLoader): Promise<unknown>;
-export declare function find_runtime_violations(args?: {
+export declare function find_runtime_violations(args: {
     project?: string;
-}): unknown;
-export declare function find_ownership_violations(args?: {
+}, loader: ProjectLoader): unknown;
+export declare function find_ownership_violations(args: {
     project?: string;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function query_traits(args: {
     trait: string;
     project?: string;
@@ -91,13 +91,13 @@ export declare function query_data_targets(args: {
     target_name: string;
     project?: string;
 }, loader: ProjectLoader): unknown;
-export declare function find_exposure_leaks(args?: {
+export declare function find_exposure_leaks(args: {
     project?: string;
-}): unknown;
-export declare function find_semantic_clones(args?: {
+}, loader: ProjectLoader): unknown;
+export declare function find_semantic_clones(args: {
     project?: string;
     min_complexity?: number;
-}): unknown;
+}, loader: ProjectLoader): unknown;
 export declare function create_symbol(args: {
     id: string;
     source_file: string;

package/dist/tools/functors.js

@@ -151,7 +151,7 @@ export function findDeadCode(args, loader) {
     };
 }
 // ─── Tool: find_layer_violations ─────────────────────────────────
-export function findLayerViolations(args) {
+export function findLayerViolations(args, loader) {
     const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
@@ -278,7 +278,7 @@ export function getCouplingMetrics(args, loader) {
     };
 }
 // ─── Tool: get_auth_matrix ───────────────────────────────────────
-export function getAuthMatrix(args) {
+export function getAuthMatrix(args, loader) {
     const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
@@ -335,7 +335,7 @@ export function getAuthMatrix(args) {
     };
 }
 // ─── Tool: find_error_gaps ───────────────────────────────────────
-export function findErrorGaps(args) {
+export function findErrorGaps(args, loader) {
     const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
@@ -822,7 +822,7 @@ export async function reportActualBurn(args, loader) {
     };
 }
 // ─── Tool: find_runtime_violations (Runtime Context) ────────────
-export function find_runtime_violations(args) {
+export function find_runtime_violations(args, loader) {
     const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
@@ -863,7 +863,7 @@ export function find_runtime_violations(args) {
     };
 }
 // ─── Tool: find_ownership_violations (Ownership & Lifetimes) ─────
-export function find_ownership_violations(args) {
+export function find_ownership_violations(args, loader) {
     const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
@@ -1079,7 +1079,7 @@ export function query_data_targets(args, loader) {
     };
 }
 // ─── Tool: find_exposure_leaks (Architectural Visibility) ───────
-export function find_exposure_leaks(args) {
+export function find_exposure_leaks(args, loader) {
     const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };
@@ -1114,7 +1114,7 @@ export function find_exposure_leaks(args) {
 }
 // ─── Tool: find_semantic_clones (Logic Analysis) ────────────────
 import { createHash } from 'crypto';
-export function find_semantic_clones(args) {
+export function find_semantic_clones(args, loader) {
     const projErr = validateProject(args?.project, loader);
     if (projErr)
         return { error: projErr };

package/dist/tools/index.d.ts

@@ -7,7 +7,7 @@
  * 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 type { JstfEntity, ProjectLoader } from '../types.js';
 import { type CallGraph } from '../graph.js';
 export declare function getGraph(project: string | undefined, loader: ProjectLoader): CallGraph;
 /**

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
   "type": "module",
   "bin": {
     "seshat-mcp": "./dist/index.js"
   },
   "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./tools": "./dist/tools/index.js",
+    "./functors": "./dist/tools/functors.js",
+    "./diff": "./dist/tools/diff.js",
+    "./types": "./dist/types.js"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",