@papyruslabsai/seshat-mcp 0.12.2 → 0.13.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server (Cloud Proxy)
+ * @papyruslabs/seshat-mcp — Structural 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.
+ * Declares the Seshat tool suite to Claude/AI clients. All tool calls are
+ * proxied to the Ptah Cloud API. Tool descriptions are written as triggers —
+ * they tell the LLM *when* to reach for each tool, not just what it does.
  */
 export {};

package/dist/index.js

@@ -1,16 +1,29 @@
 #!/usr/bin/env node
 /**
- * @papyruslabs/seshat-mcp — Semantic Code Analysis MCP Server (Cloud Proxy)
+ * @papyruslabs/seshat-mcp — Structural 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.
+ * Declares the Seshat tool suite to Claude/AI clients. All tool calls are
+ * proxied to the Ptah Cloud API. Tool descriptions are written as triggers —
+ * they tell the LLM *when* to reach for each tool, not just what it does.
  */
 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';
+// ─── 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.
+
+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
+
+Start with list_projects to see what's loaded. All tools are read-only and safe to call speculatively.
+
+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'];
 const TOOL_TIERS = {
     // Cartographer (free) — explore and navigate
@@ -52,41 +65,51 @@ const TIER_LABELS = {
 function tierAtLeast(userTier, requiredTier) {
     return TIER_ORDER.indexOf(userTier) >= TIER_ORDER.indexOf(requiredTier);
 }
-// ─── Project param definition ───
+// ─── Shared Definitions ──────────────────────────────────────────
 const projectParam = {
     type: 'string',
     description: 'Project name (required in multi-project mode). Use list_projects to see available projects.',
 };
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const READ_ONLY_OPEN = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 // ─── Tool Definitions ─────────────────────────────────────────────
+// Descriptions are written as TRIGGERS: they tell the LLM when to
+// reach for the tool, what it returns, and how it compares to built-in
+// alternatives like grep/Read.
 const TOOLS = [
+    // ─── Always Visible ───────────────────────────────────────────────
     {
         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.',
+        description: 'See your current plan, available tools, and credit balance. Call this if a tool returns a tier error or you want to know what tools are available.',
         inputSchema: { type: 'object', properties: {} },
+        annotations: READ_ONLY_OPEN,
     },
+    // ─── Cartographer (Free Tier) ─────────────────────────────────────
     {
         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.',
+        description: 'Start here. Returns all synced codebases with their size, language, and project name. You need the project name for every other tool.',
         inputSchema: { type: 'object', properties: {} },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'query_entities',
-        description: 'Search code entities by name, architectural layer (route/service/repository/component), module, or source language. Returns entity summaries with constraint tags.',
+        description: 'Like grep but for code structure. Find functions, classes, and routes by name, architectural layer (route/service/component), or module. Returns matching symbols with their type, file, and layer — use this instead of grep when you need to find code by what it does, not by text content.',
         inputSchema: {
             type: 'object',
             properties: {
                 project: projectParam,
-                query: { type: 'string', description: 'Search term — matches against entity name, ID, source file, and module' },
+                query: { type: 'string', description: 'Search term — matches against symbol 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)' },
             },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'get_entity',
-        description: 'Get complete details for a specific code entity. Returns structure, call graph, data flow, constraints, context, ownership, type info, runtime, and logic.',
+        description: 'Get everything about one function or class — its signature, callers, callees, data flow, constraints, and source location. Use this when you need to deeply understand a single symbol before modifying it. Returns more than reading the source file because it includes the dependency context.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -95,10 +118,11 @@ const TOOLS = [
             },
             required: ['id'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'get_dependencies',
-        description: 'Traverse the call graph for an entity. Shows callers (who calls this), callees (what this calls), and imports. Supports depth-limited traversal for exploring transitive dependencies.',
+        description: 'Trace who calls a function and what it calls, up to N levels deep. Use this instead of grep-for-function-name when you need the actual call chain — returns the dependency graph, not text matches. Covers callers (upstream), callees (downstream), or both.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -109,10 +133,11 @@ const TOOLS = [
             },
             required: ['entity_id'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'get_data_flow',
-        description: 'Get data flow for an entity: what data flows in (inputs/sources), what flows out (outputs/returns), and what gets mutated (database writes, state changes).',
+        description: 'See what data a function reads, returns, and mutates (DB writes, state changes). Use this when debugging data bugs or when you need to verify whether a function has side effects before refactoring it.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -121,10 +146,11 @@ const TOOLS = [
             },
             required: ['entity_id'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'find_by_constraint',
-        description: 'Search entities by behavioral properties. Find functions by security properties (AUTH, VALIDATED), behavioral properties (PURE, THROWS, DB_ACCESS, NETWORK_IO), or performance characteristics.',
+        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?"',
         inputSchema: {
             type: 'object',
             properties: {
@@ -133,10 +159,11 @@ const TOOLS = [
             },
             required: ['constraint'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'get_blast_radius',
-        description: 'Compute the blast radius for a set of entities. Returns all transitively affected entities — both upstream (callers) and downstream (callees) — with depth annotations showing distance from the change.',
+        description: 'Before modifying a function, call this to see everything that could break. Returns all transitively affected symbols — both upstream callers and downstream callees — with distance from the change point. Like git log --follow but for runtime impact. Designed for repeated use: as you discover new symbols with other tools, call this again on them to expand your understanding of the affected surface.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -145,10 +172,11 @@ const TOOLS = [
             },
             required: ['entity_ids'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'list_modules',
-        description: 'List and count entities grouped by a property. See the architectural structure (by layer), module organization (by module), file distribution (by file), or language breakdown (by language).',
+        description: 'Get a bird\'s-eye view of how the codebase is organized. Groups all symbols by architectural layer (route/service/component), module, file, or language with counts. Use this to orient yourself in an unfamiliar codebase before diving into specifics.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -156,18 +184,20 @@ const TOOLS = [
                 group_by: { type: 'string', enum: ['layer', 'module', 'file', 'language'], description: 'How to group entities (default: layer)' },
             },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        description: 'Get the full API surface map in one call — all routes, middleware, auth patterns, and database tables. Use this when you need to understand the overall architecture without reading every file. Returns the information you\'d normally piece together from dozens of file reads.',
         inputSchema: {
             type: 'object',
             properties: { project: projectParam },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        description: 'Before working on a function, call this to get the most relevant related code ranked by importance and fitted to a token budget. Returns a prioritized reading list of symbols you should understand — better than guessing which files to open. Designed for iterative use: call it on your target, read the top results, then call it again on any surprising dependencies to build a complete picture.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -178,11 +208,12 @@ const TOOLS = [
             },
             required: ['target_entity'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     // ─── 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.',
+        description: 'Find functions that nothing calls. Walks the call graph from all entry points (routes, exports, tests) and flags symbols that are unreachable. Use this during cleanup or before a release to find safe deletion candidates.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -190,18 +221,20 @@ const TOOLS = [
                 include_tests: { type: 'boolean', description: 'Include test entities in dead code results (default: false)' },
             },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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).',
+        description: 'Find places where the architecture is broken — a database repository calling a route handler, a utility importing a component. Returns every backward or skip-layer dependency that violates clean architecture.',
         inputSchema: {
             type: 'object',
             properties: { project: projectParam },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'get_coupling_metrics',
-        description: 'Compute coupling, cohesion, and instability metrics for modules or layers. Analyzes dependency edges between and within groups. High coupling + low cohesion = candidates for refactoring.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -209,26 +242,29 @@ const TOOLS = [
                 group_by: { type: 'string', enum: ['module', 'layer'], description: 'Group entities by module or layer (default: module)' },
             },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'get_auth_matrix',
-        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.',
+        description: 'Audit authentication coverage. Shows which API routes and controllers require auth and which don\'t, plus inconsistencies like database access without auth checks. Use this for security reviews.',
         inputSchema: {
             type: 'object',
             properties: { project: projectParam },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'find_error_gaps',
-        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.',
+        description: 'Find crash risks: functions that throw or have network/DB side effects whose callers don\'t catch errors. Returns the specific caller→callee pairs where exceptions can propagate unhandled. Use this before shipping to find missing error handling.',
         inputSchema: {
             type: 'object',
             properties: { project: projectParam },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'get_test_coverage',
-        description: 'Compute semantic test coverage: which production entities are exercised by test entities via the call graph. Optionally weight uncovered entities by blast radius to prioritize what to test first.',
+        description: 'See which production functions are actually exercised by tests via the call graph — semantic coverage, not line coverage. Optionally ranks uncovered functions by blast radius so you know which missing tests are riskiest.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -236,20 +272,23 @@ const TOOLS = [
                 weight_by_blast_radius: { type: 'boolean', description: 'Rank uncovered entities by blast radius to prioritize testing (default: false, slower)' },
             },
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        description: 'Find architectural boundary leaks where framework-agnostic code imports framework-specific code. Use this when separating core logic from framework dependencies.',
         inputSchema: { type: 'object', properties: { project: projectParam } },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        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.',
         inputSchema: { type: 'object', properties: { project: projectParam } },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -258,27 +297,30 @@ const TOOLS = [
             },
             required: ['trait'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        description: 'Find places where public/API code directly accesses private internals, bypassing the intended abstraction boundary. Use this during API design reviews or before extracting a module.',
         inputSchema: { type: 'object', properties: { project: projectParam } },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        description: 'Find duplicated logic across the codebase. Normalizes variable names and compares code structure to catch identical algorithms in different files — even across different languages. Use this before a DRY refactor.',
         inputSchema: {
             type: 'object',
             properties: {
                 project: projectParam,
-                min_complexity: { type: 'number', description: 'Minimum number of logic expressions required to constitute a match (default: 5).' },
+                min_complexity: { type: 'number', description: 'Minimum logic expressions to count as a match (default: 5)' },
             },
         },
+        annotations: READ_ONLY_OPEN,
     },
     // ─── Architect Tools (Tier 3) ─────────────────────────────────────
     {
         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.',
+        description: 'Before starting a code change, estimate how many tokens it will consume. Computes the blast radius, sums source tokens across all affected symbols, and projects total burn including iteration cycles. Use this to check if a task fits your context budget before committing to it.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -288,10 +330,11 @@ const TOOLS = [
             },
             required: ['target_entities'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'simulate_mutation',
-        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.',
+        description: 'Simulate a hypothetical code change without writing anything. Propose adding or removing constraints/traits on a symbol and see which other symbols would break and what fixes they\'d need. Use this to plan a change before making it.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -315,10 +358,11 @@ const TOOLS = [
             },
             required: ['entity_id', 'mutation'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        description: 'Register a planned new symbol in the graph before it exists on disk. This lets simulate_mutation and conflict_matrix reason about code you haven\'t written yet. Nothing is written to disk.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -330,23 +374,25 @@ const TOOLS = [
             },
             required: ['id', 'source_file'],
         },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     {
         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.',
+        description: 'Compare a worktree against the loaded project to see what changed structurally — not a line diff, but which symbols were added, removed, or had their signatures/dependencies changed. Use this after making changes to verify the structural impact.',
         inputSchema: {
             type: 'object',
             properties: {
                 project: projectParam,
-                worktree_path: { type: 'string', description: 'Absolute path to the worktree or branch checkout to compare against the loaded project' },
+                worktree_path: { type: 'string', description: 'Absolute path to the worktree or branch checkout to compare' },
                 include_unchanged: { type: 'boolean', description: 'Include unchanged entities in the output (default: false)' },
             },
             required: ['worktree_path'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         name: 'conflict_matrix',
-        description: 'Given multiple tasks, classify every task pair into conflict tiers to determine parallelization safety. Tier 1 (different files, safe), Tier 2 (same file, different symbols, safe via surgical splicing), Tier 3 (same symbol, MUST sequence to maintain splice integrity). Returns a pairwise matrix and a suggested execution plan.',
+        description: 'Given multiple planned tasks, check which ones can run in parallel safely. Classifies every task pair: Tier 1 (different files, safe), Tier 2 (same file different symbols, careful), Tier 3 (same symbol, must sequence). Returns a matrix and suggested execution order.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -363,23 +409,25 @@ const TOOLS = [
                         },
                         required: ['id', 'entity_ids'],
                     },
-                    description: 'Array of tasks to check for conflicts. Each task specifies which entities it will modify.',
+                    description: 'Array of tasks to check for conflicts.',
                 },
             },
             required: ['tasks'],
         },
+        annotations: READ_ONLY_OPEN,
     },
     {
         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.',
+        description: 'Find every function that reads from or writes to a specific database table, state object, or data source. Use this when you need to understand all the code paths that touch a particular data store.',
         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").' },
+                target_name: { type: 'string', description: 'The name of the database table, state object, or data source (e.g., "users", "auth_token").' },
             },
             required: ['target_name'],
         },
+        annotations: READ_ONLY_OPEN,
     },
 ];
 // ─── Project Resolution (Fallback) ────────────────────────────────
