@graphpilot-oss/graphpilot 0.0.1 → 0.1.0

package/examples/README.md

@@ -0,0 +1,105 @@
+# GraphPilot — Editor & Agent Examples
+
+Ready-to-paste configurations for every MCP-compatible coding agent we've tested.
+
+Each subfolder follows the same shape:
+
+- `README.md` — step-by-step install for that client (the file you're skimming this for)
+- A sample config file (`.claude.json`, `mcp.json`, `cline_mcp_settings.json`, etc.) you can copy verbatim and edit the path in
+- Where the client supports it: a `CLAUDE.md` / `.cursorrules` / equivalent routing template that nudges the agent to use GraphPilot tools automatically
+
+## Pick your client
+
+| Client          | Folder                                      | Config file location                                                                                            |
+| --------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Claude Code     | [`claude-code/`](claude-code/)              | `~/.claude.json`                                                                                                |
+| Cursor          | [`cursor/`](cursor/)                        | `~/.cursor/mcp.json`                                                                                            |
+| Cline (VS Code) | [`cline/`](cline/)                          | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
+| Windsurf        | [`windsurf/`](windsurf/)                    | `~/.codeium/windsurf/mcp_config.json`                                                                           |
+| Continue.dev    | [`continue/`](continue/)                    | `~/.continue/config.json`                                                                                       |
+| Anything else   | [`docs/mcp-setup.md`](../docs/mcp-setup.md) | n/a — generic stdio MCP instructions                                                                            |
+
+## Two ways GraphPilot can be launched
+
+Every example shows both forms. Pick whichever matches how you installed GraphPilot.
+
+### A) Local build (pre-npm, contributors, dev mode)
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+Then point your client at:
+
+```jsonc
+{
+  "command": "node",
+  "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+}
+```
+
+> **Replace `/absolute/path/to/graphpilot/`** with the real path on your machine. Tilde (`~`) is _not_ expanded by most MCP clients — use the full absolute path.
+
+### B) Once v0.1.0 ships to npm
+
+```jsonc
+{
+  "command": "npx",
+  "args": ["graphpilot", "mcp"],
+}
+```
+
+Or install globally and reference by name:
+
+```bash
+npm install -g @graphpilot-oss/graphpilot
+```
+
+## Cross-platform notes
+
+| Platform | Path style                                                                      |
+| -------- | ------------------------------------------------------------------------------- |
+| macOS    | `/Users/<you>/code/graphpilot/dist/cli.js`                                      |
+| Linux    | `/home/<you>/code/graphpilot/dist/cli.js`                                       |
+| Windows  | `C:\\Users\\<you>\\code\\graphpilot\\dist\\cli.js` (escape backslashes in JSON) |
+
+On Windows in particular, **use double-backslashes in JSON paths** or use forward slashes — both work, single backslashes don't.
+
+## Verifying the connection
+
+After editing the config and **fully restarting** the client (quitting completely, not just closing the window), trigger the client's MCP listing:
+
+- **Claude Code:** type `/mcp` in chat
+- **Cursor:** Settings → MCP
+- **Cline:** the Cline panel → MCP Servers
+- **Windsurf:** Cascade panel → MCP tools
+- **Continue:** Settings → MCP Servers
+
+You should see `graphpilot` with **5 tools** (`gp_index`, `gp_recall`, `gp_callers`, `gp_impact`, `gp_stats`). If not, see [`docs/mcp-setup.md`](../docs/mcp-setup.md#troubleshooting).
+
+## Indexing your first repo
+
+Once the MCP server is connected, ask the agent to index your project — or run it directly:
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js index /path/to/your/repo
+```
+
+Then keep the index fresh as you edit:
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js watch /path/to/your/repo
+```
+
+Watch mode produces sub-10 ms incremental updates on every save. The on-disk `graph.json` is rewritten atomically — the agent always sees a consistent view, even mid-edit.
+
+## End-to-end smoke test
+
+From inside the agent:
+
+```text
+Use graphpilot's gp_stats tool to show the index for this repo.
+```
+
+If the response includes a repo id, file/symbol/edge counts, and an `indexedAt` timestamp — the wire is healthy.

package/examples/claude-code/README.md

@@ -0,0 +1,125 @@
+# Claude Code (Anthropic) + GraphPilot
+
+Step-by-step install of GraphPilot as an MCP server inside Claude Code.
+
+## 1. Build GraphPilot
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+The compiled CLI lands at `dist/cli.js`. Verify:
+
+```bash
+node dist/cli.js --help
+```
+
+## 2. Edit `~/.claude.json`
+
+Create the file if it doesn't exist. Add the `mcpServers` block:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+    },
+  },
+}
+```
+
+A copy-paste-ready sample is in [`claude_config.json`](./claude_config.json). Replace `/absolute/path/to/graphpilot/` with the real path on your machine.
+
+Once v0.1.0 ships to npm, you can simplify to:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "npx",
+      "args": ["graphpilot", "mcp"],
+    },
+  },
+}
+```
+
+## 3. Fully restart Claude Code
+
+Quit completely — don't just close the window. `~/.claude.json` is read on launch only.
+
+## 4. Verify the wire
+
+In any Claude Code session, type:
+
+```text
+/mcp
+```
+
+You should see:
+
+```
+graphpilot
+  5 tools: gp_index, gp_recall, gp_callers, gp_impact, gp_stats
+```
+
+If the server doesn't appear, run `node /abs/path/to/graphpilot/dist/cli.js mcp` in a terminal and check stderr for the error — most config bugs surface immediately.
+
+## 5. Index a repo
+
+From the terminal of any TS/JS project:
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js index .
+```
+
+Or ask Claude:
+
+```text
+Use graphpilot's gp_index tool on this repo.
+```
+
+## 6. Make Claude reach for GraphPilot automatically
+
+Copy [`CLAUDE.md`](./CLAUDE.md) (the routing template in this folder) into the **root of the repo you indexed**. Restart Claude one more time. From that point on, structural questions route to GraphPilot without you having to say _"use graphpilot to…"_.
+
+Try:
+
+```text
+Who calls authenticate in this repo?
+
+What breaks if I rename parseFile?
+
+Find every function whose name contains 'parse'.
+```
+
+You should see a `Calling graphpilot/gp_*` line in the response — that's the tool firing.
+
+## 7. Keep the index fresh (optional)
+
+In a side terminal:
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js watch /path/to/your/repo
+```
+
+Sub-10 ms incremental updates on every save. Ctrl+C to stop.
+
+## Troubleshooting
+
+| Symptom                                   | Fix                                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `/mcp` doesn't list `graphpilot`          | Edits to `~/.claude.json` don't hot-reload. Fully quit Claude Code and relaunch.                              |
+| Tools list but every call says "no index" | Path mismatch — pass an explicit `path: "/abs/repo"` argument, or index from the same `cwd` Claude uses.      |
+| `pnpm install` fails on native modules    | `pnpm approve-builds --all && pnpm rebuild`. On Node 23+, drop to Node 22 LTS — tree-sitter is finicky on 23. |
+
+Anything not listed: [open an issue](https://github.com/graphpilot-oss/graphpilot/issues) with the stderr from `node dist/cli.js mcp`.
+
+## Files in this folder
+
+| File                                         | Purpose                                                                                    |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| [`README.md`](./README.md)                   | This walkthrough                                                                           |
+| [`claude_config.json`](./claude_config.json) | Sample `~/.claude.json` content — copy the `mcpServers` block into yours                   |
+| [`CLAUDE.md`](./CLAUDE.md)                   | Drop-in routing template — copy to your indexed repo's root so Claude auto-uses GraphPilot |

package/examples/claude-code/claude-routing.md

@@ -0,0 +1,102 @@
+# GraphPilot + Claude Code
+
+This routing template directs structural code questions to the `graphpilot` MCP server instead of grep/LSP, unlocking the core benefits: branch-aware differential analysis, evidence anchors, and single-call blast-radius computation.
+
+## Setup
+
+1. Install GraphPilot locally:
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+2. Index your repo:
+
+```bash
+node dist/cli.js index /path/to/your/repo
+node dist/cli.js watch /path/to/your/repo &  # keeps index fresh
+```
+
+3. Configure Claude Code MCP server (in `~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"]
+    }
+  }
+}
+```
+
+4. Copy this file into your repo root (or a `.claude/` dir).
+
+## Routing rules
+
+**For "who calls X?" questions:**
+
+- Use `gp_callers` instead of grep / LSP.
+- Single call returns both direct + transitive callers with evidence anchors.
+- Example: _"What functions call `validateUser`?"_ → `gp_callers(validateUser)`
+
+**For "what breaks if I rename/delete X?" questions:**
+
+- Use `gp_impact` instead of composing grep + git.
+- Returns direct callers + transitive callers + tests affected + public-API flag.
+- Single call, no chaining.
+- Example: _"What breaks if I rename `parseFile`?"_ → `gp_impact(parseFile)`
+
+**For "what does my PR touch?" (diff-scoped refactors):**
+
+- Use `gp_impact({since: 'main'})` to filter the blast radius to only your branch.
+- Cuts noise: only callers in files _you actually changed_ are returned.
+- Example: _"On this feature branch, if I rename `fooHelper`, which of my changed files will break?"_ → `gp_impact(fooHelper, {since: 'main'})`
+
+**For "find all functions matching a pattern:"**
+
+- Use `gp_recall` for exact or substring search.
+- Fast, structural, no false positives from comments.
+- Example: _"List every function whose name contains 'parse'"_ → `gp_recall({kind: 'function', name: 'parse'})`
+
+**For "enumerate all X of kind Y:"**
+
+- Use `gp_recall` with a kind filter.
+- Example: _"List every TypeScript interface"_ → `gp_recall({kind: 'interface'})`
+
+**Fallback: grep or text search:**
+
+- Use grep only for string-literal searches (constants, error messages, comments).
+- GraphPilot doesn't index text content, only structure.
+- Example: _"Find every place `MAX_FILE_SIZE` is mentioned"_ → grep
+
+## Evidence anchors
+
+Every `gp_*` tool response includes `file:line @ sha` citations. Example output:
+
+```
+1. analyzeImpact  (function)  src/impact.ts:168 @ ab12cd3
+   export function analyzeImpact(idx: GraphIndex, ...): ImpactResult | null
+```
+
+When citing results to your user, include these anchors verbatim. They're verifiable: paste `src/impact.ts:168` into your editor's goto-line command and the code will match the quoted excerpt.
+
+**Why it matters:** If a tool ever hallucinated a symbol or a caller, you'd spot it instantly by jumping to the file. No more "the tool said this exists but I can't find it" dead ends.
+
+## Scope & limitations
+
+GraphPilot v0.1 indexes **TypeScript/JavaScript only**. For Python/Rust/Go repos, fall back to grep or your IDE's LSP.
+
+- **Fast:** sub-second recall on repos up to ~100k LOC.
+- **Deterministic:** same repo = same index (not language-model based, no flakiness).
+- **Structural only:** no semantic search, no taint analysis, no control-flow analysis (yet).
+
+See [`docs/limitations.md`](../../docs/limitations.md) in the GraphPilot repo for the full boundary conditions.
+
+## Tips for agent use
+
+1. **Always check the SHA.** If the index SHA is old (> a few hours), ask the user to re-run `graphpilot watch` or re-index.
+2. **On cache miss.** If `gp_recall` returns no results, confirm the symbol name and kind — it may be spelled differently or exported as a type alias.
+3. **Test the evidence.** Before recommending a refactor, jump to one of the cited file:line anchors yourself to confirm the code matches.
+4. **Diff-scoped analysis.** For PR review, always use `gp_impact({since: 'main'})` instead of the raw impact — it cuts false positives.

package/examples/claude-code/claude_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"]
+    }
+  }
+}

