seer-mcp 0.1.0

package/docs/examples/pre-edit-context.md

@@ -0,0 +1,81 @@
+# Pre-edit context
+
+The single most useful thing Seer does: tell an agent what a change will touch
+*before* it makes it.
+
+## The problem
+
+An agent asked to "add idempotency to `chargeCard`" usually starts by grepping
+for `chargeCard`, opening the file, grepping for callers, opening those, hunting
+for tests, and maybe checking git blame. That is six to ten tool calls and a lot
+of tokens, and it still misses the transitive dependents and the risk.
+
+## One call instead
+
+```
+seer_preflight { "symbol": "chargeCard" }
+```
+
+Trimmed response:
+
+```json
+{
+  "symbol": {
+    "name": "chargeCard",
+    "qualifiedName": "billing.PaymentService.chargeCard",
+    "file": "src/billing/payment.ts",
+    "lineStart": 142,
+    "kind": "method"
+  },
+  "callers": [
+    { "name": "checkout", "file": "src/api/checkout.ts", "line": 88 },
+    { "name": "retryFailedPayment", "file": "src/jobs/retry.ts", "line": 31 }
+  ],
+  "callerCount": 2,
+  "transitiveDependents": 9,
+  "routeExposure": [
+    { "method": "POST", "path": "/api/checkout", "framework": "express" }
+  ],
+  "tests": [
+    { "name": "charges a valid card", "file": "test/payment.spec.ts", "directness": "direct" }
+  ],
+  "history": [
+    { "sha": "a1b2c3d", "date": "2026-04-18", "summary": "handle declined cards" }
+  ],
+  "risk": {
+    "verdict": "high",
+    "reasons": ["sits on public route POST /api/checkout", "9 transitive dependents", "cyclomatic 14"]
+  }
+}
+```
+
+## Why this matters
+
+The agent now knows, in one shot, that `chargeCard`:
+
+- is reached from a public checkout endpoint, so a regression is user-facing,
+- has 9 downstream dependents, so the blast radius is wide,
+- has exactly one direct test, so coverage is thin,
+- was last touched to handle declined cards, so that path is load-bearing.
+
+That is enough to write the change carefully and add the right test, without a
+scavenger hunt.
+
+## Diff mode
+
+If you want the blast radius of work already in progress:
+
+```
+seer_preflight { "fromRef": "main", "toRef": "HEAD" }
+```
+
+Seer maps the changed line ranges to the affected symbols and returns the same
+kind of packet for each. See [Change history](change-history.md).
+
+## From the CLI
+
+```bash
+seer preflight --symbol chargeCard
+seer preflight --symbol chargeCard --file src/billing/payment.ts   # disambiguate
+seer preflight --from main --to HEAD --json
+```

package/docs/examples/service-links.md

@@ -0,0 +1,88 @@
+# Service links
+
+In a microservice repo (or a set of repos), the interesting bugs live in the
+gaps between services. Seer resolves an outbound network call in one service to
+the concrete route handler that serves it in another, so an agent can follow a
+request across a boundary.
+
+## What gets connected
+
+Seer scans for client call signatures (fetch, axios, requests, httpx,
+HttpClient, RestTemplate, gRPC, tRPC, GraphQL, and message-queue producers) and
+records them in `service_calls`. After indexing, a resolver normalizes those URLs
+and patterns and matches them against the `routes` it extracted from server
+frameworks, producing `service_links`.
+
+## The call
+
+```
+seer_service_links { "pathSubstr": "/invoices" }
+```
+
+Trimmed response:
+
+```json
+{
+  "links": [
+    {
+      "protocol": "http",
+      "method": "GET",
+      "path": "/api/invoices/:id",
+      "matchKind": "param",
+      "client": {
+        "symbol": "shop.getInvoice",
+        "file": "services/shop/src/billing.ts",
+        "line": 40
+      },
+      "handler": {
+        "symbol": "billing.getInvoice",
+        "file": "services/billing/src/routes.ts",
+        "line": 77
+      },
+      "confidence": 0.95
+    }
+  ]
+}
+```
+
+The `shop` service calls `GET /api/invoices/<id>`; Seer resolves that to the
+`billing` service's `/api/invoices/:id` handler, even though the client wrote the
+URL with a template literal.
+
+## Tracing a chain
+
+To follow a request across several hops:
+
+```
+seer_trace_service_path { "from": "shop.getInvoice", "to": "billing.getInvoice" }
+```
+
+or fan out from one entry point:
+
+```
+seer_trace_service_dependencies { "from": "shop.checkout", "maxDepth": 3 }
+```
+
+## Crossing repos with external bundles
+
+If the services live in separate repos, export a bundle from one and import it
+additively into the other as a read-only layer:
+
+```bash
+# in the billing repo
+seer bundle export --out billing.seerbundle
+
+# in the shop repo
+seer bundle import billing.seerbundle --external --alias billing
+```
+
+Now `shop`'s outbound calls resolve against `billing`'s real routes without
+copying any source in. See [bundles in the CLI reference](../cli.md).
+
+## From the CLI
+
+```bash
+seer service-calls --protocol http --path /invoices
+seer service-links --match-kind exact
+seer trace-service shop.getInvoice billing.getInvoice
+```

