@papyruslabsai/seshat-mcp 0.13.1 → 0.13.3

package/dist/index.js

@@ -13,20 +13,29 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 // ─── Server Instructions ─────────────────────────────────────────
 // Sent to the LLM at connection time. This is the "first contact" pitch.
-const SERVER_INSTRUCTIONS = `Seshat provides structural code analysis backed by a compiled intermediate representation — not heuristic guesses or text search. Every function, class, and route in the synced codebase has been extracted into a typed symbol graph with dependency edges, data flow, constraints, and architectural layer tags.
+const SERVER_INSTRUCTIONS = `Seshat provides structural code analysis backed by a compiled intermediate representation — not heuristic guesses or text search. Every function, class, and route in the synced codebase has been extracted into a typed symbol graph with dependency edges, data flow, constraints, and architectural layer tags. Results are precise and complete — if Seshat says a function has 3 callers, it has exactly 3 callers.
 
-Use these tools instead of grep/Read when you need to understand code structure:
-- "Who calls this function?" → get_dependencies (not grep for the function name)
-- "What breaks if I change this?" → get_blast_radius (not guessing from imports)
-- "Which functions touch the database?" → find_by_constraint with DB_ACCESS
-- "How is this codebase organized?" → list_modules or get_topology
+Use Seshat tools instead of grep/Read when you need to understand code structure. Each tool maps to a question you're already asking:
+- "What projects are loaded?" → list_projects
+- "How is the codebase organized?" → list_modules
+- "What's the full API surface?" → get_topology
+- "Find functions by name or layer" → query_entities
+- "Deep-dive a single function" → get_entity
+- "Who calls this / what does it call?" → get_dependencies
+- "What breaks if I change this?" → get_blast_radius
+- "What data does this read/write/mutate?" → get_data_flow
+- "Which functions touch the DB / require auth / throw?" → find_by_constraint
+- "Which endpoints require auth and which don't?" → get_auth_matrix
+- "Where is sensitive data exposed without protection?" → find_exposure_leaks
+- "What should I read before modifying X?" → get_optimal_context
+- "What tier am I on / what tools are available?" → get_account_status
 
-Start with list_projects to see what's loaded. All tools are read-only and safe to call speculatively.
+All tools are read-only and safe to call speculatively — there is no cost to trying them.
 