package/examples/cline/.clinerules

@@ -0,0 +1,39 @@
+# GraphPilot routing rules for Cline
+
+This repo has a GraphPilot structural code-graph available via MCP. Use it before grep on structural questions.
+
+## When the user asks any of:
+
+- "who calls X" / "what uses X" / "where is X called from"
+- "what does X call" / "what does X depend on"
+- "rename X — what breaks" / "impact of changing X" / "what depends on X"
+- "find function X" / "where is X defined" / "list all interfaces"
+
+→ **Use the graphpilot MCP tools BEFORE grep or reading files.**
+
+| Question kind          | Tool to call                                            |
+| ---------------------- | ------------------------------------------------------- |
+| Define / locate symbol | `gp_recall({ query, substring?, path? })`               |
+| Callers / callees      | `gp_callers({ symbol, direction, path? })`              |
+| Blast radius / rename  | `gp_impact({ symbol, depth?, path? })`                  |
+| PR-scoped blast radius | `gp_impact({ symbol, since: 'main', path? })`           |
+| Index health probe     | `gp_stats({ path? })`                                   |
+| Refresh after edits    | `gp_index({ path? })`                                   |
+
+## When NOT to use GraphPilot
+
+Fall back to grep / read for:
+
+- Comments, JSDoc, string literals, error messages
+- Config files (package.json, tsconfig.json, .env)
+- Markdown / docs
+- Languages other than TypeScript / JavaScript
+- Git history (blame, log)
+
+## After heavy editing
+
+After ~10+ file edits, call `gp_index` once before further structural questions, or run `graphpilot watch` in a side terminal for sub-10 ms incremental updates.
+
+## Citing evidence
+
+Every GraphPilot response carries `file:line @ sha` anchors. When citing results to the user, **include the anchor verbatim** — it's verifiable: the user can jump to that line and the code will match.

