seer-mcp 0.1.0

package/docs/mcp.md

@@ -0,0 +1,199 @@
+# MCP Setup
+
+Seer speaks the Model Context Protocol over stdio. Any MCP-capable agent can
+talk to it. The annoying part of MCP is that every client invented its own
+config file, root key, and location, so this page covers all of them, plus a
+command that writes them for you.
+
+---
+
+## The fast path: `seer init`
+
+From inside the repo you want indexed:
+
+```bash
+seer init
+```
+
+This writes a project-local MCP config for Claude Code, Cursor, VS Code, Codex,
+and Gemini, and drops an `AGENTS.md` guidance block so the agent knows Seer
+exists and when to call it. It is idempotent: run it again and it leaves
+existing entries alone unless you pass `--force`.
+
+### Options
+
+| Flag | What it does |
+|---|---|
+| `--client <names>` | Comma-separated subset: `claude,cursor,vscode,codex,gemini,antigravity`, or `all`. |
+| `--global` | Write the user-level config instead of the project-local one. |
+| `--npx` | Emit a portable `npx -y seer-mcp mcp` launcher (no machine paths). |
+| `--pkg <name>` | Package name for the `--npx` launcher (default `seer-mcp`). |
+| `--command <cmd>` | Override the launch command entirely (advanced). |
+| `--no-agents` | Do not write `AGENTS.md`. |
+| `--print` | Show the plan and the exact snippets without writing anything. |
+| `--force` | Overwrite an existing `seer` entry / `AGENTS.md` block. |
+| `--db <path>` | Use a custom database path in the launcher. |
+
+### What the launcher looks like
+
+By default `seer init` writes an absolute-path launcher, which works right now
+without publishing anything:
+
+```
+node /abs/path/to/Seer-Core/dist/cli/index.js mcp --workspace /abs/path/to/your-repo
+```
+
+If you have published or linked the package, `--npx` gives you a portable
+launcher that any teammate can use as-is (it relies on the client starting the
+server with the repo as its working directory):
+
+```
+npx -y seer-mcp mcp
+```
+
+---
+
+## Manual configuration
+
+Prefer to paste it yourself? Here is the exact config for each client. The
+launcher (`command` + `args`) is the same everywhere; only the file location and
+the surrounding keys differ. Replace the path with your absolute path, or use
+the `npx` form.
+
+### Claude Code
+
+Project-local: `.mcp.json` at the repo root. User-level: `~/.claude.json`.
+
+```json
+{
+  "mcpServers": {
+    "seer": {
+      "command": "npx",
+      "args": ["-y", "seer-mcp", "mcp"]
+    }
+  }
+}
+```
+
+You can also use the CLI: `claude mcp add seer -- npx -y seer-mcp mcp`.
+
+### Cursor
+
+Project-local: `.cursor/mcp.json`. User-level: `~/.cursor/mcp.json`. Same shape
+as Claude Code (the `mcpServers` key).
+
+```json
+{
+  "mcpServers": {
+    "seer": { "command": "npx", "args": ["-y", "seer-mcp", "mcp"] }
+  }
+}
+```
+
+### VS Code (Copilot / native MCP)
+
+Project-local: `.vscode/mcp.json`. Note the different root key (`servers`) and
+the required `type`.
+
+```json
+{
+  "servers": {
+    "seer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "seer-mcp", "mcp"]
+    }
+  }
+}
+```
+
+### OpenAI Codex
+
+User-level: `~/.codex/config.toml`. Project-local: `.codex/config.toml`. This one
+is TOML, not JSON.
+
+```toml
+[mcp_servers.seer]
+command = "npx"
+args = ["-y", "seer-mcp", "mcp"]
+```
+
+### Gemini CLI
+
+Project-local: `.gemini/settings.json`. User-level: `~/.gemini/settings.json`.
+
+```json
+{
+  "mcpServers": {
+    "seer": { "command": "npx", "args": ["-y", "seer-mcp", "mcp"] }
+  }
+}
+```
+
+### Google Antigravity
+
+User-level only, shared across the Antigravity IDE and CLI:
+`~/.gemini/config/mcp_config.json`. Uses the `mcpServers` key. Because there is
+no project-local file, `seer init` only touches this one when you ask for it
+(`--client antigravity` or `--client all`).
+
+```json
+{
+  "mcpServers": {
+    "seer": { "command": "npx", "args": ["-y", "seer-mcp", "mcp"] }
+  }
+}
+```
+
+---
+
+## Letting the agent know Seer exists
+
+Configuring the server is half the job. The other half is making sure the agent
+actually reaches for it instead of grepping. `seer init` writes an `AGENTS.md`
+block (the cross-agent convention that Codex, Cursor, Gemini, and Claude Code
+all read) describing what Seer is and the recommended workflow:
+
+1. `seer_health` to confirm the index is live.
+2. `seer_architecture` or `seer_boundaries` to orient.
+3. `seer_preflight { symbol }` before editing an unfamiliar symbol.
+4. `seer_preflight { fromRef, toRef }` for the blast radius of a diff.
+5. `seer_behavior` / `seer_history` for tests and blame.
+6. `seer_skeleton { file }` to read a big file cheaply.
+
+The block is wrapped in `<!-- seer:begin -->` / `<!-- seer:end -->` markers so a
+re-run updates it cleanly without clobbering the rest of your `AGENTS.md`.
+
+---
+
+## Server options
+
+The MCP server itself is `seer mcp`:
+
+```bash
+seer mcp --workspace <repo-path> [--db <path>] [--no-watch] [--no-jit]
+```
+
+- `--workspace` defaults to the current working directory.
+- `--no-watch` disables the background file watcher.
+- `--no-jit` disables the freshness check that runs before each query.
+
+The full tool surface is documented in the [Tool Guide](tools.md).
+
+---
+
+## Troubleshooting
+
+**The agent does not list any Seer tools.** Reload the MCP servers (most clients
+have a refresh button or need a restart). Confirm the config file is where that
+client expects it, and that `node`/`npx` is on the PATH the client launches with.
+
+**First query is slow.** That is the initial index. It runs once, then the cache
+makes everything fast. You can pre-build it with `seer index .`.
+
+**"Could not find .seer/graph.db".** A CLI query was run outside the repo. Pass
+`--db <path>` or run from inside the workspace.
+
+**Stale results.** Seer hashes files before each query and re-parses anything
+that changed, so this should not happen. If it does, `seer index . --reset`
+rebuilds from scratch.

