ai.papyruslabs/seshat-mcp

Find every function with a specific syntactic constraint tag — AUTH (requires authentication), DB_ACCESS (touches database), THROWS (explicit throw statement), PURE (no side effects), NETWORK_IO (makes HTTP calls), VALIDATED (has input validation). Also supports table-level queries: pass table="walks" to find every function that reads or writes the walks table (answers "what touches this table?" for schema migrations). Constraints are extracted from source syntax, not inferred. For semantic/behavioral properties (e.g., "can fail transitively"), use query_traits instead.

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.

List the ways into the system: route/controller handlers, test entries, framework plugin registrations, and exported symbols (the public API surface), classified by kind and ranked by reach. Call it first when orienting in an unfamiliar codebase — it answers "where does execution start, and what is the public surface?" Complements list_modules (structure) and find_dead_code (its exact inverse: these are the reachability roots).

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.

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.

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.

Find memory and lifecycle issues — entities with complex ownership, unsafe blocks, escaping references, or illegal mutability on borrowed data. Returns 0 for most JS/Python codebases — a non-zero result in those languages indicates a serious boundary violation worth investigating. Most detailed results for Rust and C++.

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.

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.

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. Most useful for backend codebases with middleware-based auth. Frontend frameworks (React, Vue) handle auth via component wrappers, which this tool won't detect as AUTH constraints.

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.

The codebase's hidden modules: groups of symbols that historically change together (≥3 shared commits, sweep commits excluded), computed from real commit history. Clusters that span multiple directories reveal coupling the file tree doesn't show. Call it when planning a change or splitting work across agents — touching one member of a cluster usually means touching the rest, even when no static dependency connects them. Correlation evidence, honestly framed; complements get_blast_radius (static reach) with empirical reach.

Measure how tangled your code is. Returns coupling (cross-boundary dependencies), cohesion (within-group dependencies), and instability scores. High coupling + low cohesion = refactoring candidates. Start with group_by: "layer" for the architectural health view ("are my controllers more coupled than my services?"), then drill into group_by: "module" for specific hotspots.

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.

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.

Get everything about one function or class — its signature, callers, callees, data flow, constraints, source location, and database operations (which tables it reads/writes). 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.

Project-level change-history orientation: the most-changed entities (and what kind of change dominates each), low-survival thrash spots where changes don't stick, heavily-depended-on entities that haven't changed all window (interface freeze), and directories with no recent changes. Call it after list_modules when orienting in a codebase — it answers "where does development actually happen, and where does it fail?" from commit history rather than current structure. Complements get_lineage (one entity's story) with the project-wide map.

The change history of one symbol, typed by what kind of change each commit made (body, calls, data, signature, constraints…), with CI verdicts, reverts, rename tracking, co-change partners, and rejected PRs that touched it. Call before modifying anything load-bearing: it answers "how does this entity usually change, and what happened last time someone tried?" — which no text diff can. Complements get_blast_radius (current impact) with history (past behavior).

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.

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.

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.

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.

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.

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.

Find functions by inferred behavioral trait — "fallible" (can fail, including transitively via callees that throw), "asyncContext" (carries async state), "generator" (yields values). Traits are semantic properties inferred from the call graph, not just syntax. Use this when you need to find all code with a specific capability. For syntactic tags (explicit throw statements, DB access), use find_by_constraint instead.

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. Use force: true to re-extract even if a cached snapshot exists (useful after code changes or when Seshat extraction has been updated).

Follow data from one function through the call graph to its sinks. From a start entity it walks callees, records the data each hop consumes/produces/mutates, and reports the chain from the start to every sink the data reaches — database writes, network egress, filesystem writes — plus the tables touched. Call it before changing a function that handles real data: it answers "where does this data end up?", the cross-call composition get_data_flow (one entity) cannot give. Flags untrusted inputs at the source.