@papyruslabsai/seshat-mcp 0.20.0 → 0.20.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Papyrus Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# Seshat — structural code intelligence for AI agents
+
+**Your agent reconstructs your codebase from likelihood. Seshat compiles it.**
+
+Seshat turns a repository into a typed symbol graph (every function, class, route, and
+table, with its *real* dependency edges, data flow, and constraints) and serves it to your
+agent over MCP. So before your agent edits a function, it can ask what will actually break
+instead of guessing.
+
+Backed by a compiled intermediate representation, not text search or embeddings: if Seshat
+says a function has three callers, it has exactly three.
+
+## Why
+
+AI coding agents are fast but structurally blind. When an agent changes one function, it
+often cannot see everything that depends on it, so it silently breaks callers it never
+looked at. A large share of AI-introduced regressions come from exactly this. Seshat gives
+the agent the map.
+
+## Try it first (no install, no login)
+
+Paste any public repo at **https://seshat.papyruslabs.ai/try** and watch it trace what a
+change would break.
+
+## Install
+
+```
+npx -y @papyruslabsai/seshat-mcp setup <your-key>
+```
+
+Get a free key at **https://seshat.papyruslabs.ai** (first extraction is free). The setup
+command writes your MCP config and stores the key.
+
+Or configure manually (Claude Code, Cursor, or any MCP client):
+
+```json
+{
+  "mcpServers": {
+    "seshat": {
+      "command": "npx",
+      "args": ["-y", "@papyruslabsai/seshat-mcp"],
+      "env": { "SESHAT_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+## Tools
+
+Point your agent at a repo with `sync_project`, then it investigates the way a senior
+engineer does: orient, trace, verify.
+
+**Orient**
+- `list_projects` — what is synced
+- `list_modules` — how the codebase is organized, by layer or module
+- `query_entities` — find functions, classes, and routes by name, layer, or module
+- `find_entry_points` — routes, exports, and the public API surface
+
+**Investigate a symbol**
+- `get_entity` — signature, callers, callees, data flow, side effects, and tables touched
+- `get_dependencies` — the real call chain, callers and callees
+- `get_blast_radius` — everything that breaks if you change it, transitively
+- `get_data_flow` — what a function reads, returns, and mutates
+- `get_optimal_context` — the minimal, ranked set of files to read before editing
+- `find_by_constraint` — every function that touches a given table (or carries a given trait)
+- `find_dead_code` — unreachable symbols, safe to delete
+
+Every answer comes from the compiled graph and discloses the coverage behind it.
+
+> History and cross-cutting audit tools (hotspots, co-change clusters, lineage, topology,
+> semantic clones) are being hardened and will be added to this list as they land.
+
+## Privacy
+
+Analysis runs in the Papyrus Labs cloud, by design: the compiled graph is the product's
+moat, and keeping extraction server-side is how that stays protected. Public repos are
+cloned from GitHub; private repos require you to connect your GitHub account. Source is
+processed to build the graph and cached to serve queries. See the privacy policy at
+seshat.papyruslabs.ai.
+
+## Pricing
+
+First extraction is free. $0.03 per query after a free tier; a typical investigation is 5
+to 15 queries. Details at https://seshat.papyruslabs.ai.
+
+MIT licensed server. Named for the goddess who kept the records, built so your agent can
+read them.

package/package.json

@@ -1,48 +1,41 @@
-{
-  "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.20.0",
-  "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
-  "type": "module",
-  "bin": {
-    "seshat-mcp": "./dist/index.js"
-  },
-  "main": "./dist/index.js",
-  "exports": {
-    ".": "./dist/index.js",
-    "./tools": "./dist/tools/index.js",
-    "./functors": "./dist/tools/functors.js",
-    "./diff": "./dist/tools/diff.js",
-    "./types": "./dist/types.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1"
-  },
-  "devDependencies": {
-    "typescript": "^5.5.0",
-    "@types/node": "^20.0.0"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "files": [
-    "dist/"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/papyruslabs-ai/seshat.git",
-    "directory": "packages/seshat-mcp"
-  },
-  "keywords": [
-    "mcp",
-    "semantic",
-    "code-analysis",
-    "seshat",
-    "static-analysis"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "@papyruslabsai/seshat-mcp",
+  "version": "0.20.1",
+  "mcpName": "ai.papyruslabs/seshat-mcp",
+  "description": "Structural code intelligence for AI agents: a compiled typed symbol graph over MCP.",
+  "type": "module",
+  "bin": {
+    "seshat-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/papyruslabs-ai/seshat-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "code-intelligence",
+    "structural-analysis",
+    "blast-radius",
+    "ai-agents",
+    "seshat"
+  ],
+  "license": "MIT"
+}

package/dist/bootstrap.d.ts

@@ -1,29 +0,0 @@
-/**
- * Auto-Bootstrap — extract a .seshat/ bundle on first run.
- *
- * When the MCP server starts and finds no .seshat/_bundle.json, this module
- * spawns `npx @papyruslabsai/seshat-extract` to generate one on the fly.
- *
- * CI continues to regenerate the bundle on every merge to main, overwriting
- * the bootstrap result. The bootstrap only runs when .seshat/ doesn't exist.
- *
- * Env vars:
- *   SESHAT_BOOTSTRAP_TIMEOUT — spawn timeout in ms (default: 120000)
- */
-export interface BootstrapResult {
-    success: boolean;
-    entityCount: number;
-    languages: string[];
-    durationMs: number;
-    error?: string;
-}
-/**
- * Auto-bootstrap: extract a .seshat/ bundle for the given project directory.
- *
- * Spawns `npx @papyruslabsai/seshat-extract <dir> <dir>/.seshat <name>`
- * and waits for it to complete.
- *
- * @param projectDir - Absolute path to the project root
- * @returns Bootstrap result with entity count, languages, duration, and any error
- */
-export declare function bootstrap(projectDir: string): Promise<BootstrapResult>;

package/dist/bootstrap.js

@@ -1,190 +0,0 @@
-/**
- * Auto-Bootstrap — extract a .seshat/ bundle on first run.
- *
- * When the MCP server starts and finds no .seshat/_bundle.json, this module
- * spawns `npx @papyruslabsai/seshat-extract` to generate one on the fly.
- *
- * CI continues to regenerate the bundle on every merge to main, overwriting
- * the bootstrap result. The bootstrap only runs when .seshat/ doesn't exist.
- *
- * Env vars:
- *   SESHAT_BOOTSTRAP_TIMEOUT — spawn timeout in ms (default: 120000)
- */
-import { spawn } from 'child_process';
-import fs from 'fs';
-import path from 'path';
-import { execSync } from 'child_process';
-// Project marker files — presence of any means "this is a code project"
-const PROJECT_MARKERS = [
-    '.git',
-    'package.json',
-    'go.mod',
-    'Cargo.toml',
-    'pyproject.toml',
-    'pom.xml',
-    'build.gradle',
-    'Makefile',
-    'CMakeLists.txt',
-];
-/**
- * Check if a directory looks like a code project.
- */
-function isCodeProject(dir) {
-    for (const marker of PROJECT_MARKERS) {
-        const markerPath = path.join(dir, marker);
-        if (fs.existsSync(markerPath))
-            return true;
-    }
-    // Also check for *.sln files (C# solutions)
-    try {
-        const entries = fs.readdirSync(dir);
-        if (entries.some(e => e.endsWith('.sln')))
-            return true;
-    }
-    catch { }
-    return false;
-}
-/**
- * Infer a project name from the directory.
- * Priority: package.json name → git remote → directory basename
- */
-function inferProjectName(dir) {
-    // 1. Try package.json
-    try {
-        const pkgPath = path.join(dir, 'package.json');
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        if (pkg.name) {
-            return pkg.name.replace(/^@[^/]+\//, '');
-        }
-    }
-    catch { }
-    // 2. Try git remote
-    try {
-        const remote = execSync('git remote get-url origin', {
-            cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
-        }).trim();
-        const match = remote.match(/\/([^/]+?)(?:\.git)?$/);
-        if (match)
-            return match[1];
-    }
-    catch { }
-    // 3. Fallback: directory basename
-    return path.basename(dir);
-}
-/**
- * Auto-bootstrap: extract a .seshat/ bundle for the given project directory.
- *
- * Spawns `npx @papyruslabsai/seshat-extract <dir> <dir>/.seshat <name>`
- * and waits for it to complete.
- *
- * @param projectDir - Absolute path to the project root
- * @returns Bootstrap result with entity count, languages, duration, and any error
- */
-export async function bootstrap(projectDir) {
-    const startTime = Date.now();
-    const timeoutMs = parseInt(process.env.SESHAT_BOOTSTRAP_TIMEOUT || '120000', 10);
-    // Sanity checks
-    if (!isCodeProject(projectDir)) {
-        return {
-            success: false,
-            entityCount: 0,
-            languages: [],
-            durationMs: Date.now() - startTime,
-            error: `${projectDir} does not appear to be a code project (no package.json, .git, go.mod, etc.)`,
-        };
-    }
-    const seshatDir = path.join(projectDir, '.seshat');
-    const projectName = inferProjectName(projectDir);
-    process.stderr.write(`[seshat-mcp] Auto-bootstrap: extracting ${projectName} from ${projectDir}\n`);
-    return new Promise((resolve) => {
-        // On Windows, npx is npx.cmd and must run through shell.
-        // shell: true concatenates args into a command string, so paths with
-        // spaces must be double-quoted to survive CMD parsing.
-        const isWindows = process.platform === 'win32';
-        const npxCmd = isWindows ? 'npx.cmd' : 'npx';
-        const q = (s) => isWindows && s.includes(' ') ? `"${s}"` : s;
-        const child = spawn(npxCmd, ['-y', '@papyruslabsai/seshat-extract', q(projectDir), q(seshatDir), projectName], {
-            cwd: projectDir,
-            shell: isWindows, // Windows needs shell: true for .cmd files
-            stdio: ['pipe', 'pipe', 'pipe'],
-            timeout: timeoutMs,
-        });
-        let stdout = '';
-        let stderr = '';
-        child.stdout?.on('data', (data) => {
-            stdout += data.toString();
-        });
-        child.stderr?.on('data', (data) => {
-            const text = data.toString();
-            stderr += text;
-            // Forward progress to parent stderr
-            process.stderr.write(`[seshat-extract] ${text}`);
-        });
-        child.on('error', (err) => {
-            resolve({
-                success: false,
-                entityCount: 0,
-                languages: [],
-                durationMs: Date.now() - startTime,
-                error: `Failed to spawn seshat-extract: ${err.message}`,
-            });
-        });
-        child.on('close', (code) => {
-            const durationMs = Date.now() - startTime;
-            if (code !== 0) {
-                resolve({
-                    success: false,
-                    entityCount: 0,
-                    languages: [],
-                    durationMs,
-                    error: `seshat-extract exited with code ${code}. stderr: ${stderr.slice(-500)}`,
-                });
-                return;
-            }
-            // Parse the JSON result from stdout
-            try {
-                const result = JSON.parse(stdout.trim());
-                if (result.ok) {
-                    process.stderr.write(`[seshat-mcp] Bootstrap complete: ${result.entities} entities, ${result.languages?.join(', ')} in ${(durationMs / 1000).toFixed(1)}s\n`);
-                    resolve({
-                        success: true,
-                        entityCount: result.entities || 0,
-                        languages: result.languages || [],
-                        durationMs,
-                    });
-                }
-                else {
-                    resolve({
-                        success: false,
-                        entityCount: 0,
-                        languages: [],
-                        durationMs,
-                        error: result.error || 'Unknown extraction error',
-                    });
-                }
-            }
-            catch {
-                // JSON parse failed — check if bundle was written anyway
-                const bundlePath = path.join(seshatDir, '_bundle.json');
-                if (fs.existsSync(bundlePath)) {
-                    process.stderr.write(`[seshat-mcp] Bootstrap produced bundle but JSON result was malformed. Proceeding.\n`);
-                    resolve({
-                        success: true,
-                        entityCount: 0,
-                        languages: [],
-                        durationMs,
-                    });
-                }
-                else {
-                    resolve({
-                        success: false,
-                        entityCount: 0,
-                        languages: [],
-                        durationMs,
-                        error: `seshat-extract succeeded but produced no parseable result. stdout: ${stdout.slice(-200)}`,
-                    });
-                }
-            }
-        });
-    });
-}

package/dist/graph.d.ts

@@ -1,42 +0,0 @@
-/**
- * Call Graph Construction & Blast Radius Computation
- *
- * Computes the set of entities affected by a change:
- *   affected(e) = ancestors(e) ∪ descendants(e) ∪ {e}
- *
- * Ancestors = all transitive callers (upstream).
- * Descendants = all transitive callees (downstream).
- */
-import type { JstfEntity } from './types.js';
-export interface CallGraph {
-    callers: Map<string, Set<string>>;
-    callees: Map<string, Set<string>>;
-    entityById: Map<string, JstfEntity>;
-    /** Reference-resolution outcomes — honest sparsity as a reported number. */
-    resolutionStats?: {
-        resolved: number;
-        ambiguous: number;
-        unknown: number;
-    };
-}
-export interface BlastRadiusResult {
-    affected: string[];
-    depthMap: Record<string, number>;
-    ancestors: string[];
-    descendants: string[];
-}
-/**
- * Build a bidirectional call graph from entities' dependency data.
- *
- * Reference resolution is identity-honest: a bare-name target resolves to the
- * unique entity with that local name, or the unique same-file match when the
- * name is ambiguous repo-wide. A reference that stays ambiguous produces NO
- * edge — first-wins matching used to silently attribute edges to whichever
- * same-named entity was indexed first.
- */
-export declare function buildCallGraph(entities: JstfEntity[]): CallGraph;
-/**
- * Compute blast radius: all entities affected by changes to the given IDs.
- * Traverses both callers (upstream) and callees (downstream).
- */
-export declare function computeBlastRadius(graph: CallGraph, changedIds: Set<string>, maxDepth?: number): BlastRadiusResult;