package/docs/quickstart.md

@@ -0,0 +1,119 @@
+# Quick Start
+
+Seer is a local MCP server. You point it at a repo, it builds a small SQLite
+index, and your AI agent can then ask it structural questions instead of
+grepping around. This page gets you from zero to a connected agent.
+
+There is no account, no API key, and nothing leaves your machine.
+
+---
+
+## 1. Install
+
+You need Node.js 18 or newer (Node 26+ recommended).
+
+### From source (works today)
+
+```bash
+git clone https://github.com/vladimirhegai/Seer-Core.git
+cd Seer-Core
+npm install
+npm run build
+```
+
+That produces the runnable CLI at `dist/cli/index.js`. If you want a global
+`seer` command, link it:
+
+```bash
+npm link        # now `seer` is on your PATH
+```
+
+### From npm
+
+Once published, the whole thing collapses to one line that every agent can run
+without a global install:
+
+```bash
+npx -y seer-mcp mcp
+```
+
+---
+
+## 2. Connect your agent (the easy way)
+
+Run `seer init` inside the repo you want indexed. It detects nothing magical;
+it just writes the right MCP config snippet to the right file for each agent,
+and drops an `AGENTS.md` so the agent knows the tool exists and how to use it.
+
+```bash
+seer init
+```
+
+By default it configures the clients that support a project-local config file
+(Claude Code, Cursor, VS Code, Codex, Gemini) and leaves a shareable, committable
+config in your repo. Want everything, including the user-level ones?
+
+```bash
+seer init --client all
+```
+
+Pick specific agents:
+
+```bash
+seer init --client claude,cursor
+```
+
+See exactly what it would write without touching anything:
+
+```bash
+seer init --print
+```
+
+Full options live in [MCP Setup](mcp.md). If you would rather paste the snippet
+yourself, that page has the exact JSON/TOML for every client.
+
+---
+
+## 3. First query
+
+Restart (or reload the MCP servers in) your agent. Seer indexes the workspace
+automatically the first time it is queried, so you do not have to run an index
+step by hand. Ask your agent something like:
+
+> Call seer_health, then give me the architecture overview.
+
+If `seer_health` comes back with a schema version and some role counts, you are
+connected.
+
+---
+
+## 4. Using the CLI directly (optional)
+
+The same engine works from a plain shell, which is handy for scripting or just
+poking around:
+
+```bash
+seer index .                 # build/refresh the index
+seer architecture            # one-page overview of the repo
+seer symbols --top 20        # top symbols by PageRank
+seer preflight --symbol foo  # everything you need before editing `foo`
+```
+
+The full command list is in the [CLI Reference](cli.md).
+
+---
+
+## Where the index lives
+
+Seer writes a single SQLite file to `<repo>/.seer/graph.db`. Add `.seer/` to
+your `.gitignore` if you do not want to commit it. Delete the folder any time;
+it rebuilds on the next query or `seer index`.
+
+---
+
+## Next steps
+
+- [MCP Setup](mcp.md) for every client's config and troubleshooting.
+- [Tool Guide](tools.md) for what each MCP tool returns.
+- [Examples](examples.md) for real agent workflows.
+- [Architecture](architecture.md) for how the index is built.