package/docs/examples.md

@@ -0,0 +1,80 @@
+# Examples
+
+Real workflows, the way an agent (or you, from the CLI) would actually use Seer.
+Each one links to a fuller walkthrough.
+
+The outputs below are illustrative and trimmed for readability. Shapes are real;
+exact numbers depend on your repo.
+
+---
+
+## Before editing unfamiliar code
+
+You are about to change `chargeCard`. Instead of five searches, one call:
+
+```
+seer_preflight { "symbol": "chargeCard" }
+```
+
+You get the definition, who calls it, the tests that cover it, recent commits,
+and a risk verdict in a single packet. Full walkthrough:
+[Pre-edit context](examples/pre-edit-context.md).
+
+---
+
+## Find the tests that actually exercise a symbol
+
+```
+seer_behavior { "symbol": "chargeCard" }
+```
+
+Ranked by how directly each test hits the symbol, not just filename matching.
+Full walkthrough: [Behavior and tests](examples/behavior-tests.md).
+
+---
+
+## Follow routes across service boundaries
+
+```
+seer_service_links { "pathSubstr": "/invoices" }
+```
+
+See which client call in one service resolves to which route handler in another.
+Full walkthrough: [Service links](examples/service-links.md).
+
+---
+
+## Understand recent changes
+
+```
+seer_preflight { "fromRef": "main", "toRef": "HEAD" }
+```
+
+Maps the diff to the affected symbols and their blast radius, then layers on the
+history for each. Full walkthrough: [Change history](examples/change-history.md).
+
+---
+
+## Read a giant file cheaply
+
+```
+seer_skeleton { "file": "src/server.ts" }
+```
+
+Returns every signature with bodies collapsed to `{ ... 40 lines ... }`. Add
+`focusSymbol` to expand exactly one body. A 2,000-line file becomes an outline
+you can scan for a few hundred tokens.
+
+---
+
+## Batch several lookups into one round-trip
+
+```
+seer_batch { "calls": [
+  { "tool": "seer_definition", "args": { "name": "chargeCard" } },
+  { "tool": "seer_callers",    "args": { "symbol": "chargeCard" } },
+  { "tool": "seer_behavior",   "args": { "symbol": "chargeCard" } }
+] }
+```
+
+One request, three results, failure-isolated.

package/docs/faq.md

