purecontext-mcp 1.5.2 → 1.11.0

package/docs/02-installation.md

@@ -1,89 +1,97 @@
-# Installation — Reference
-
-This is the reference page for installation: prerequisites, prebuilt-binary support matrix, verification commands, and upgrade paths.
-
-For the **user-friendly walkthrough** — per-IDE setup, agent-instructions installer, team server connection — see [`FULL-INSTALLATION-GUIDE.md`](../FULL-INSTALLATION-GUIDE.md) at the project root.
-
----
-
-## Prerequisites
-
-| Requirement | Version | Notes |
-|-------------|---------|-------|
-| Node.js | >= 18.0.0 | 18, 20, and 22 are tested |
-| npm | >= 9.0.0 | Ships with Node 18+ |
-| Git | any | Required only for `index_repo` (cloning remote repositories) |
-
----
-
-## Install commands
-
-```bash
-# Recommended: run via npx (no global install needed)
-npx purecontext-mcp@latest
-
-# Or install globally
-npm install -g purecontext-mcp@latest
-```
-
-The `@latest` tag is recommended in AI-client configurations so new versions are picked up without manual upgrade steps.
-
----
-
-## Prebuilt binary support matrix
-
-`better-sqlite3` is the only native dependency. Prebuilt binaries are bundled for:
-
-| Platform | Node 18 | Node 20 | Node 22 |
-|----------|:-------:|:-------:|:-------:|
-| Windows x64 | ✓ | ✓ | ✓ |
-| macOS x64 | ✓ | ✓ | ✓ |
-| macOS arm64 | ✓ | ✓ | ✓ |
-| Linux x64 | ✓ | ✓ | ✓ |
-| Linux arm64 | ✓ | ✓ | ✓ |
-
-When your platform matches a row above, `npm install` completes with zero native compilation. For unsupported combinations, `npm install` falls back to a source build, which requires Python 3.x, a C++ toolchain, and `node-gyp`.
-
----
-
-## Verification
-
-```bash
-purecontext-mcp --version
-purecontext-mcp config --check
-```
-
-`config --check` validates the install: confirms Node and SQLite versions, verifies all 34 grammar WASM files load, and reports the effective configuration.
-
----
-
-## Upgrade matrix
-
-| How you installed | Command to upgrade |
-|-------------------|--------------------|
-| Volta | `volta install purecontext-mcp` |
-| npm global | `npm install -g purecontext-mcp@latest` |
-| npx (cached) | `npx purecontext-mcp@latest` (forces a fresh fetch) |
-| Source / clone | `git pull && npm install && npm run build` |
-
-> `npm update -g` is not reliable for this package — use `npm install -g ...@latest`.
-
-**Index compatibility:** SQLite indexes are forward-compatible within a major version (`1.x` → `1.y` keeps existing indexes). Major upgrades (`1.x` → `2.0`) may require a re-index; the CLI warns when it detects an incompatible index.
-
----
-
-## Uninstall
-
-```bash
-npm uninstall -g purecontext-mcp
-rm -rf ~/.purecontext   # removes indexes, config, savings stats
-```
-
----
-
-## Related reference
-
-- [Configuration](04-configuration.md) — full `config.json` schema and environment variable overrides
-- [CLI Reference](05-cli-reference.md) — every command and flag
-- [Transport Modes](14-transport-modes.md) — stdio vs HTTP/SSE deployment
-- [Team Setup & Multi-Tenant](15-team-setup.md) — reference for shared-server config
+# Installation — Reference
+
+This is the reference page for installation: prerequisites, prebuilt-binary support matrix, verification commands, and upgrade paths.
+
+For the **user-friendly walkthrough** — per-IDE setup, agent-instructions installer, team server connection — see [`FULL-INSTALLATION-GUIDE.md`](../FULL-INSTALLATION-GUIDE.md) at the project root.
+
+---
+
+## Prerequisites
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | >= 18.0.0 | 18, 20, and 22 are tested |
+| npm | >= 9.0.0 | Ships with Node 18+ |
+| Git | any | Required only for `index_repo` (cloning remote repositories) |
+
+---
+
+## Install commands
+
+```bash
+# Recommended: run via npx (no global install needed)
+npx purecontext-mcp@latest
+
+# Or install globally
+npm install -g purecontext-mcp@latest
+```
+
+The `@latest` tag is recommended in AI-client configurations so new versions are picked up without manual upgrade steps.
+
+---
+
+## Prebuilt binary support matrix
+
+`better-sqlite3` is the only native dependency. Prebuilt binaries are bundled for:
+
+| Platform | Node 18 | Node 20 | Node 22 |
+|----------|:-------:|:-------:|:-------:|
+| Windows x64 | ✓ | ✓ | ✓ |
+| macOS x64 | ✓ | ✓ | ✓ |
+| macOS arm64 | ✓ | ✓ | ✓ |
+| Linux x64 | ✓ | ✓ | ✓ |
+| Linux arm64 | ✓ | ✓ | ✓ |
+
+When your platform matches a row above, `npm install` completes with zero native compilation. For unsupported combinations, `npm install` falls back to a source build, which requires Python 3.x, a C++ toolchain, and `node-gyp`.
+
+### Runs on any Node ≥ 18 (WASM fallback)
+
+The native binary above is an **optimization, not a requirement**. At runtime, if the native `better-sqlite3` addon can't be loaded — you're on a Node version without a matching prebuild (19, 21, 23, 24+), a per-project Node manager like Volta pins a different version than the one the binary was built for, or the build simply isn't present — PureContext automatically falls back to a pure-**WASM** SQLite engine (`@sqlite.org/sqlite-wasm`) that is ABI-independent.
+
+The fallback is full-featured (FTS5 search, transactions, the whole schema) — only somewhat slower on large indexes. Backend selection is automatic and logged: you'll see `SQLite backend: WASM (@sqlite.org/sqlite-wasm)`. Set `PCTX_SQLITE_BACKEND=wasm` to force it.
+
+Net effect: **PureContext works on any Node ≥ 18**, with or without a version manager. Below Node 18 it exits at startup with a clear message rather than a cryptic failure.
+
+---
+
+## Verification
+
+```bash
+purecontext-mcp --version
+purecontext-mcp config --check
+```
+
+`config --check` validates the install: confirms Node and SQLite versions, verifies all 34 grammar WASM files load, and reports the effective configuration.
+
+---
+
+## Upgrade matrix
+
+| How you installed | Command to upgrade |
+|-------------------|--------------------|
+| Volta | `volta install purecontext-mcp` |
+| npm global | `npm install -g purecontext-mcp@latest` |
+| npx (cached) | `npx purecontext-mcp@latest` (forces a fresh fetch) |
+| Source / clone | `git pull && npm install && npm run build` |
+
+> `npm update -g` is not reliable for this package — use `npm install -g ...@latest`.
+
+**Index compatibility:** SQLite indexes are forward-compatible within a major version (`1.x` → `1.y` keeps existing indexes). Major upgrades (`1.x` → `2.0`) may require a re-index; the CLI warns when it detects an incompatible index.
+
+---
+
+## Uninstall
+
+```bash
+npm uninstall -g purecontext-mcp
+rm -rf ~/.purecontext   # removes indexes, config, savings stats
+```
+
+---
+
+## Related reference
+
+- [Configuration](04-configuration.md) — full `config.json` schema and environment variable overrides
+- [CLI Reference](05-cli-reference.md) — every command and flag
+- [Transport Modes](14-transport-modes.md) — stdio vs HTTP/SSE deployment
+- [Team Setup & Multi-Tenant](15-team-setup.md) — reference for shared-server config

