@papyruslabsai/seshat-mcp 0.14.2 → 0.16.0

package/dist/index.js

@@ -6,7 +6,6 @@
  * 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';
@@ -15,136 +14,63 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 // 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. Results are precise and complete — if Seshat says a function has 3 callers, it has exactly 3 callers.
 
+GETTING STARTED — If list_projects returns empty, the current project hasn't been synced yet. Use the sync_project tool to import it:
+1. Detect the git remote: run \`git remote get-url origin\` in the user's terminal
+2. Call sync_project with that repo URL
+3. Wait for extraction to complete (typically 5-30 seconds depending on repo size)
+4. Then call list_projects again — the project will now appear
+Note: For private repos, sync_project will return a GitHub authorization URL. Direct the user to open it in their browser to connect their GitHub account, then retry sync_project. Once connected, all future private repo syncs work automatically.
+
 Use Seshat tools instead of grep/Read when you need to understand code structure. Each tool maps to a question you're already asking:
+
+Setup & Navigation:
 - "What projects are loaded?" → list_projects
+- "Sync this repo to Seshat" → sync_project
 - "How is the codebase organized?" → list_modules
 - "What's the full API surface?" → get_topology
+- "What tier am I on / what tools are available?" → get_account_status
+
+Understanding Code:
 - "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
+- "What should I read before modifying X?" → get_optimal_context
 - "Which functions touch the DB / require auth / throw?" → find_by_constraint
 - "What reads or writes the 'users' table?" → find_by_constraint(table="users")
+- "Find functions that can fail, including transitively" → query_traits(trait="fallible")
+
+Change Planning:
+- "What breaks if I change this?" → get_blast_radius
+- "Is there dead code I can safely delete?" → find_dead_code
+- "Is there copy-pasted logic I should consolidate?" → find_semantic_clones
+
+Security & Quality Audits:
 - "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
+- "Where are errors thrown but never caught?" → find_error_gaps
+- "Are there architecture violations (e.g. routes calling repos directly)?" → find_layer_violations
+- "Does framework-agnostic code import framework-specific code?" → find_runtime_violations
+- "Are there memory/lifecycle/ownership issues?" → find_ownership_violations
+
+Metrics:
+- "How coupled is the codebase? Where are the hotspots?" → get_coupling_metrics
+- "Which functions are tested and which aren't?" → get_test_coverage
 
 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 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', 'pro', 'analyst', 'architect', 'founder'];
-const REVELATION_ORDER = ['core', 'navigate', 'security', 'quality', 'full'];
-// Which tools appear at each stage (cumulative — each stage includes all previous)
-const TOOL_REVELATION = {
-    // Always visible
-    get_account_status: 'core',
-    list_projects: 'core',
-    // Core loop — the curiosity engine (available immediately)
-    get_entity: 'core',
-    get_blast_radius: 'core',
-    get_dependencies: 'core',
-    get_optimal_context: 'core',
-    // Navigation — after agent starts exploring (revealed after ~3 queries)
-    query_entities: 'navigate',
-    list_modules: 'navigate',
-    get_topology: 'navigate',
-    get_data_flow: 'navigate',
-    find_by_constraint: 'navigate',
-    // Security surface — after architecture is understood (~8 queries)
-    get_auth_matrix: 'security',
-    find_exposure_leaks: 'security',
-    // Quality & audit — after deep exploration (~15 queries)
-    find_dead_code: 'quality',
-    find_layer_violations: 'quality',
-    get_coupling_metrics: 'quality',
-    find_error_gaps: 'quality',
-    get_test_coverage: 'quality',
-    find_runtime_violations: 'quality',
-    find_ownership_violations: 'quality',
-    query_traits: 'quality',
-    find_semantic_clones: 'quality',
-    // Architect — always gated by tier, shown when quality is visible
-    estimate_task_cost: 'full',
-    simulate_mutation: 'full',
-    create_symbol: 'full',
-    diff_bundle: 'full',
-    conflict_matrix: 'full',
-    query_data_targets: 'full',
-};
-// Query thresholds for each stage transition
-const REVELATION_THRESHOLDS = {
-    core: 0, // Immediate
-    navigate: 3, // After a few core loop calls
-    security: 8, // After architecture is understood
-    quality: 15, // After deep exploration
-    full: 25, // Power user territory
-};
-// Session state for progressive revelation
-let _sessionQueryCount = 0;
-let _currentStage = 'core';
-let _serverRef = null; // Stored so we can send notifications
-function stageAtLeast(current, required) {
-    return REVELATION_ORDER.indexOf(current) >= REVELATION_ORDER.indexOf(required);
-}
-function checkRevelation() {
-    for (const stage of REVELATION_ORDER) {
-        if (_sessionQueryCount >= REVELATION_THRESHOLDS[stage]) {
-            if (REVELATION_ORDER.indexOf(stage) > REVELATION_ORDER.indexOf(_currentStage)) {
-                const previousStage = _currentStage;
-                _currentStage = stage;
-                // Notify client that tool list has changed
-                if (_serverRef) {
-                    _serverRef.notification({ method: 'notifications/tools/list_changed' });
-                    process.stderr.write(`[Seshat] Revelation: ${previousStage} → ${stage} (${_sessionQueryCount} queries). Notified client.\n`);
-                }
-            }
-        }
-    }
-}
-const TOOL_TIERS = {
-    // Cartographer (free) — explore, navigate, and assess security surface
-    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',
-    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',
-    find_error_gaps: 'analyst',
-    get_test_coverage: 'analyst',
-    find_runtime_violations: 'analyst',
-    find_ownership_violations: 'analyst',
-    query_traits: '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)',
-    pro: 'Seshat Pro',
-    analyst: 'Seshat Shield',
-    architect: 'Architect',
-    founder: 'Founder (All Access)',
-};
-function tierAtLeast(userTier, requiredTier) {
-    return TIER_ORDER.indexOf(userTier) >= TIER_ORDER.indexOf(requiredTier);
-}
+// ─── Private Tools (Ptah IP — never exposed publicly) ────────────
+// These tools are reserved for the Ptah write layer. They exist in
+// the codebase but are never listed, never hinted at, never mentioned.
+const PRIVATE_TOOLS = new Set([
+    'estimate_task_cost',
+    'simulate_mutation',
+    'create_symbol',
+    'diff_bundle',
+    'conflict_matrix',
+    'query_data_targets',
+]);
 // ─── Shared Definitions ──────────────────────────────────────────
 const projectParam = {
     type: 'string',
@@ -167,10 +93,21 @@ const TOOLS = [
     // ─── Cartographer (Free Tier) ─────────────────────────────────────
     {
         name: 'list_projects',
-        description: 'Start here. Returns all synced codebases with their size, language, and project name. You need the project name for every other tool.',
+        description: 'Start here. Returns all synced codebases with their size, language, and project name. You need the project name for every other tool. If this returns empty, use sync_project to import the current repo.',
         inputSchema: { type: 'object', properties: {} },
         annotations: READ_ONLY_OPEN,
     },
+    {
+        name: 'sync_project',
+        description: 'Import a public GitHub repo into Seshat for structural analysis. Call this when list_projects returns empty or when the user wants to analyze a new repo. Detects the git remote automatically if no URL is provided. Extraction typically takes 5-30 seconds. After syncing, call list_projects to confirm the project is available.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                repo_url: { type: 'string', description: 'Public GitHub repo URL (e.g., https://github.com/org/repo). If omitted, tries to detect from the current git remote.' },
+            },
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
     {
         name: 'query_entities',
         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.',
@@ -327,10 +264,14 @@ const TOOLS = [
     },
     {
         name: 'get_auth_matrix',
-        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.',
+        description: 'Audit authentication coverage. Shows which API routes and controllers require auth and which don\'t, plus inconsistencies like database access without auth checks. For large codebases, use the module parameter to drill into a specific module/directory.',
         inputSchema: {
             type: 'object',
-            properties: { project: projectParam },
+            properties: {
+                project: projectParam,
+                module: { type: 'string', description: 'Filter to routes/controllers in a specific module or directory path (optional).' },
+                layer: { type: 'string', description: 'Filter to a specific layer: "route" or "controller" (optional).' },
+            },
         },
         annotations: READ_ONLY_OPEN,
     },
@@ -511,6 +452,11 @@ const TOOLS = [
         annotations: READ_ONLY_OPEN,
     },
 ];
+// ─── _meta Steering Hints ────────────────────────────────────────
+// After each tool call, suggest the next logical tool based on what
+// the agent has been doing. This replaces progressive revelation —
+// all tools are visible, but hints guide the agent toward the right
+// tool at the right time.
 // ─── Project Resolution (Fallback) ────────────────────────────────
 // Cache for the last project used — so tools auto-scope after list_projects
 let _lastKnownProject;
@@ -519,25 +465,10 @@ function resolveProjectName() {
     if (process.env.SESHAT_PROJECTS && !process.env.SESHAT_PROJECTS.includes(',') && !process.env.SESHAT_PROJECTS.includes('*')) {
         return path.basename(process.env.SESHAT_PROJECTS);
     }
-    // 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 { }
-    }
-    // If we've seen a project from list_projects, use that
+    // If we've seen a project from list_projects or sync_project, use that
     if (_lastKnownProject)
         return _lastKnownProject;
-    // Only fall back to CWD basename if there's a .seshat/ dir (i.e., it's actually a Seshat project)
-    // This prevents agents running from unrelated directories from sending bogus project names
-    if (fs.existsSync(path.join(process.cwd(), '.seshat'))) {
-        return path.basename(process.cwd());
-    }
-    // No project could be resolved — let the API return a helpful error
+    // No project could be resolved — caller should use list_projects or sync_project
     return undefined;
 }
 // ─── Cloud API helper ─────────────────────────────────────────────
@@ -551,46 +482,15 @@ function getCloudUrl(path) {
 async function main() {
     const server = new Server({
         name: 'seshat',
-        version: '0.14.0',
+        version: '0.16.0',
     }, {
-        capabilities: { tools: { listChanged: true } },
+        capabilities: { tools: {} },
         instructions: SERVER_INSTRUCTIONS,
     });
-    // Store server ref for sending notifications from revelation system
-    _serverRef = server;
-    // ─── Dynamic ListTools — only expose tools the user can access ──
+    // ─── ListTools — all public tools, Architect tools hidden (Ptah IP) ──
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        const apiKey = process.env.SESHAT_API_KEY;
-        let userTier = 'cartographer';
-        // Fetch account status to determine which tools to expose
-        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';
-                }
-            }
-            catch {
-                // If unavailable, default to cartographer (free tier tools only)
-            }
-        }
-        // Filter tools by BOTH tier access AND revelation stage
-        const visibleTools = TOOLS.filter((tool) => {
-            // Tier gate: user must have access
-            const requiredTier = TOOL_TIERS[tool.name];
-            if (requiredTier && !tierAtLeast(userTier, requiredTier))
-                return false;
-            // Revelation gate: tool must be revealed at current stage
-            const requiredStage = TOOL_REVELATION[tool.name];
-            if (requiredStage && !stageAtLeast(_currentStage, requiredStage))
-                return false;
-            return true;
-        });
-        process.stderr.write(`[Seshat] ListTools: stage=${_currentStage}, queries=${_sessionQueryCount}, tools=${visibleTools.length}/${TOOLS.length}\n`);
+        const visibleTools = TOOLS.filter((tool) => !PRIVATE_TOOLS.has(tool.name));
+        process.stderr.write(`[Seshat] ListTools: ${visibleTools.length} tools (${PRIVATE_TOOLS.size} private)\n`);
         return { tools: visibleTools };
     });
     // ─── CallTool handler ──────────────────────────────────────────
@@ -599,7 +499,14 @@ async function main() {
         const apiKey = process.env.SESHAT_API_KEY;
         if (!apiKey) {
             return {
-                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) }],
+                content: [{ type: 'text', text: JSON.stringify({ error: 'SESHAT_API_KEY environment variable is required. Get your free key at https://seshat.papyruslabs.ai' }, null, 2) }],
+                isError: true,
+            };
+        }
+        // Block private Ptah tools from being called
+        if (PRIVATE_TOOLS.has(name)) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }, null, 2) }],
                 isError: true,
             };
         }
@@ -618,37 +525,16 @@ async function main() {
                     };
                 }
                 const account = await res.json();
-                const userTier = account.tier || 'cartographer';
-                const credits = account.credits || 0;
-                // 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)) {
-                    if (tierAtLeast(userTier, requiredTier)) {
-                        availableTools.push(toolName);
-                    }
-                    else {
-                        if (!upgradeTeaser[TIER_LABELS[requiredTier]]) {
-                            upgradeTeaser[TIER_LABELS[requiredTier]] = [];
-                        }
-                        upgradeTeaser[TIER_LABELS[requiredTier]].push(toolName);
-                    }
-                }
+                // List all public tools
+                const publicTools = TOOLS
+                    .filter(t => !PRIVATE_TOOLS.has(t.name))
+                    .map(t => t.name);
                 const response = {
-                    tier: userTier,
-                    tier_label: TIER_LABELS[userTier],
-                    ptah_credits: credits,
-                    your_tools: availableTools,
-                    tool_count: `${availableTools.length} tools available`,
+                    status: 'active',
+                    tools_available: publicTools.length,
+                    your_tools: publicTools,
+                    dashboard: 'https://seshat.papyruslabs.ai/dashboard',
                 };
-                // 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(response, null, 2) }],
                 };
@@ -660,6 +546,133 @@ async function main() {
                 };
             }
         }
+        // ─── sync_project ──────────────────────────────────────────
+        if (name === 'sync_project') {
+            let repoUrl = args?.repo_url;
+            // If no URL provided, try to detect git remote
+            if (!repoUrl) {
+                try {
+                    const { execSync } = await import('child_process');
+                    const remote = execSync('git remote get-url origin', { timeout: 5000 }).toString().trim();
+                    // Normalize SSH URLs to HTTPS
+                    const sshMatch = remote.match(/^git@github\.com:(.+)\.git$/);
+                    repoUrl = sshMatch ? `https://github.com/${sshMatch[1]}` : remote.replace(/\.git$/, '');
+                }
+                catch {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({
+                                    error: 'No repo_url provided and could not detect git remote. Please provide the GitHub repo URL.',
+                                    hint: 'Example: sync_project({ repo_url: "https://github.com/org/repo" })',
+                                }, null, 2) }],
+                        isError: true,
+                    };
+                }
+            }
+            try {
+                const res = await fetch(getCloudUrl('/api/extract/create'), {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-api-key': apiKey,
+                    },
+                    body: JSON.stringify({ repo_url: repoUrl }),
+                });
+                if (!res.ok) {
+                    const errorText = await res.text();
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({ error: `Sync failed (${res.status}): ${errorText}` }, null, 2) }],
+                        isError: true,
+                    };
+                }
+                const result = await res.json();
+                // If private repo needs GitHub auth
+                if (result.status === 'github_auth_required') {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({
+                                    status: 'github_auth_required',
+                                    message: `This repository is private and requires GitHub authentication.\n\nTo connect your GitHub account, open this URL in your browser:\n\n${result.auth_url}\n\nAfter authorizing, try sync_project again.`,
+                                    auth_url: result.auth_url,
+                                }, null, 2) }],
+                        isError: true,
+                    };
+                }
+                // If already ready, return immediately
+                if (result.status === 'ready') {
+                    _lastKnownProject = result.repo_name;
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({
+                                    status: 'ready',
+                                    project: result.repo_name,
+                                    total_entities: result.total_entities,
+                                    language: result.language,
+                                    message: 'Project synced and ready. You can now use all Seshat tools with this project.',
+                                    cached: result.cached || false,
+                                }, null, 2) }],
+                    };
+                }
+                // If queued/extracting, poll until complete
+                if (result.status === 'queued' || result.status === 'extracting') {
+                    const pollUrl = getCloudUrl(`/api/extract/status/${result.repo_name}`);
+                    const maxAttempts = 60; // 5 minutes max
+                    for (let i = 0; i < maxAttempts; i++) {
+                        await new Promise(r => setTimeout(r, 5000));
+                        try {
+                            const pollRes = await fetch(pollUrl, { headers: { 'x-api-key': apiKey } });
+                            if (pollRes.ok) {
+                                const pollResult = await pollRes.json();
+                                if (pollResult.status === 'ready') {
+                                    _lastKnownProject = pollResult.repo_name;
+                                    return {
+                                        content: [{ type: 'text', text: JSON.stringify({
+                                                    status: 'ready',
+                                                    project: pollResult.repo_name,
+                                                    total_entities: pollResult.total_entities,
+                                                    language: pollResult.language,
+                                                    message: 'Project synced and ready. You can now use all Seshat tools with this project.',
+                                                }, null, 2) }],
+                                    };
+                                }
+                                if (pollResult.status === 'github_auth_required') {
+                                    return {
+                                        content: [{ type: 'text', text: JSON.stringify({
+                                                    status: 'github_auth_required',
+                                                    message: `This repository is private and requires GitHub authentication.\n\nTo connect your GitHub account, open this URL in your browser:\n\n${pollResult.auth_url || 'https://seshat.papyruslabs.ai/dashboard'}\n\nAfter authorizing, try sync_project again.`,
+                                                    auth_url: pollResult.auth_url,
+                                                }, null, 2) }],
+                                        isError: true,
+                                    };
+                                }
+                                if (pollResult.status === 'failed') {
+                                    return {
+                                        content: [{ type: 'text', text: JSON.stringify({
+                                                    error: `Extraction failed: ${pollResult.error || 'Unknown error'}`,
+                                                    hint: 'The repo may be too large, private, or contain unsupported file types.',
+                                                }, null, 2) }],
+                                        isError: true,
+                                    };
+                                }
+                            }
+                        }
+                        catch { /* continue polling */ }
+                    }
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({
+                                    status: 'timeout',
+                                    message: 'Extraction is taking longer than expected. Try calling list_projects in a minute to check if it completed.',
+                                }, null, 2) }],
+                    };
+                }
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ error: `Sync failed: ${err.message}` }, null, 2) }],
+                    isError: true,
+                };
+            }
+        }
         // Determine the project hash for this workspace
         // list_projects is unscoped — it returns ALL projects for the user
         const project_hash = name === 'list_projects'