@@ -0,0 +1,70 @@
+# FAQ and positioning
+
+## Is Seer just another codebase-graph MCP?
+
+There is overlap, but the focus is different. Most graph tools help an agent
+*explore* structure. Seer is built around the moment *before an edit*: it folds
+callers, tests, risk, boundaries, and per-symbol history into one packet so the
+agent understands the impact of a change, not just the shape of the code. The
+headline differentiator is symbol-level git history, not file-level churn.
+
+## How is Seer different from codebase-memory?
+
+Codebase-memory and similar graph-first tools are great at structural
+exploration. Seer leans into edit-awareness: tests that cover a symbol, the risk
+of touching it, what a diff will break, and how a function changed over time.
+Think of structural exploration as the floor, and edit-impact context as the
+thing Seer adds on top.
+
+## How is Seer different from Serena?
+
+Serena-style tools focus on editing and refactoring symbols directly. Seer does
+not edit your code. It tells the agent doing the editing what the change is going
+to affect, so the edit is safer. They are complementary.
+
+## Does Seer replace Claude, Cursor, or Codex?
+
+No. Seer is an MCP server those tools call. It gives the agent better context;
+the agent still does the reasoning and the editing. Seer works with all of them
+at once (see [MCP Setup](mcp.md)).
+
+## How is Seer different from grep?
+
+Grep matches text. Seer understands structure. "Who calls this method", "which
+tests cover it", "what does this diff break", and "how did this function change"
+are not text queries. They also cost far fewer tokens than the multi-search,
+multi-file-read dance an agent does with grep alone. Use grep for comments,
+string literals, and config values; use Seer for everything structural.
+
+## Does anything leave my machine?
+
+No. Seer-Core is local and deterministic. No API keys, no network calls, no
+telemetry. The index is a single SQLite file under `.seer/`.
+
+## Does it use an LLM?
+
+Seer-Core does not. It returns deterministic structural facts. The accuracy and
+token-efficiency benchmarks use LLMs only to *measure* how much Seer helps an
+agent, not inside Seer itself. (A separate Seer-Onboarding layer is the
+LLM-enabled, human-facing product; this repo is Core.)
+
+## Which languages are supported?
+
+Python, JavaScript, TypeScript/TSX, Go, Java, Rust, C, C++, and C#. See
+[Language Support](languages.md) for the capability matrix.
+
+## How big a repo can it handle?
+
+It has been run on the Linux kernel and Unreal Engine (millions of symbols, tens
+of millions of edges). See [Benchmarks](benchmarks.md) for measured numbers.
+
+## Do I have to commit the `.seer/` folder?
+
+No. It rebuilds on demand. Add `.seer/` to `.gitignore` if you prefer. For
+sharing a prebuilt index (for example in CI), use `seer bundle export`.
+
+## How do I keep results fresh?
+
+You do not have to do anything. A background watcher keeps the index warm, and a
+hash-based freshness check re-parses anything that changed before a query
+returns. If you ever suspect drift, `seer index . --reset` rebuilds clean.

package/docs/internals.md