-get_blast_radius and get_optimal_context are designed for iterative use. As you learn more about the codebase from other tools, call them again with new targets — each call refines your understanding. When answering "what does this system do?" questions, a few rounds of blast_radius → get_entity → blast_radius on the newly discovered symbols will build a complete picture faster than reading files.`;
-const TIER_ORDER = ['cartographer', 'analyst', 'architect'];
+get_blast_radius and get_optimal_context are designed to be called iteratively. Start with any entity, then feed discovered entities back in to expand your understanding. Each round reveals new structure that informs where to look next. When answering "what does this system do?" questions, a few rounds of blast_radius → get_entity → blast_radius on the newly discovered symbols will build a complete picture faster than reading files.`;
+const TIER_ORDER = ['cartographer', 'analyst', 'architect', 'founder'];
 const TOOL_TIERS = {
-    // Cartographer (free) — explore and navigate
+    // Cartographer (free) — explore, navigate, and assess security surface
     list_projects: 'cartographer',
     query_entities: 'cartographer',
     get_entity: 'cartographer',
@@ -37,17 +46,17 @@ const TOOL_TIERS = {
     list_modules: 'cartographer',
     get_topology: 'cartographer',
     get_optimal_context: 'cartographer',
-    // Analyst (tier 2) — audit and analyze
+    get_auth_matrix: 'cartographer',
+    find_exposure_leaks: 'cartographer',
+    // Analyst (tier 2) — audit and diagnose
     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',
@@ -61,6 +70,7 @@ const TIER_LABELS = {
     cartographer: 'Cartographer (Free)',
     analyst: 'Analyst (Tier 2)',
     architect: 'Architect (Tier 3)',
+    founder: 'Founder (All Access)',
 };
 function tierAtLeast(userTier, requiredTier) {
     return TIER_ORDER.indexOf(userTier) >= TIER_ORDER.indexOf(requiredTier);
@@ -150,7 +160,7 @@ const TOOLS = [
     },
     {
         name: 'find_by_constraint',
-        description: 'Find every function with a specific behavior tag — AUTH (requires authentication), DB_ACCESS (touches database), THROWS (can throw), PURE (no side effects), NETWORK_IO (makes HTTP calls), VALIDATED (has input validation). Use this when you need to answer questions like "which functions write to the database?" or "what endpoints lack auth?"',
+        description: 'Find every function with a specific syntactic constraint tag — AUTH (requires authentication), DB_ACCESS (touches database), THROWS (explicit throw statement), PURE (no side effects), NETWORK_IO (makes HTTP calls), VALIDATED (has input validation). Constraints are extracted from source syntax, not inferred. Use this when you need to answer "which functions write to the database?" or "what endpoints lack auth?" For semantic/behavioral properties (e.g., "can fail transitively"), use query_traits instead.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -234,7 +244,7 @@ const TOOLS = [
     },
     {
         name: 'get_coupling_metrics',
-        description: 'Measure how tangled modules are. Returns coupling (cross-module dependencies), cohesion (within-module dependencies), and instability scores. High coupling + low cohesion = refactoring candidates. Use this when planning a refactor to find the worst offenders.',
+        description: 'Measure how tangled your code is. Returns coupling (cross-boundary dependencies), cohesion (within-group dependencies), and instability scores. High coupling + low cohesion = refactoring candidates. Start with group_by: "layer" for the architectural health view ("are my controllers more coupled than my services?"), then drill into group_by: "module" for specific hotspots.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -276,19 +286,19 @@ const TOOLS = [
     },
     {
         name: 'find_runtime_violations',
-        description: 'Find architectural boundary leaks where framework-agnostic code imports framework-specific code. Use this when separating core logic from framework dependencies.',
+        description: 'Find architectural boundary leaks where framework-agnostic code imports framework-specific code. Use this when separating core logic from framework dependencies. Returns 0 for most JS/Python codebases — a non-zero result indicates a serious boundary violation worth investigating.',
         inputSchema: { type: 'object', properties: { project: projectParam } },
         annotations: READ_ONLY_OPEN,
     },
     {
         name: 'find_ownership_violations',
-        description: 'Find memory and lifecycle issues — entities with complex ownership, unsafe blocks, escaping references, or illegal mutability on borrowed data. Most useful for Rust and C++ codebases.',
+        description: 'Find memory and lifecycle issues — entities with complex ownership, unsafe blocks, escaping references, or illegal mutability on borrowed data. Returns 0 for most JS/Python codebases — a non-zero result in those languages indicates a serious boundary violation worth investigating. Most detailed results for Rust and C++.',
         inputSchema: { type: 'object', properties: { project: projectParam } },
         annotations: READ_ONLY_OPEN,
     },
     {
         name: 'query_traits',
-        description: 'Find functions by abstract capability regardless of syntax — "fallible" (can fail), "asyncContext" (carries async state), "generator" (yields values). Use this when you need to find all code with a specific behavioral trait across the entire codebase.',
+        description: 'Find functions by inferred behavioral trait — "fallible" (can fail, including transitively via callees that throw), "asyncContext" (carries async state), "generator" (yields values). Traits are semantic properties inferred from the call graph, not just syntax. Use this when you need to find all code with a specific capability. For syntactic tags (explicit throw statements, DB access), use find_by_constraint instead.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -460,7 +470,7 @@ function getCloudUrl(path) {
 async function main() {
     const server = new Server({
         name: 'seshat',
-        version: '0.13.0',
+        version: '0.13.3',
     }, {
         capabilities: { tools: {} },
         instructions: SERVER_INSTRUCTIONS,
@@ -521,24 +531,37 @@ async function main() {
                 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: [] },
-                };
+                // Build response: lead with what you CAN do, not what you can't
+                const availableTools = [];
+                const upgradeTeaser = {};
                 for (const [toolName, requiredTier] of Object.entries(TOOL_TIERS)) {
-                    const bucket = tierAtLeast(userTier, requiredTier) ? 'available' : 'locked';
-                    toolsByTier[requiredTier][bucket].push(toolName);
+                    if (tierAtLeast(userTier, requiredTier)) {
+                        availableTools.push(toolName);
+                    }
+                    else {
+                        if (!upgradeTeaser[TIER_LABELS[requiredTier]]) {
+                            upgradeTeaser[TIER_LABELS[requiredTier]] = [];
+                        }
+                        upgradeTeaser[TIER_LABELS[requiredTier]].push(toolName);
+                    }
+                }
+                const response = {
+                    tier: userTier,
+                    tier_label: TIER_LABELS[userTier],
+                    ptah_credits: credits,
+                    your_tools: availableTools,
+                    tool_count: `${availableTools.length} tools available`,
+                };
+                // Only mention upgrades if there are locked tools, and frame positively
+                if (Object.keys(upgradeTeaser).length > 0) {
+                    const totalLocked = Object.values(upgradeTeaser).reduce((sum, t) => sum + t.length, 0);
+                    response.upgrades_available = {
+                        summary: `${totalLocked} additional diagnostic and simulation tools available with a tier upgrade — find dead code, coupling hotspots, test gaps, layer violations, and simulate changes before making them.`,
+                        url: 'https://ptah.papyruslabs.ai/settings/billing',
+                    };
                 }
                 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) }],
+                    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
                 };
             }
             catch (err) {
@@ -599,7 +622,7 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`Seshat MCP v0.13.0 connected. Structural code analysis ready.\n`);
+    process.stderr.write(`Seshat MCP v0.13.1 connected. Structural code analysis ready.\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

package/dist/tools/functors.js

@@ -135,6 +135,15 @@ export function findDeadCode(args, loader) {
     if (!include_tests) {
         deadEntities = deadEntities.filter((e) => entityLayer(e) !== 'test');
     }
+    // Separate schemas — they're often registered dynamically (e.g., fastify.addSchema())
+    // and appear "dead" from a static call graph but are alive at runtime.
+    const SCHEMA_TYPES = new Set(['schema', 'typealias', 'interface', 'type']);
+    const schemaEntities = deadEntities.filter((e) => {
+        const type = (typeof e.struct === 'string' ? e.struct : e.struct?.type || '').toLowerCase();
+        const layer = entityLayer(e);
+        return SCHEMA_TYPES.has(type) || layer === 'schema';
+    });
+    deadEntities = deadEntities.filter((e) => !schemaEntities.includes(e));
     // Group by layer for overview
     const byLayer = new Map();
     for (const e of deadEntities) {
@@ -148,6 +157,10 @@ export function findDeadCode(args, loader) {
         deadCount: deadEntities.length,
         deadByLayer: Object.fromEntries([...byLayer.entries()].sort((a, b) => b[1] - a[1])),
         dead: deadEntities.slice(0, 100).map(entitySummary),
+        ...(schemaEntities.length > 0 ? {
+            schemas_excluded: schemaEntities.length,
+            _note_schemas: `${schemaEntities.length} schema/type definitions excluded — no static references found, but schemas are often registered dynamically (e.g., fastify.addSchema()) and may be alive at runtime.`,
+        } : {}),
     };
 }
 // ─── Tool: find_layer_violations ─────────────────────────────────

package/package.json

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