package/docs/testing.md

@@ -0,0 +1,123 @@
+# Testing
+
+## The short version
+
+Seer ships with a large automated test suite: more than 900 individual checks
+across 37 test files. Every check has to pass before anything is considered
+done, and we keep a strict no-regression rule, so once a bug is fixed it gets a
+test that fails if the bug ever comes back.
+
+The tests fall into a few plain-English buckets:
+
+| What it checks | In human terms |
+|---|---|
+| Reading code correctly | Does Seer pull the right functions, classes, and calls out of each language? |
+| Not getting confused at scale | Does a huge repo index the same way every time, with no crashes? |
+| Staying fresh | When a file changes, does the next answer reflect it, instantly? |
+| The agent tools | Do the MCP tools return what they promise, including the token-saving ones? |
+| Cross-service tracing | Do calls in one service correctly link to handlers in another? |
+| Edit-impact features | Are risk, tests, history, and blast radius accurate? |
+| Easy install | Does `seer init` write the right config for every agent? |
+| Old bugs | Every bug we ever fixed has a test so it cannot return. |
+
+If you just want to confirm everything works on your machine:
+
+```bash
+npm install
+npm test
+```
+
+A green run means all of the above passed.
+
+---
+
+## The categories in a bit more detail
+
+**Reading code (smoke tests).** Small hand-written fixtures in each supported
+language. They confirm the parser finds the right symbols, builds the right
+qualified names, and resolves basic calls. This is the foundation; if these
+break, nothing else matters.
+
+**Scale and determinism.** Seer indexes real, large open-source repos and checks
+that a second run produces byte-identical counts, that the cache truly
+rehydrates, and that nothing crashes or drifts. This is also where speed is
+measured (see [Benchmarks](benchmarks.md)).
+
+**Worker threads.** Parsing runs across multiple threads for speed. These tests
+prove the parallel path produces the exact same result as the simple serial
+path, and that a crashed worker is recovered without corrupting the index.
+
+**Freshness and the watcher.** Simulates an agent editing files in bursts and
+confirms the index updates instantly, without stalls, leaks, or duplicate rows,
+and that deleted files are pruned.
+
+**The MCP tools.** Drives the actual server the way an agent would, over its
+real protocol, and checks each tool's output. A dedicated optimization spec
+covers the token-budget trimming, the "did you mean" suggestions on typos, the
+file-skeleton renderer, and the batch and trace helpers.
+
+**Cross-service links.** Builds small multi-service repos and confirms that an
+outbound call (HTTP, gRPC, tRPC, GraphQL, or a message queue) resolves to the
+right route handler, including across separate repos via bundles.
+
+**Edit-impact features.** The risk score, the ranked tests, the per-symbol
+history, the monorepo boundaries, and the rename/move continuity all have their
+own suites with concrete expected values.
+
+**Install.** Confirms `seer init` writes valid, mergeable config for Claude
+Code, Cursor, VS Code, Codex, and Gemini, that re-running is safe, and that it
+never clobbers your existing settings.
+
+**Regressions.** Every real bug found, including during the pre-release stress
+pass, is pinned with a test in `tests/bug-regressions.ts`, so it cannot quietly
+come back.
+
+---
+
+## Running your own
+
+The whole suite:
+
+```bash
+npm test
+```
+
+Just one category (handy while working on a feature):
+
+```bash
+npm run test:smoke         # language extractors
+npm run test:mcp           # the MCP server + optimization spec
+npm run test:init          # the cross-agent installer
+npm run test:tracke        # modules, behavior, risk, context
+npm run test:trackg        # service links and protocols
+npm run test:tracki        # external bundles, contract diff, preflight, boundaries, continuity
+npm run test:regressions   # locked-in bug fixes
+```
+
+The large-codebase suite is separate because it needs real repos checked out
+under `Large Codebases/` and takes a while:
+
+```bash
+npm run scale-test                       # all available codebases
+npm run scale-test -- --only helix,react # a subset
+npm run scale-test -- --skip unreal      # exclude the slow ones
+```
+
+It writes a human-readable summary to `tests/outputs/latest.md` and a full
+machine-readable report alongside it.
+
+There is also a parity gate that proves the parallel and serial indexers agree
+row-for-row at scale:
+
+```bash
+npm run test:scale-parallel-parity
+```
+
+---
+
+## What a passing run looks like
+
+Each test file prints a line per check and a final tally. A clean run ends with
+every file reporting `PASS` and a zero failure count. If anything fails, the
+exit code is non-zero (so CI catches it) and the failing check prints what it
+expected versus what it got.