package/examples/cline/README.md

@@ -0,0 +1,104 @@
+# Cline (VS Code extension) + GraphPilot
+
+Step-by-step install of GraphPilot as an MCP server inside Cline.
+
+## 1. Build GraphPilot
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+## 2. Open Cline's MCP settings
+
+The easy way:
+
+1. Open VS Code
+2. Open the **Cline panel** (sidebar icon)
+3. Click **MCP Servers**
+4. Click the ⚙ gear icon → **Edit MCP Settings**
+
+That opens `cline_mcp_settings.json`. Direct paths if you prefer to edit it manually:
+
+| OS      | Path                                                                                                            |
+| ------- | --------------------------------------------------------------------------------------------------------------- |
+| macOS   | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
+| Linux   | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`                     |
+| Windows | `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`                     |
+
+## 3. Add the GraphPilot block
+
+Paste the contents of [`cline_mcp_settings.json`](./cline_mcp_settings.json) and replace `/absolute/path/to/graphpilot/` with the real path:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+      "disabled": false,
+      "autoApprove": [],
+    },
+  },
+}
+```
+
+Post-npm:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "npx",
+      "args": ["graphpilot", "mcp"],
+      "disabled": false,
+      "autoApprove": [],
+    },
+  },
+}
+```
+
+> The `autoApprove` array lets you list tool names that Cline will call without per-call confirmation. Add e.g. `["gp_recall", "gp_stats"]` once you're comfortable — leave it empty until then.
+
+## 4. Verify
+
+In the Cline panel → **MCP Servers** section, `graphpilot` should appear with a **green status dot** and 5 tools listed underneath. If it doesn't, restart VS Code.
+
+## 5. Index a repo
+
+From the integrated terminal:
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js index .
+```
+
+## 6. Try it
+
+```text
+Use graphpilot to find who calls authenticate.
+
+Use gp_impact to show the blast radius of renaming parseFile.
+```
+
+Cline will surface a tool-call card with the request → response → "Approve" button. Once approved, the result appears in the chat with `file:line @ sha` evidence anchors.
+
+## 7. Keep the index fresh
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js watch .
+```
+
+## Troubleshooting
+
+| Symptom                                | Fix                                                                                                                         |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Server shows red / disconnected        | Check `disabled: false`. Then try VS Code: Command Palette → "Developer: Reload Window".                                    |
+| Cline can't find tools after a restart | The settings file is JSON-strict — a trailing comma will silently disable the entire `mcpServers` block. Validate the JSON. |
+| Tool calls return "no index"           | Pass an explicit `path: "/abs/repo"`, or run `gp_index` first.                                                              |
+
+## Files in this folder
+
+| File                                                   | Purpose                                                |
+| ------------------------------------------------------ | ------------------------------------------------------ |
+| [`README.md`](./README.md)                             | This walkthrough                                       |
+| [`cline_mcp_settings.json`](./cline_mcp_settings.json) | Sample config — copy the `mcpServers` block into yours |

package/examples/cline/cline_mcp_settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}

package/examples/continue/.continuerules

@@ -0,0 +1,39 @@
+# GraphPilot routing rules for Continue
+
+This repo has a GraphPilot structural code-graph available via MCP. Use it before grep on structural questions.
+
+## When the user asks any of:
+
+- "who calls X" / "what uses X" / "where is X called from"
+- "what does X call" / "what does X depend on"
+- "rename X — what breaks" / "impact of changing X" / "what depends on X"
+- "find function X" / "where is X defined" / "list all interfaces"
+
+→ **Use the graphpilot MCP tools BEFORE grep or reading files.**
+
+| Question kind          | Tool to call                                            |
+| ---------------------- | ------------------------------------------------------- |
+| Define / locate symbol | `gp_recall({ query, substring?, path? })`               |
+| Callers / callees      | `gp_callers({ symbol, direction, path? })`              |
+| Blast radius / rename  | `gp_impact({ symbol, depth?, path? })`                  |
+| PR-scoped blast radius | `gp_impact({ symbol, since: 'main', path? })`           |
+| Index health probe     | `gp_stats({ path? })`                                   |
+| Refresh after edits    | `gp_index({ path? })`                                   |
+
+## When NOT to use GraphPilot
+
+Fall back to grep / read for:
+
+- Comments, JSDoc, string literals, error messages
+- Config files (package.json, tsconfig.json, .env)
+- Markdown / docs
+- Languages other than TypeScript / JavaScript
+- Git history (blame, log)
+
+## After heavy editing
+
+After ~10+ file edits, call `gp_index` once before further structural questions, or run `graphpilot watch` in a side terminal for sub-10 ms incremental updates.
+
+## Citing evidence
+
+Every GraphPilot response carries `file:line @ sha` anchors. When citing results to the user, **include the anchor verbatim** — it's verifiable: the user can jump to that line and the code will match.

package/examples/continue/README.md

@@ -0,0 +1,98 @@
+# Continue.dev + GraphPilot
+
+Step-by-step install of GraphPilot as an MCP server inside Continue.
+
+> Continue's MCP support is flagged **experimental** at the time of writing. If the config key below isn't recognized, check the [Continue docs](https://docs.continue.dev) for the current schema.
+
+## 1. Build GraphPilot
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+## 2. Edit Continue's config
+
+Two scopes — pick one:
+
+- **Global:** `~/.continue/config.json`
+- **Per-project:** `<your-repo>/.continue/config.json`
+
+Create the file if it doesn't exist. Paste the contents of [`config.json`](./config.json) and replace `/absolute/path/to/graphpilot/` with the real path:
+
+```jsonc
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "node",
+          "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+        },
+      },
+    ],
+  },
+}
+```
+
+Post-npm:
+
+```jsonc
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["graphpilot", "mcp"],
+        },
+      },
+    ],
+  },
+}
+```
+
+## 3. Restart Continue
+
+Reload the VS Code / JetBrains window after editing the config.
+
+## 4. Verify
+
+Continue → Settings → **MCP Servers** panel. `graphpilot` should be listed with 5 tools.
+
+## 5. Index a repo
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js index .
+```
+
+## 6. Try it
+
+```text
+Use graphpilot's gp_recall to find parseToken.
+
+Use gp_impact to compute the blast radius of renaming authenticate.
+```
+
+## 7. Keep the index fresh
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js watch .
+```
+
+## Troubleshooting
+
+| Symptom                                                 | Fix                                                                                       |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `modelContextProtocolServers` reported as "unknown key" | Your Continue version is on an older schema. Check the current docs for the new key name. |
+| Server appears but tools aren't called                  | Continue's MCP autorouting is conservative. Be explicit: _"Use graphpilot's gp_callers…"_ |
+| `pnpm install` native-module errors                     | `pnpm approve-builds --all && pnpm rebuild`. Drop to Node 22 LTS if on 23+.               |
+
+## Files in this folder
+
+| File                           | Purpose                                                      |
+| ------------------------------ | ------------------------------------------------------------ |
+| [`README.md`](./README.md)     | This walkthrough                                             |
+| [`config.json`](./config.json) | Sample `~/.continue/config.json` — copy the block into yours |

package/examples/continue/config.json

@@ -0,0 +1,13 @@
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "node",
+          "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"]
+        }
+      }
+    ]
+  }
+}