purecontext-mcp 1.5.2 → 1.11.0

package/docs/14-transport-modes.md

@@ -1,167 +1,170 @@
-# Transport Modes
-
-
-PureContext supports two transport modes: **stdio** (local, default) and **HTTP/SSE** (team/cloud).
-
-## stdio transport (default)
-
-The standard transport for Claude Code and other MCP-native clients.
-
-```bash
-purecontext-mcp
-```
-
-Claude Code spawns `purecontext-mcp` as a child process and communicates over stdin/stdout using the JSON-RPC MCP protocol. No network, no authentication required.
-
-**Claude Code setup:**
-
-```bash
-# Using npx (recommended)
-claude mcp add purecontext-mcp -- npx purecontext-mcp
-
-# Using global install
-claude mcp add purecontext-mcp purecontext-mcp
-```
-
-**Best for:** Individual developers, local development, any situation where security and simplicity matter more than sharing.
-
-## HTTP / SSE transport
-
-For browser-based clients, remote development, or multi-client setups.
-
-```bash
-purecontext-mcp --transport http --port 3000
-```
-
-Or via `config.json`:
-
-```json
-{
-  "transport": "http",
-  "http": {
-    "port": 3000,
-    "host": "127.0.0.1",
-    "corsOrigins": ["http://localhost:*"]
-  }
-}
-```
-
-**HTTP endpoints:**
-
-| Endpoint | Description |
-|----------|-------------|
-| `GET /health` | Server health check (always public) |
-| `POST /mcp/sse` | MCP Streamable HTTP endpoint |
-| `GET /` | Web UI (served when UI is built) |
-| `GET /admin/*` | Admin API (requires admin key) |
-
-**Connect Claude Code to an HTTP server:**
-
-```json
-// ~/.claude/claude_desktop_config.json
-{
-  "mcpServers": {
-    "purecontext": {
-      "transport": "http",
-      "url": "http://localhost:3000/mcp/sse"
-    }
-  }
-}
-```
-
-Or via CLI:
-
-```bash
-claude mcp add purecontext-remote \
-  --transport http \
-  --url https://purecontext.mycompany.com/mcp/sse \
-  --header "Authorization: Bearer pctx_yourkey"
-```
-
-**Best for:** Team deployments, shared index, CI pipelines, Web UI access.
-
-## Both transports simultaneously (development)
-
-Run stdio and HTTP at the same time — useful during development to test the HTTP API while still using Claude Code via stdio:
-
-```bash
-purecontext-mcp --transport both
-```
-
-## Choosing a transport
-
-| Scenario | Recommended transport |
-|----------|-----------------------|
-| Solo developer, local project | `stdio` |
-| Team with shared codebase | `http` (server) |
-| CI pipeline | `http` or `stdio` with cached index |
-| Web UI access | `http` |
-| Testing both simultaneously | `both` |
-
-## Authentication in HTTP mode
-
-When binding to a non-loopback address, always enable authentication:
-
-```json
-{
-  "http": {
-    "host": "0.0.0.0",
-    "auth": {
-      "enabled": true,
-      "token": "${PURECONTEXT_API_TOKEN}"
-    }
-  }
-}
-```
-
-If `token` is empty and `enabled` is `true`, a random 32-byte hex token is generated at startup and printed to stderr. Save it immediately — it is not persisted to disk.
-
-All MCP requests must include:
-
-```
-Authorization: Bearer <token>
-```
-
-A warning is logged at startup if the server is bound to a non-loopback address with authentication disabled.
-
-## TLS / HTTPS
-
-PureContext does not terminate TLS itself. Put it behind a reverse proxy for HTTPS in production.
-
-**nginx example:**
-
-```nginx
-server {
-    listen 443 ssl;
-    server_name purecontext.mycompany.com;
-
-    ssl_certificate     /etc/letsencrypt/live/purecontext.mycompany.com/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/purecontext.mycompany.com/privkey.pem;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection keep-alive;
-        proxy_set_header Host $host;
-        # Disable buffering for SSE
-        proxy_buffering off;
-        proxy_cache off;
-        proxy_read_timeout 3600s;
-    }
-}
-```
-
-**Caddy example:**
-
-```
-purecontext.mycompany.com {
-    reverse_proxy localhost:3000 {
-        flush_interval -1
-    }
-}
-```
-
-## SSE keepalive
-
-The HTTP server sends a `: ping` comment over the SSE stream every 30 seconds to keep connections alive through proxies and load balancers. If your proxy has a shorter idle timeout than 30 seconds, increase it (e.g., `proxy_read_timeout 3600s` in nginx).
+# Transport Modes
+
+
+PureContext supports two transport modes: **stdio** (local, default) and **HTTP/SSE** (team/cloud).
+
+## stdio transport (default)
+
+The standard transport for Claude Code and other MCP-native clients.
+
+```bash
+purecontext-mcp
+```
+
+Claude Code spawns `purecontext-mcp` as a child process and communicates over stdin/stdout using the JSON-RPC MCP protocol. No network, no authentication required.
+
+**Claude Code setup:**
+
+```bash
+# Recommended: installer registers the server (pinned to your global Node) + rules
+npx purecontext-mcp install claude
+
+# Or register manually with npx
+claude mcp add purecontext-mcp -- npx purecontext-mcp
+
+# Using global install
+claude mcp add purecontext-mcp purecontext-mcp
+```
+
+**Best for:** Individual developers, local development, any situation where security and simplicity matter more than sharing.
+
+## HTTP / SSE transport
+
+For browser-based clients, remote development, or multi-client setups.
+
+```bash
+purecontext-mcp --transport http --port 3000
+```
+
+Or via `config.json`:
+
+```json
+{
+  "transport": "http",
+  "http": {
+    "port": 3000,
+    "host": "127.0.0.1",
+    "corsOrigins": ["http://localhost:*"]
+  }
+}
+```
+
+**HTTP endpoints:**
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Server health check (always public) |
+| `POST /mcp/sse` | MCP Streamable HTTP endpoint |
+| `GET /` | Web UI (served when UI is built) |
+| `GET /admin/*` | Admin API (requires admin key) |
+
+**Connect Claude Code to an HTTP server:**
+
+```json
+// ~/.claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "purecontext": {
+      "transport": "http",
+      "url": "http://localhost:3000/mcp/sse"
+    }
+  }
+}
+```
+
+Or via CLI:
+
+```bash
+claude mcp add purecontext-remote \
+  --transport http \
+  --url https://purecontext.mycompany.com/mcp/sse \
+  --header "Authorization: Bearer pctx_yourkey"
+```
+
+**Best for:** Team deployments, shared index, CI pipelines, Web UI access.
+
+## Both transports simultaneously (development)
+
+Run stdio and HTTP at the same time — useful during development to test the HTTP API while still using Claude Code via stdio:
+
+```bash
+purecontext-mcp --transport both
+```
+
+## Choosing a transport
+
+| Scenario | Recommended transport |
+|----------|-----------------------|
+| Solo developer, local project | `stdio` |
+| Team with shared codebase | `http` (server) |
+| CI pipeline | `http` or `stdio` with cached index |
+| Web UI access | `http` |
+| Testing both simultaneously | `both` |
+
+## Authentication in HTTP mode
+
+When binding to a non-loopback address, always enable authentication:
+
+```json
+{
+  "http": {
+    "host": "0.0.0.0",
+    "auth": {
+      "enabled": true,
+      "token": "${PURECONTEXT_API_TOKEN}"
+    }
+  }
+}
+```
+
+If `token` is empty and `enabled` is `true`, a random 32-byte hex token is generated at startup and printed to stderr. Save it immediately — it is not persisted to disk.
+
+All MCP requests must include:
+
+```
+Authorization: Bearer <token>
+```
+
+A warning is logged at startup if the server is bound to a non-loopback address with authentication disabled.
+
+## TLS / HTTPS
+
+PureContext does not terminate TLS itself. Put it behind a reverse proxy for HTTPS in production.
+
+**nginx example:**
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name purecontext.mycompany.com;
+
+    ssl_certificate     /etc/letsencrypt/live/purecontext.mycompany.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/purecontext.mycompany.com/privkey.pem;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection keep-alive;
+        proxy_set_header Host $host;
+        # Disable buffering for SSE
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 3600s;
+    }
+}
+```
+
+**Caddy example:**
+
+```
+purecontext.mycompany.com {
+    reverse_proxy localhost:3000 {
+        flush_interval -1
+    }
+}
+```
+
+## SSE keepalive
+
+The HTTP server sends a `: ping` comment over the SSE stream every 30 seconds to keep connections alive through proxies and load balancers. If your proxy has a shorter idle timeout than 30 seconds, increase it (e.g., `proxy_read_timeout 3600s` in nginx).

package/docs/18-git-history.md

@@ -43,6 +43,8 @@ This means you can ask "which commits touched `authenticateUser`?" and get an an
 | `git.maxCommits` | `500` | Maximum commits to walk back from HEAD |
 | `git.includeMergeCommits` | `false` | Include merge commits (usually noise) |
 | `git.branches` | `["main"]` | Branches to index history from |
+| `git.coChangeDepth` | `300` | Commits captured at the repo root for co-change analysis (`get_co_change`, `get_symbol_risk`, bundle `historicalNeighbors`). `0` disables capture entirely. |
+| `git.megaCommitThreshold` | `30` | Commits touching more files than this are excluded / down-weighted as mega-commits (reformats, lockfile sweeps) |
 
 ---
 
@@ -120,6 +122,45 @@ File and symbol churn metrics — how often things change.
 
 ---
 
+## `get_co_change` — temporal coupling
+
+Files that historically change together with a target file or symbol. This is the signal a static dependency graph cannot derive: a route and its test, or a feature flag and the code it gates, that move together without importing each other.
+
+Capture is a single repo-level `git log --no-merges --name-only -n N` at index time (controlled by `git.coChangeDepth`), stored in a dedicated `commit_files` table — separate from the per-file `git_metadata` history, whose last-N-per-file window is too shallow for co-change.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `filePath` | `string` | — | Target file (provide this **or** `symbolId`) |
+| `symbolId` | `string` | — | Target symbol — resolved to its file (git is file-granular) |
+| `minSupport` | `number` | `2` | Drop partners with fewer than N shared commits |
+| `dayWindow` | `number` | — | Look back N days (default: entire captured window) |
+| `topN` | `number` | `20` | Max partners to return |
+
+**Response:** ranked `partners` with `support` (shared commits), `confidence` (directional A→B probability), `lift` (association strength), and `coChangeDate`. Mega-commits are filtered and down-weighted; `signalQuality: "low"` flags shallow/sparse histories.
+
+**Use cases:**
+- "If I touch this file, what else usually changes with it?"
+- "What's the test or config that moves with this code but doesn't import it?"
+
+---
+
+## `get_symbol_risk` — composite change risk
+
+A single, explainable "how risky is it to change this symbol?" verdict. Blends churn (90 d), centrality (afferent coupling + reverse blast radius), cyclomatic complexity, test-coverage gap, and co-change spread — each normalized **repo-relative** (midrank percentile) so scores compare within a repo and aren't dominated by absolute size.
+
+**Parameters:** `{ repoId, symbolId }`
+
+**Response:** `{ riskScore (0–100), band: "low" | "review" | "high", factors: { churn, centrality, complexity, testGap, coChange }, reasons: string[], signalQuality }`. Factor weights are tunable via `risk.weights.*` (see [Configuration](04-configuration.md)).
+
+It always returns `factors` (raw + normalized) and human-readable `reasons[]` — never a black-box number. **Code-centered only — no author, ownership, or productivity metrics.**
+
+**Guardrail:** before broad or automated edits to a `high` symbol, inspect its callers (`get_blast_radius`) and co-changers (`get_co_change`) first. `search_symbols` and `get_symbol_source` accept `includeRisk: true` to attach a compact `{ band, riskScore }` inline; `get_context_bundle` returns `historicalNeighbors` (co-changing files not reachable via imports) when co-change data exists.
+
+---
+
 ## PR / diff analysis
 
 Analyze what a branch or commit range changes at the symbol level:
@@ -155,3 +196,5 @@ When git integration is enabled:
 - **Merge commits:** excluded by default to avoid noise from merge-only diffs
 - **Rebased history:** rebase changes commit hashes — a re-index is needed to pick up rebased history accurately
 - Git submodules are not indexed
+- **Co-change rename continuity:** the repo-level capture does not follow renames, so a file renamed mid-history splits its co-change signal until re-indexed
+- **Squash-merge monorepos:** squashed PRs collapse many logical changes into one commit, which can inflate co-change; `git.megaCommitThreshold` mitigates this and `signalQuality: "low"` flags weak signal

package/docs/23-performance.md

@@ -1,121 +1,123 @@
-# Performance & Scalability
-
-
-PureContext is designed to handle enterprise-scale repos (10k–50k files) using a worker thread pool for parallel tree-sitter parsing.
-
----
-
-## Indexing speed
-
-Typical performance on a 4-core machine:
-
-| Repo size | First index | Incremental re-index |
-|-----------|-------------|----------------------|
-| 500 files | ~2 seconds | < 100ms |
-| 5,000 files | ~15 seconds | < 1 second |
-| 20,000 files | ~60 seconds | 1–3 seconds |
-| 50,000 files | ~3 minutes | 2–10 seconds |
-
-These numbers assume no AI summarization or semantic indexing. Both add API round-trip time.
-
----
-
-## Worker thread pool
-
-The bottleneck in sequential indexing is tree-sitter WASM parsing — each WASM instance is single-threaded. The worker thread pool parallelizes parsing across CPU cores.
-
-```
-                Main thread
-                     │
-        ┌────────────┼────────────┐
-        ▼            ▼            ▼
-   Worker 1      Worker 2     Worker 3
-   (TypeScript)  (Python)     (Go)
-   parse + extract  parse + extract  parse + extract
-        │            │            │
-        └────────────┴────────────┘
-                     │
-                Main thread
-             (SQLite writes)
-```
-
-Each worker loads its own WASM grammar instances. File batches are distributed across workers by the main thread. SQLite writes are serialized on the main thread (better-sqlite3 is synchronous).
-
-### Configuring worker threads
-
-```json
-{
-  "workerThreads": 4   // default: os.cpus().length - 1, minimum 1
-}
-```
-
-Increase for CPU-bound workloads on machines with many cores. Do not exceed `os.cpus().length - 1` — you want to leave one core for the main thread and OS.
-
----
-
-## Memory usage
-
-| Component | Memory |
-|-----------|--------|
-| WASM grammars (per worker) | ~20–30 MB per grammar loaded |
-| In-memory symbol cache (during indexing) | ~100 MB for 10k symbols |
-| SQLite WAL mode (at rest) | ~50 MB |
-| HNSW vector index (if enabled) | ~100 bytes per embedding dimension per symbol |
-
-**Typical peak during indexing:** 200–500 MB for a 10k-file repo. Returns to ~50 MB at rest.
-
-Workers are spawned once and reused for the lifetime of the server — no spawn/teardown overhead per index run.
-
----
-
-## Incremental re-indexing
-
-The content hash cache makes re-indexing very fast:
-
-1. Each file's SHA-256 hash is stored in the `files` table after indexing
-2. On re-index, the hash is recomputed and compared
-3. Only files with a changed hash are re-parsed
-4. Symbols for unchanged files are retained as-is
-
-A typical `git pull` touches 10–50 files — re-index completes in milliseconds.
-
-To force a full re-index (bypass the hash cache):
-
-```
-Use invalidate_cache tool, then index_folder again.
-```
-
-Or call `index_folder` with `force: true`.
-
----
-
-## Large repo tuning
-
-For repos with > 10,000 files:
-
-| Setting | Recommendation |
-|---------|---------------|
-| `workerThreads` | Set to `os.cpus().length - 1` |
-| `watchDebounceMs` | Increase to `5000` if many files change at once (e.g., code generation) |
-| `excludePatterns` | Add patterns for generated files, test fixtures with large data files |
-| `maxFileSizeBytes` | Keep at 1 MB or lower — parsing multi-MB files is slow and rarely useful |
-| `fileLimit` | Set to `0` (unlimited) if you need the full repo indexed |
-
----
-
-## SQLite performance
-
-SQLite in **WAL (Write-Ahead Logging) mode** provides:
-- Concurrent reads without blocking writes
-- Fast writes (no fsync on every write in WAL mode)
-- Crash safety (WAL journal ensures atomicity)
-
-Query performance:
-- `search_symbols` with FTS5: < 5ms for 100k symbols
-- `get_symbol_source`: < 1ms (single row lookup by primary key)
-- `get_blast_radius` (depth 5): 5–20ms depending on graph density
-- `get_context_bundle` (depth 3): 3–15ms
-
-No tuning is needed for the SQLite layer up to ~500k symbols. At very large scale, consider periodic `VACUUM` to reclaim space from deleted symbols.
-
-
+# Performance & Scalability
+
+
+PureContext is designed to handle enterprise-scale repos (10k–50k files) using a worker thread pool for parallel tree-sitter parsing.
+
+---
+
+## Indexing speed
+
+Typical performance on a 4-core machine:
+
+| Repo size | First index | Incremental re-index |
+|-----------|-------------|----------------------|
+| 500 files | ~2 seconds | < 100ms |
+| 5,000 files | ~15 seconds | < 1 second |
+| 20,000 files | ~60 seconds | 1–3 seconds |
+| 50,000 files | ~3 minutes | 2–10 seconds |
+
+These numbers assume no AI summarization or semantic indexing. Both add API round-trip time.
+
+---
+
+## Worker thread pool
+
+The bottleneck in sequential indexing is tree-sitter WASM parsing — each WASM instance is single-threaded. The worker thread pool parallelizes parsing across CPU cores.
+
+```
+                Main thread
+                     │
+        ┌────────────┼────────────┐
+        ▼            ▼            ▼
+   Worker 1      Worker 2     Worker 3
+   (TypeScript)  (Python)     (Go)
+   parse + extract  parse + extract  parse + extract
+        │            │            │
+        └────────────┴────────────┘
+                     │
+                Main thread
+             (SQLite writes)
+```
+
+Each worker loads its own WASM grammar instances. File batches are distributed across workers by the main thread. SQLite writes are serialized on the main thread (better-sqlite3 is synchronous).
+
+> **SQLite backend note:** the numbers here assume the native `better-sqlite3` engine (Node 18/20/22). On other Node versions PureContext falls back to a WASM SQLite engine (see [Installation](02-installation.md)); it is functionally identical (FTS5 included) but slower on write-heavy indexing, because the WASM database is held in memory and serialized to disk on flush rather than written natively in place. Indexing throughput is the main thing affected; query latency is much closer.
+
+### Configuring worker threads
+
+```json
+{
+  "workerThreads": 4   // default: os.cpus().length - 1, minimum 1
+}
+```
+
+Increase for CPU-bound workloads on machines with many cores. Do not exceed `os.cpus().length - 1` — you want to leave one core for the main thread and OS.
+
+---
+
+## Memory usage
+
+| Component | Memory |
+|-----------|--------|
+| WASM grammars (per worker) | ~20–30 MB per grammar loaded |
+| In-memory symbol cache (during indexing) | ~100 MB for 10k symbols |
+| SQLite WAL mode (at rest) | ~50 MB |
+| HNSW vector index (if enabled) | ~100 bytes per embedding dimension per symbol |
+
+**Typical peak during indexing:** 200–500 MB for a 10k-file repo. Returns to ~50 MB at rest.
+
+Workers are spawned once and reused for the lifetime of the server — no spawn/teardown overhead per index run.
+
+---
+
+## Incremental re-indexing
+
+The content hash cache makes re-indexing very fast:
+
+1. Each file's SHA-256 hash is stored in the `files` table after indexing
+2. On re-index, the hash is recomputed and compared
+3. Only files with a changed hash are re-parsed
+4. Symbols for unchanged files are retained as-is
+
+A typical `git pull` touches 10–50 files — re-index completes in milliseconds.
+
+To force a full re-index (bypass the hash cache):
+
+```
+Use invalidate_cache tool, then index_folder again.
+```
+
+Or call `index_folder` with `force: true`.
+
+---
+
+## Large repo tuning
+
+For repos with > 10,000 files:
+
+| Setting | Recommendation |
+|---------|---------------|
+| `workerThreads` | Set to `os.cpus().length - 1` |
+| `watchDebounceMs` | Increase to `5000` if many files change at once (e.g., code generation) |
+| `excludePatterns` | Add patterns for generated files, test fixtures with large data files |
+| `maxFileSizeBytes` | Keep at 1 MB or lower — parsing multi-MB files is slow and rarely useful |
+| `fileLimit` | Set to `0` (unlimited) if you need the full repo indexed |
+
+---
+
+## SQLite performance
+
+SQLite in **WAL (Write-Ahead Logging) mode** provides:
+- Concurrent reads without blocking writes
+- Fast writes (no fsync on every write in WAL mode)
+- Crash safety (WAL journal ensures atomicity)
+
+Query performance:
+- `search_symbols` with FTS5: < 5ms for 100k symbols
+- `get_symbol_source`: < 1ms (single row lookup by primary key)
+- `get_blast_radius` (depth 5): 5–20ms depending on graph density
+- `get_context_bundle` (depth 3): 3–15ms
+
+No tuning is needed for the SQLite layer up to ~500k symbols. At very large scale, consider periodic `VACUUM` to reclaim space from deleted symbols.
+
+