package/docs/03-quick-start.md

@@ -1,135 +1,138 @@
-# Quick Start
-
-
-## Step 1 — Connect to Claude Code
-
-```bash
-# Recommended: use npx (no global install needed, always up-to-date)
-claude mcp add purecontext-mcp -- npx purecontext-mcp
-
-# Or, if installed globally:
-claude mcp add purecontext-mcp purecontext-mcp
-```
-
-Verify the connection:
-
-```bash
-claude mcp list
-# purecontext-mcp   connected   npx purecontext-mcp
-```
-
-## Step 2 — Index your project
-
-In a Claude Code conversation, ask:
-
-> "Use index_folder to index /path/to/my-project."
-
-Or more naturally:
-
-> "Index this project so I can search its symbols."
-
-Claude will call `index_folder`. A typical response looks like:
-
-```json
-{
-  "repoId": "a1b2c3d4e5f60001",
-  "filesIndexed": 342,
-  "symbolsExtracted": 4821,
-  "durationMs": 1240,
-  "languages": ["typescript", "javascript"],
-  "adapters": ["vue", "nuxt"]
-}
-```
-
-Re-indexing is incremental — only files whose content has changed are re-parsed. You can call `index_folder` again at any time; it is fast on subsequent runs.
-
-## Step 3 — Explore the project structure
-
-```
-Get the repo outline for my project.
-```
-
-Claude calls `get_repo_outline`, which returns all files and their top-level symbols — a token-efficient project map.
-
-## Step 4 — Search for symbols
-
-```
-Search for functions named 'authenticate'.
-```
-
-Claude calls `search_symbols`:
-
-```json
-{
-  "symbols": [
-    {
-      "id": "8f3a2c1d0e4b5f9a",
-      "name": "authenticateUser",
-      "kind": "function",
-      "filePath": "src/auth/validator.ts",
-      "signature": "function authenticateUser(credentials: Credentials): Promise<User>",
-      "summary": "Validates user credentials and returns an authenticated User object."
-    }
-  ]
-}
-```
-
-Note: `search_symbols` returns signatures and summaries — **no source code**. This keeps the response tiny.
-
-## Step 5 — Retrieve source when you need it
-
-```
-Get the source for the authenticateUser symbol.
-```
-
-Claude calls `get_symbol_source` using the `id` from step 4 and gets back just those lines — not the whole file.
-
-## Example workflow
-
-```
-User: "Find the authentication logic in this project."
-
-Claude:
-1. search_symbols(query: "auth", kind: "function")
-   → Returns: authenticateUser, validateToken, hashPassword (3 matches, ~80 tokens)
-
-2. get_symbol_source(symbolId: "authenticateUser-id")
-   → Returns: 45 lines of source (~150 tokens)
-
-Total: ~230 tokens
-Without PureContext: read the 800-line auth file → ~2,000 tokens
-Savings: 88%
-```
-
-## What to try next
-
-| Task | Tool |
-|------|------|
-| See all symbols in a file | `get_file_outline` |
-| Find what a function imports | `get_context_bundle` |
-| Find what uses a function | `get_blast_radius` |
-| Find unused exports | `find_dead_code` |
-| Search by meaning, not name | `search_semantic` |
-| Text search (like grep) | `search_text` |
-
-## Connecting to a team server
-
-If your team runs a shared PureContext server:
-
-```bash
-claude mcp add purecontext-remote \
-  --transport http \
-  --url https://purecontext.mycompany.com/mcp/sse \
-  --header "Authorization: Bearer pctx_yourpersonalkey"
-```
-
-See [Team Setup](15-team-setup.md) for full instructions.
-
-## Generating a config file
-
-```bash
-purecontext-mcp config --init
-# Creates ~/.purecontext/config.json with defaults and comments
-```
-
-See [Configuration](04-configuration.md) for all available options.
+# Quick Start
+
+
+## Step 1 — Connect to Claude Code
+
+```bash
+# Recommended: registers the server (pinned to your global Node) + adds workflow rules
+npx purecontext-mcp install claude
+
+# Or register the server manually with npx:
+claude mcp add purecontext-mcp -- npx purecontext-mcp
+
+# Or, if installed globally:
+claude mcp add purecontext-mcp purecontext-mcp
+```
+
+Verify the connection:
+
+```bash
+claude mcp list
+# purecontext-mcp   connected   npx purecontext-mcp
+```
+
+## Step 2 — Index your project
+
+In a Claude Code conversation, ask:
+
+> "Use index_folder to index /path/to/my-project."
+
+Or more naturally:
+
+> "Index this project so I can search its symbols."
+
+Claude will call `index_folder`. A typical response looks like:
+
+```json
+{
+  "repoId": "a1b2c3d4e5f60001",
+  "filesIndexed": 342,
+  "symbolsExtracted": 4821,
+  "durationMs": 1240,
+  "languages": ["typescript", "javascript"],
+  "adapters": ["vue", "nuxt"]
+}
+```
+
+Re-indexing is incremental — only files whose content has changed are re-parsed. You can call `index_folder` again at any time; it is fast on subsequent runs.
+
+## Step 3 — Explore the project structure
+
+```
+Get the repo outline for my project.
+```
+
+Claude calls `get_repo_outline`, which returns all files and their top-level symbols — a token-efficient project map.
+
+## Step 4 — Search for symbols
+
+```
+Search for functions named 'authenticate'.
+```
+
+Claude calls `search_symbols`:
+
+```json
+{
+  "symbols": [
+    {
+      "id": "8f3a2c1d0e4b5f9a",
+      "name": "authenticateUser",
+      "kind": "function",
+      "filePath": "src/auth/validator.ts",
+      "signature": "function authenticateUser(credentials: Credentials): Promise<User>",
+      "summary": "Validates user credentials and returns an authenticated User object."
+    }
+  ]
+}
+```
+
+Note: `search_symbols` returns signatures and summaries — **no source code**. This keeps the response tiny.
+
+## Step 5 — Retrieve source when you need it
+
+```
+Get the source for the authenticateUser symbol.
+```
+
+Claude calls `get_symbol_source` using the `id` from step 4 and gets back just those lines — not the whole file.
+
+## Example workflow
+
+```
+User: "Find the authentication logic in this project."
+
+Claude:
+1. search_symbols(query: "auth", kind: "function")
+   → Returns: authenticateUser, validateToken, hashPassword (3 matches, ~80 tokens)
+
+2. get_symbol_source(symbolId: "authenticateUser-id")
+   → Returns: 45 lines of source (~150 tokens)
+
+Total: ~230 tokens
+Without PureContext: read the 800-line auth file → ~2,000 tokens
+Savings: 88%
+```
+
+## What to try next
+
+| Task | Tool |
+|------|------|
+| See all symbols in a file | `get_file_outline` |
+| Find what a function imports | `get_context_bundle` |
+| Find what uses a function | `get_blast_radius` |
+| Find unused exports | `find_dead_code` |
+| Search by meaning, not name | `search_semantic` |
+| Text search (like grep) | `search_text` |
+
+## Connecting to a team server
+
+If your team runs a shared PureContext server:
+
+```bash
+claude mcp add purecontext-remote \
+  --transport http \
+  --url https://purecontext.mycompany.com/mcp/sse \
+  --header "Authorization: Bearer pctx_yourpersonalkey"
+```
+
+See [Team Setup](15-team-setup.md) for full instructions.
+
+## Generating a config file
+
+```bash
+purecontext-mcp config --init
+# Creates ~/.purecontext/config.json with defaults and comments
+```
+
+See [Configuration](04-configuration.md) for all available options.