@@ -0,0 +1,104 @@
+# Implementation Notes
+
+This is the engineering companion to [Architecture](architecture.md). It covers
+the decisions that are easy to get wrong and that Seer cares about: the stack,
+caching, edge resolution, worker pooling, and the database schema.
+
+---
+
+## Stack
+
+| Piece | Choice | Why |
+|---|---|---|
+| Runtime | Node.js 18+ (26+ recommended) | Standard worker threads, fast local startup. |
+| Language | TypeScript, CommonJS output | Type safety for graph code; CommonJS maps cleanly to Node tooling. |
+| Database | built-in `node:sqlite` | Zero native npm dependencies; no compiler traps. |
+| Parser | `web-tree-sitter` (WASM) | Tree-sitter parsing in V8 with no native C++ build. |
+| Grammars | `tree-sitter-wasms` | Pre-compiled grammars, loaded lazily per language. |
+
+The "zero native dependency" rule is deliberate. The whole thing installs and
+runs without a compiler toolchain, which is what makes the `npx` install path
+realistic across machines.
+
+---
+
+## Database schema (v10)
+
+One file, `<repo>/.seer/graph.db`, with `CURRENT_SCHEMA_VERSION = 10`.
+Migrations are idempotent and run automatically when the database is opened for
+writing, using `ALTER TABLE ADD COLUMN` and `CREATE TABLE IF NOT EXISTS` checks,
+so an old index upgrades in place.
+
+```mermaid
+erDiagram
+    FILES ||--o{ SYMBOLS : defines
+    FILES ||--o{ FILE_IMPORTS : "declares imports"
+    SYMBOLS ||--o{ EDGES : "from_id / to_id"
+    MODULES ||--o{ MODULE_MEMBERS : clusters
+    BOUNDARIES ||--o{ BOUNDARY_MEMBERS : groups
+    EXTERNAL_BUNDLES ||--o{ ROUTES : embeds
+```
+
+Symbols carry a `symbol_role` (`definition`, `declaration`, or `type_ref`) and an
+`is_rankable` flag. Forward declarations and type references are stored but kept
+out of PageRank and hidden from default search, which is what keeps a 3-million-
+node C codebase from drowning in noise.
+
+---
+
+## Incremental caching and lazy PageRank
+
+- **Content hashing.** Every file's SHA-256 is recorded. An unchanged file is
+  skipped entirely on re-index. When a file does change, foreign keys cascade
+  the old rows out cleanly before the new ones go in.
+- **Lazy PageRank.** PageRank runs only over rankable symbols, and only when the
+  graph actually changed. No new files, edges, or deletions means the previous
+  vector is reused. On a large repo this turns a multi-second pass into a no-op.
+
+---
+
+## Scope-aware edge resolution
+
+Linking a call (`to_name`) to a concrete definition (`to_id`) is a three-pass
+post-index step. Each pass only fills links still NULL, so the narrowest scope
+wins:
+
+1. **Same-file.** The callee is defined in the caller's own file.
+2. **Imported-file.** Follow the caller's resolved imports and match there.
+3. **Global fallback.** Bind to a global definition of that name, used only when
+   scope cannot decide.
+
+---
+
+## Parser worker pooling
+
+`web-tree-sitter` shares a single V8 isolate, which blocks normal Promise
+concurrency. So parsing runs in a pool of native worker threads, each with its
+own WASM heap and parser context. The main thread keeps all SQLite writes serial
+and in input order, which keeps `AUTOINCREMENT` IDs deterministic across runs.
+JIT freshness syncs stay serial on purpose, because spinning up workers for a
+two-file edit is slower than just doing it.
+
+A query-assisted walker compiles each extractor's declared candidate node types
+into a Tree-sitter query once, then only runs extractor callbacks on captured
+nodes. Set `SEER_USE_CANDIDATE_QUERY=0` to force the plain walker.
+
+---
+
+## Monorepo boundaries
+
+Boundaries come from package manifests (`package.json`, `go.mod`, `Cargo.toml`)
+or fallback paths like `packages/*` and `services/*`. When a call edge starts in
+boundary A and resolves into boundary B, that crossing is recorded and surfaced
+in the `boundaryCrossings` part of a risk profile.
+
+---
+
+## Rename and move continuity
+
+For per-symbol history that survives refactoring, Seer compares a 64-bit SimHash
+over identifier-folded AST subtrees, plus Hamming distance and scope similarity.
+Common shapes (think standard getters) with several matches are capped at low
+confidence and require a name or scope match, so it does not invent links. This
+is snapshot evidence; true cross-commit lineage is delivered by `seer history`
+(git follow plus line overlap).

package/docs/languages.md