@@ -672,7 +685,7 @@ async function main() {
             return {
                 content: [{ type: 'text', text: JSON.stringify({
                             error: 'No project specified. Call list_projects first to see available projects, then pass the project name as the "project" argument.',
-                            hint: 'If list_projects returns empty, the repo may not be synced yet. Use the Ptah demo API (POST /api/demo/create) to import a repo first.',
+                            hint: 'If list_projects returns empty, use sync_project to import the current repo first.',
                         }, null, 2) }],
                 isError: true,
             };
@@ -702,12 +715,10 @@ async function main() {
             if (name === 'list_projects' && result.projects && result.projects.length > 0) {
                 _lastKnownProject = result.projects[0].name;
             }
-            // Progressive revelation: count queries and check for stage transitions
-            _sessionQueryCount++;
-            checkRevelation();
             // 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) {
+            // Server-side _meta now includes cross-tool recommendations.
+            if (result._meta && Object.keys(result._meta).length > 0) {
                 const meta = result._meta;
                 delete result._meta;
                 return {
@@ -717,6 +728,9 @@ async function main() {
                     ],
                 };
             }
+            // Strip empty _meta
+            if (result._meta)
+                delete result._meta;
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             };
@@ -730,7 +744,7 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`Seshat MCP v0.13.1 connected. Structural code analysis ready.\n`);
+    process.stderr.write(`Seshat MCP v0.16.0 connected. Structural intelligence ready.\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

package/dist/tools/functors.d.ts

@@ -25,6 +25,8 @@ export declare function getCouplingMetrics(args: {
 }, loader: ProjectLoader): unknown;
 export declare function getAuthMatrix(args: {
     project?: string;
+    module?: string;
+    layer?: string;
 }, loader: ProjectLoader): unknown;
 export declare function findErrorGaps(args: {
     project?: string;

package/dist/tools/functors.js

@@ -296,11 +296,24 @@ export function getAuthMatrix(args, loader) {
     if (projErr)
         return { error: projErr };
     const entities = loader.getEntities(args?.project);
-    const apiEntities = entities.filter((e) => {
+    let apiEntities = entities.filter((e) => {
         const layer = entityLayer(e);
         return layer === 'route' || layer === 'controller' ||
             e.context?.exposure === 'api';
     });
+    // Optional module filter — drill into a specific module/directory
+    if (args?.module) {
+        const mod = args.module.toLowerCase();
+        apiEntities = apiEntities.filter((e) => {
+            const eModule = (e.context?.module || e._sourceFile || '').toLowerCase();
+            return eModule.includes(mod);
+        });
+    }
+    // Optional layer filter
+    if (args?.layer) {
+        const targetLayer = args.layer.toLowerCase();
+        apiEntities = apiEntities.filter((e) => entityLayer(e) === targetLayer);
+    }
     const withAuth = [];
     const withoutAuth = [];
     const inconsistencies = [];

package/package.json

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