@papyruslabsai/seshat-mcp 0.15.0 → 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,21 +14,48 @@ 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.
 
@@ -67,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.',
@@ -227,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,
     },
@@ -424,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 ─────────────────────────────────────────────
@@ -456,7 +482,7 @@ function getCloudUrl(path) {
 async function main() {
     const server = new Server({
         name: 'seshat',
-        version: '0.14.2',
+        version: '0.16.0',
     }, {
         capabilities: { tools: {} },
         instructions: SERVER_INSTRUCTIONS,
@@ -473,7 +499,7 @@ 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,
             };
         }
@@ -507,7 +533,7 @@ async function main() {
                     status: 'active',
                     tools_available: publicTools.length,
                     your_tools: publicTools,
-                    dashboard: 'https://ptah.papyruslabs.ai/dashboard',
+                    dashboard: 'https://seshat.papyruslabs.ai/dashboard',
                 };
                 return {
                     content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
@@ -520,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'
@@ -532,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,
             };
@@ -591,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.15.0",
+  "version": "0.16.0",
   "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
   "type": "module",
   "bin": {