@@ -0,0 +1,70 @@
+# Language Support
+
+Seer parses with Tree-sitter, so adding depth to a language is mostly about
+writing a good extractor, not wrestling a parser. Nine languages ship today.
+
+## Supported languages
+
+| Language | Symbols + calls | Imports | Routes | Service calls | Config reads |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Python | yes | yes | FastAPI, Flask | requests, httpx | `os.getenv` |
+| JavaScript | yes | yes | Express, Fastify | fetch, axios | `process.env` |
+| TypeScript / TSX | yes | yes | Express, Fastify, tRPC, GraphQL | fetch, axios | `process.env` |
+| Go | yes | yes | (via gRPC `.proto`) | gRPC, net/http clients | `os.Getenv` |
+| Java | yes | yes | Spring Boot | gRPC, RestTemplate, HttpClient | `System.getenv` |
+| Rust | yes | yes | no | reqwest-style clients | env reads |
+| C | yes | yes | no | no | no |
+| C++ | yes | yes | no | no | no |
+| C# | yes | yes | no | gRPC, HttpClient | env reads |
+
+"Routes" means server-side endpoint extraction. gRPC routes come from `.proto`
+files regardless of the implementing language. A language without HTTP route
+extraction can still be a *client* in a service link; it just cannot be the HTTP
+*target*. See [Known Limits](limits.md) for the precise boundary.
+
+Every language gets the structural core: definitions with qualified names, call
+edges, imports, complexity metrics, and shape hashes. The columns above are the
+extras layered on top.
+
+## Notable per-language handling
+
+- **C / C++** use syntactic body gating: a `struct device *dev` reference does
+  not create a phantom `device` symbol. Out-of-line method definitions
+  (`T Vec<T>::dot(...)`) reconstruct the owning class scope, so they qualify as
+  `Vec.dot`, not a free function.
+- **TypeScript** maps the TSX grammar for React components and preserves path
+  parameters in template-literal URLs so cross-service links resolve.
+- **Java** Spring controllers inherit class-level path prefixes.
+- **C#** tracks constructor and member calls.
+
+## Adding a language (for contributors)
+
+Adding a language is mostly about writing a good extractor; Tree-sitter does the
+parsing. The shape of the work:
+
+1. **Register the grammar.** Map the file extensions and load the Tree-sitter
+   WASM grammar in the parser context.
+2. **Write the extractor** in `src/parser/languages/<lang>.ts`. It walks the AST
+   and returns definitions (with short names), the names a node calls or
+   references, and imports. Declare its `candidateNodeTypes` so the walker only
+   runs your callbacks on the node types you care about, which keeps big repos
+   fast.
+3. **Get qualified names right.** Return short names and, when a definition has
+   an owning scope (a class, a namespace, an out-of-line method), set the
+   `scopePath` hint and let the walker fold it into the qualified name. Do not
+   hand-build qualified names in the extractor.
+4. **Layer on the optional signals** if the language has them: routes, config or
+   env reads, and outbound service calls.
+5. **Add a smoke fixture** under `tests/fixtures/` and assertions in
+   `tests/smoke.ts`, so the new language is covered and stays covered.
+
+The best starting point is an existing extractor close to your target:
+`go.ts` for a C-family procedural language, `typescript.ts` for something with
+rich imports and routes, `cpp.ts` for the gnarly cases (out-of-line methods,
+body gating). The core pieces to read first are `src/types.ts`,
+`src/parser/walker.ts`, and `src/parser/parserContext.ts`.
+
+The watch-outs that tend to bite: emit type references and forward declarations
+with the right `symbol_role` so they do not pollute search or PageRank; keep the
+extractor pure and deterministic; and make sure cached re-indexing produces the
+exact same rows (the scale and parity tests will catch you if it does not).

package/docs/limits.md

@@ -0,0 +1,52 @@
+# Known Limits
+
+Seer is honest about what it does not do. Knowing these keeps an agent from
+trusting a signal further than it should.
+
+## HTTP route extraction is framework-limited
+
+Server-side routes are extracted for Java (Spring), Python (FastAPI, Flask), and
+TypeScript/JavaScript (Express, Fastify, tRPC, GraphQL). Go `net/http`/gin/chi,
+Rust axum/actix, C# ASP.NET, and C++ have no HTTP route extraction. Those
+backends can still be a *client* in a service link, and they can be a *target*
+over gRPC (routes come from `.proto` files), but not an HTTP target. See
+[Language Support](languages.md).
+
+## Continuity is a snapshot matcher, not a time machine
+
+`seer_continuity` links a rename or move only when both identities exist in the
+current working tree (for example a kept alias). A true cross-commit rename,
+where the old symbol is gone, yields no continuity candidate, on purpose, because
+inventing one would be a false positive. Cross-commit lineage is delivered by
+`seer_history` instead, which follows the file through git. So the "trace
+refactoring across renames" promise is real; it is just fulfilled by history,
+with continuity as advisory snapshot evidence.
+
+## Edge resolution is heuristic, not a compiler
+
+The three-pass resolver (same-file, imported-file, global fallback) is fast and
+language-agnostic, but it is not type-aware. On heavily overloaded or
+dynamically dispatched code, the global fallback can bind to a plausible
+same-name target rather than the exact one. For compiler-grade precision on a
+specific language, layer in a SCIP index with `seer scip-import`; those edges are
+labeled by provenance and sit on top of the tree-sitter baseline.
+
+## It indexes what is on disk
+
+Seer parses source files. Code generated at build time, behavior injected by
+reflection or runtime DI, and routes registered dynamically at startup are
+invisible until they exist as files. `--include-generated` pulls in generated
+files if you want them.
+
+## Resolution percentage is not coverage
+
+The "resolved edges" percentage in `seer stats` reflects how many call edges
+were bound to a definition, which is naturally lower in repos that lean on
+external libraries (those targets are not in the index). It is a health signal,
+not a quality grade.
+
+## Deterministic, not semantic
+
+Seer returns facts, not understanding. It will tell you a function has 9
+dependents and sits on a public route; it will not tell you whether your change
+is correct. That judgment stays with the agent and with you.