@papyruslabsai/seshat-mcp 0.12.1 → 0.12.2

package/dist/index.js

@@ -11,6 +11,47 @@ 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';
+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 ───
 const projectParam = {
     type: 'string',
@@ -18,6 +59,11 @@ const projectParam = {
 };
 // ─── 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.',
@@ -119,7 +165,21 @@ const TOOLS = [
             properties: { project: projectParam },
         },
     },
-    // ─── Analysis Tools ─────────────────────────────────────────────
+    {
+        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'],
+        },
+    },
+    // ─── 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.',
@@ -178,70 +238,55 @@ const TOOLS = [
         },
     },
     {
-        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.',
+        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: '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: {
                 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)' },
+                trait: { type: 'string', description: 'The trait or capability to search for (e.g., "fallible", "asyncContext")' },
             },
-            required: ['target_entities'],
+            required: ['trait'],
         },
     },
     {
-        name: 'report_actual_burn',
-        description: 'Close the calibration feedback loop: report actual token usage against a prior prediction from estimate_task_cost.',
+        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_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: {
-                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.' },
+                min_complexity: { type: 'number', description: 'Minimum number of logic expressions required to constitute a match (default: 5).' },
             },
         },
     },
-    // ─── 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.',
-        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.',
-        inputSchema: { type: 'object', properties: { project: projectParam } },
-    },
+    // ─── 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'],
         },
     },
     {
@@ -271,34 +316,6 @@ 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.',
-        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.',
-        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.',
@@ -314,7 +331,6 @@ const TOOLS = [
             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.',
@@ -353,6 +369,18 @@ 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'],
+        },
+    },
 ];
 // ─── Project Resolution (Fallback) ────────────────────────────────
 function resolveProjectName() {
@@ -373,20 +401,61 @@ function resolveProjectName() {
     // 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: '1.0.0',
+        version: '0.12.2',
     }, {
         capabilities: { tools: {} },
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: 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;
+                }
+            }
+            catch {
+                // If the account endpoint is unavailable, fall back to showing all tools unlabeled
+            }
+        }
+        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 };
+    });
+    // ─── CallTool handler with #1 (_meta piggyback) and #2 (get_account_status) ──
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
-        // We expect the user to provide an API key for the cloud service
         const apiKey = process.env.SESHAT_API_KEY;
         if (!apiKey) {
             return {
@@ -394,14 +463,57 @@ async function main() {
                 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({
+                                tier: userTier,
+                                tier_label: TIER_LABELS[userTier],
+                                ptah_credits: credits,
+                                tools: toolsByTier,
+                                upgrade_url: 'https://ptah.papyruslabs.ai/settings/billing',
+                            }, null, 2) }],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ error: `Account status check failed: ${err.message}` }, null, 2) }],
+                    isError: true,
+                };
+            }
+        }
         // Determine the project hash for this workspace
         const project_hash = (args && typeof args === 'object' && 'project' in args)
             ? String(args.project)
             : resolveProjectName();
-        const PTAH_CLOUD_URL = process.env.PTAH_CLOUD_URL || 'https://api.papyruslabs.ai/api/mcp/execute';
         try {
-            // Blindly proxy the tool call to the cloud
-            const res = await fetch(PTAH_CLOUD_URL, {
+            // Proxy the tool call to the cloud
+            const res = await fetch(getCloudUrl('/api/mcp/execute'), {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
@@ -421,6 +533,9 @@ async function main() {
                 };
             }
             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) }],
             };

package/package.json

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