@@ -411,17 +459,17 @@ function getCloudUrl(path) {
 // ─── Server Setup ─────────────────────────────────────────────────
 async function main() {
     const server = new Server({
-        name: 'seshat-mcp-cloud-proxy',
-        version: '0.12.2',
+        name: 'seshat',
+        version: '0.13.0',
     }, {
         capabilities: { tools: {} },
+        instructions: SERVER_INSTRUCTIONS,
     });
-    // ─── #3: Dynamic ListTools with tier annotations ──────────────
+    // ─── Dynamic ListTools — only expose tools the user can access ──
     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
+        // Fetch account status to determine which tools to expose
         if (apiKey) {
             try {
                 const res = await fetch(getCloudUrl('/api/mcp/account'), {
@@ -431,39 +479,32 @@ async function main() {
                 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
+                // If unavailable, default to cartographer (free tier tools only)
             }
         }
-        const annotatedTools = TOOLS.map((tool) => {
+        // Only return tools the user's tier can actually use
+        const visibleTools = TOOLS.filter((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 true; // get_account_status — always visible
+            return tierAtLeast(userTier, requiredTier);
         });
-        return { tools: annotatedTools };
+        return { tools: visibleTools };
     });
-    // ─── CallTool handler with #1 (_meta piggyback) and #2 (get_account_status) ──
+    // ─── CallTool handler ──────────────────────────────────────────
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         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) }],
+                content: [{ type: 'text', text: JSON.stringify({ error: 'SESHAT_API_KEY environment variable is required. Get your free key at https://ptah.papyruslabs.ai' }, null, 2) }],
                 isError: true,
             };
         }
-        // ─── #2: get_account_status tool ──────────────────────────────
+        // ─── get_account_status ──────────────────────────────────────
         if (name === 'get_account_status') {
             try {
                 const res = await fetch(getCloudUrl('/api/mcp/account'), {
@@ -533,9 +574,18 @@ 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.
+            // Separate _meta into assistant-only content so it doesn't clutter
+            // the user-visible response. The LLM still sees it for context.
+            if (result._meta) {
+                const meta = result._meta;
+                delete result._meta;
+                return {
+                    content: [
+                        { type: 'text', text: JSON.stringify(result, null, 2) },
+                        { type: 'text', text: JSON.stringify({ _meta: meta }), annotations: { audience: ['assistant'], priority: 0.2 } },
+                    ],
+                };
+            }
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             };
@@ -549,7 +599,7 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`Seshat Cloud Proxy started. Routing requests to Ptah API...\n`);
+    process.stderr.write(`Seshat MCP v0.13.0 connected. Structural code analysis ready.\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

package/package.json

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