package/docs/tools.md

@@ -0,0 +1,115 @@
+# Tool Guide
+
+These are the MCP tools an agent sees once Seer is connected. Everything is
+read-only structural fact: no prose, no summaries, no guessing. If a lookup
+finds nothing, list tools return a `didYouMean` array of close matches rather
+than a dead end.
+
+This page is about what each tool is *for*. For exact parameters, every tool
+also self-describes its input schema over MCP, so your agent sees the arguments
+inline.
+
+---
+
+## Start here
+
+| Tool | Use it when |
+|---|---|
+| `seer_health` | You want to confirm the index is live and fresh. Cheap. |
+| `seer_architecture` | You just landed in an unfamiliar repo and need the lay of the land. |
+| `seer_preflight` | You are about to edit something, or want a diff's blast radius. |
+
+`seer_preflight` is the workhorse. Give it a symbol and it returns the
+definition, who calls it, transitive dependents, the tests that cover it, recent
+commit history, and a risk verdict, all in one call. Give it `fromRef`/`toRef`
+and it maps a git diff to the affected symbols and their blast radius.
+
+---
+
+## Navigation and search
+
+- `seer_symbols` (`query?`, `top?`) BM25 search, or top symbols by PageRank.
+- `seer_definition` (`name`, `file?`) exact definition lookup.
+- `seer_file_symbols` (`file`) symbols in a file, in line order.
+- `seer_callers` / `seer_callees` (`symbol`) direct neighbors, with a true count.
+- `seer_search` (`query`) combined symbol + file-path search.
+- `seer_skeleton` (`file`, `focusSymbol?`) render a file as signatures only, with
+  bodies collapsed to `{ ... N lines ... }`. Read a 2,000-line file for the cost
+  of its outline. `focusSymbol` expands one body verbatim.
+
+## Routes, deps, config
+
+- `seer_routes` (`method?`, `framework?`, `pathSubstr?`)
+- `seer_dependencies` (`ecosystem?`, `nameSubstr?`)
+- `seer_config` (`key?`, `source?`)
+
+## Complexity and blast radius
+
+- `seer_complexity` (`by?`, `minValue?`) cyclomatic / cognitive / LOC rankings.
+- `seer_behavior` (`symbol`) tests that exercise the symbol, ranked by how
+  directly they hit it.
+- `seer_trace_path` (`from`, `to`) shortest call path between two symbols.
+- `seer_trace_callers` / `seer_trace_callees` (`symbol`, `maxDepth?`) transitive
+  reachability.
+- `seer_detect_changes` (`fromRef?`, `toRef?`) blast radius for a diff.
+
+## Modules and boundaries
+
+- `seer_modules`, `seer_module_members`, `seer_symbol_module`,
+  `seer_module_dependencies` Louvain clusters and their edges.
+- `seer_boundaries`, `seer_boundary_for_file`, `seer_boundary_dependencies`
+  monorepo package partitions and crossings.
+- `seer_trace_file_dependencies`, `seer_trace_module_dependencies` import BFS.
+
+## History and continuity
+
+- `seer_churn` file-level git stats.
+- `seer_history` (`symbol`) per-symbol commit blame chain.
+- `seer_continuity` (`symbol`) rename/move evidence (advisory, confidence-labeled).
+
+## Portability and precision
+
+- `seer_bundle_export`, `seer_bundle_info`, `seer_bundle_import` portable
+  `.seerbundle` archives.
+- `seer_external_bundles` list imported peer-repo layers.
+- `seer_contract_diff` (`oldBundle`, `newBundle`) advisory API diff across protocols.
+- `seer_scip_import`, `seer_scip_imports`, `seer_provenance` SCIP precision overlays.
+- `seer_duplicates` near-duplicate code clusters via SimHash.
+
+## Service links (cross-service)
+
+- `seer_service_calls`, `seer_service_links` outbound calls resolved to handlers.
+- `seer_trace_service_path`, `seer_trace_service_dependencies`,
+  `seer_trace_module_service_dependencies` cross-service BFS.
+
+## Unified context
+
+- `seer_preflight` consolidated pre-edit packet (symbol or diff-range mode).
+- `seer_context` consolidated symbol context.
+- `seer_risk` decomposed edit-risk analysis.
+
+---
+
+## Tools that save round-trips
+
+- `seer_batch` (`calls`) run up to 25 read-only tools in a single request.
+  One failing call does not abort the rest. It cannot nest inside itself.
+- `seer_trace` (`scope`, `args?`) a single entry point that dispatches to the
+  whole `seer_trace_*` family (`callers`, `callees`, `path`, `file`, `module`,
+  `service`, `service_path`, `module_service`).
+
+## Keeping output small
+
+The high-volume list tools (`seer_symbols`, `seer_definition`, `seer_callers`,
+`seer_callees`, `seer_complexity`, `seer_service_calls`, `seer_service_links`)
+accept an optional `tokenBudget`. Seer packs the highest-ranked rows until the
+serialized payload would exceed roughly `tokenBudget * 4` characters, then flags
+`truncated: true` with an `omitted` count and a note on how to get the rest. With
+no budget, output is untrimmed and byte-identical to before.
+
+## Tools you usually do not need
+
+The heavy derived indexes (modules, shape hashes, symbol history) build
+themselves on first use. The manual `*_build` tools (`seer_modules_build`,
+`seer_symbol_history_build`, `seer_shape_hash_build`) are there only to force a
+rebuild.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "seer-mcp",
+  "version": "0.1.0",
+  "description": "Local-first AI codebase explainer — onboarding from months to days",
+  "private": false,
+  "type": "commonjs",
+  "bin": {
+    "seer": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/cli/index.ts",
+    "build": "tsc",
+    "test": "npm run test:smoke && npm run test:parallel && npm run test:trackcd && npm run test:tracke && npm run test:trackf && npm run test:trackg && npm run test:tracki && npm run test:git && npm run test:regressions && npm run test:query-parity && npm run test:filters && npm run test:init && npm run test:parallel-suite && npm run test:mcp && npm run test:bench",
+    "test:init": "tsx tests/init.ts",
+    "test:parallel-suite": "npm run build && tsx tests/worker-parity.ts && tsx tests/worker-pool.ts && tsx tests/parallel-index.ts && tsx tests/parallel-recovery.ts",
+    "test:smoke": "tsx tests/smoke.ts",
+    "test:mcp": "npm run build && tsx tests/mcp-smoke.ts && tsx tests/mcp-jit.ts && tsx tests/mcp-watcher.ts && tsx tests/mcp-trackcd.ts && tsx tests/mcp-tracke.ts && tsx tests/mcp-trackf.ts && tsx tests/mcp-trackg.ts && tsx tests/mcp-tracki.ts && tsx tests/optspec.ts",
+    "test:parallel": "tsx tests/parallel-read.ts",
+    "test:trackcd": "tsx tests/trackcd.ts",
+    "test:tracke": "tsx tests/tracke.ts && tsx tests/tracke-collisions.ts",
+    "test:trackf": "tsx tests/trackf.ts && tsx tests/trackf-bugs.ts",
+    "test:trackg": "tsx tests/trackg.ts",
+    "test:tracki": "tsx tests/tracki-external-bundles.ts && tsx tests/tracki-contract-diff.ts && tsx tests/tracki-preflight.ts && tsx tests/tracki-boundaries.ts && tsx tests/tracki-continuity.ts",
+    "test:git": "tsx tests/git-features.ts",
+    "test:regressions": "tsx tests/bug-regressions.ts",
+    "test:query-parity": "tsx tests/query-parity.ts",
+    "test:filters": "tsx tests/filters.ts",
+    "test:bench": "tsx tests/benchmark-service-links.ts",
+    "test:worker-parity": "npm run build && tsx tests/worker-parity.ts",
+    "test:worker-pool": "npm run build && tsx tests/worker-pool.ts",
+    "test:parallel-index": "npm run build && tsx tests/parallel-index.ts",
+    "test:parallel-recovery": "npm run build && tsx tests/parallel-recovery.ts",
+    "scale-test": "tsx tests/scale-test.ts",
+    "test:scale-parallel-parity": "npm run build && tsx tests/scale-parallel-parity.ts",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chokidar": "^5.0.0",
+    "commander": "^12.0.0",
+    "fast-glob": "^3.3.2",
+    "ignore": "^5.3.1",
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^5.0.5",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}