purecontext-mcp 1.1.0 → 1.1.2

package/docs/15-team-setup.md

@@ -0,0 +1,251 @@
+# Team Setup & Multi-Tenant
+
+
+Run PureContext as a shared server so your whole team queries the same index — no per-developer re-indexing.
+
+---
+
+## Overview
+
+```
+Local mode:                        Server mode (shared):
+  Claude Code (each dev)             Claude Code (each dev)
+      ↓ stdio                            ↓ HTTP + API key
+  PureContext (local)                PureContext (shared server)
+      ↓                                  ↓
+  Local SQLite index             Shared SQLite index(es)
+```
+
+**Why a shared server?** Each developer re-indexes the same codebase independently in local mode. A shared server indexes once and serves all team members — consistent results and no redundant work.
+
+---
+
+## Step 1 — Deploy the server
+
+### Docker (recommended)
+
+```bash
+mkdir -p ./purecontext-data
+
+docker run -d \
+  --name purecontext \
+  -p 3000:3000 \
+  -v "$(pwd)/purecontext-data:/data" \
+  -e PCTX_ADMIN_KEY="$(openssl rand -hex 32)" \
+  --restart unless-stopped \
+  purecontext/purecontext-mcp:latest
+```
+
+Note your `PCTX_ADMIN_KEY` — you need it to manage workspaces and keys.
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+services:
+  purecontext:
+    image: purecontext/purecontext-mcp:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./data:/data
+    environment:
+      PCTX_ADMIN_KEY: "change-me-before-deploying"
+    restart: unless-stopped
+```
+
+```bash
+docker compose up -d
+```
+
+### npm (no Docker)
+
+```bash
+npm install -g purecontext-mcp
+PCTX_ADMIN_KEY=your-secret purecontext-mcp --server --host 0.0.0.0 --port 3000
+```
+
+### Verify the server is running
+
+```bash
+curl http://localhost:3000/health
+# {"status":"ok","version":"1.x.x","repoCount":0}
+```
+
+---
+
+## Step 2 — Create a workspace
+
+A workspace is the unit of isolation — one team = one workspace. All repos and API keys belong to a workspace.
+
+```bash
+export ADMIN_KEY="your-pctx-admin-key"
+export SERVER="http://localhost:3000"
+
+curl -s -X POST "$SERVER/admin/workspaces" \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-team", "plan": "team"}' | jq .
+```
+
+Response:
+
+```json
+{"id": "ws_abc123", "name": "my-team", "plan": "team", "created_at": 1714000000}
+```
+
+Save the `id` — you'll use it when creating API keys.
+
+---
+
+## Step 3 — Create API keys
+
+Each developer gets their own API key. Keys are shown once on creation and never again.
+
+```bash
+curl -s -X POST "$SERVER/admin/keys" \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "label": "alice-macbook",
+    "permissions": ["read", "write"],
+    "workspace_id": "ws_abc123"
+  }' | jq .
+```
+
+**Response (key shown only once):**
+
+```json
+{
+  "key": "pctx_00000000_..._1234",
+  "label": "alice-macbook",
+  "permissions": ["read", "write"],
+  "key_hash_prefix": "deadbeef"
+}
+```
+
+### Permission levels
+
+| Permission | Allowed operations |
+|------------|-------------------|
+| `read` | Search symbols, get outlines, get source |
+| `write` | + `index_folder`, `index_repo` |
+| `admin` | + Manage keys and workspaces |
+
+For AI agents that only query (not index), use `read` permission. For CI pipelines that re-index on push, use `write`.
+
+---
+
+## Step 4 — Index the shared codebase
+
+Connect Claude Code (step 5) and ask it to index, or call the API directly:
+
+```bash
+curl -s -X POST "$SERVER/mcp/sse" \
+  -H "Authorization: Bearer pctx_yourwritekey" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "params": {"name": "index_folder", "arguments": {"path": "/path/to/repo"}},
+    "id": 1
+  }'
+```
+
+---
+
+## Step 5 — Connect each developer
+
+Each developer runs this once:
+
+```bash
+claude mcp add purecontext-remote \
+  --transport http \
+  --url https://purecontext.mycompany.com/mcp/sse \
+  --header "Authorization: Bearer pctx_yourpersonalkey"
+```
+
+After adding, verify in Claude Code:
+
+```
+/mcp
+# Should show purecontext-remote as connected
+
+List my indexed repositories using list_repos
+```
+
+---
+
+## Step 6 — Manage keys over time
+
+```bash
+# List all keys (shows label, prefix, permissions — never the raw key)
+curl -s "$SERVER/admin/keys" -H "Authorization: Bearer $ADMIN_KEY" | jq .
+
+# Revoke a key (e.g., when someone leaves the team)
+curl -s -X DELETE "$SERVER/admin/keys/deadbeef" \
+  -H "Authorization: Bearer $ADMIN_KEY"
+
+# Check key usage stats
+curl -s "$SERVER/admin/keys/deadbeef/usage" \
+  -H "Authorization: Bearer $ADMIN_KEY" | jq .
+```
+
+---
+
+## Rate limiting
+
+HTTP mode uses a token-bucket algorithm to prevent any single client from overwhelming the server:
+
+- Each key gets a bucket with capacity `rateLimit.maxTokens` (default: 100)
+- Tokens refill at `rateLimit.refillRate` per second (default: 10)
+- Expensive tools (e.g., `index_folder`) cost more tokens
+
+When rate limited, responses return `429 Too Many Requests` with a `Retry-After` header.
+
+Configure per-tool costs in `config.json`:
+
+```json
+{
+  "rateLimit": {
+    "enabled": true,
+    "maxTokens": 200,
+    "refillRate": 20,
+    "perToolLimits": {
+      "index_folder": 10,
+      "search_symbols": 1
+    }
+  }
+}
+```
+
+---
+
+## Admin API reference
+
+All endpoints require `Authorization: Bearer <PCTX_ADMIN_KEY>`.
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/admin/workspaces` | `POST` | Create workspace |
+| `/admin/workspaces` | `GET` | List workspaces |
+| `/admin/workspaces/:id` | `DELETE` | Delete workspace and all data |
+| `/admin/keys` | `POST` | Create API key |
+| `/admin/keys` | `GET` | List keys |
+| `/admin/keys/:prefix` | `DELETE` | Revoke key |
+| `/admin/keys/:prefix/usage` | `GET` | Key usage stats |
+| `/admin/stats` | `GET` | Server-wide statistics |
+
+---
+
+## Production checklist
+
+- [ ] `PCTX_ADMIN_KEY` is a long random secret (≥ 32 hex chars), set via env var only — never in a committed config file
+- [ ] Server is behind a reverse proxy (nginx, Caddy) with TLS
+- [ ] Port 3000 is not directly exposed to the internet (terminate TLS at the proxy)
+- [ ] `/data` volume is on a backed-up disk
+- [ ] `restart: unless-stopped` is set in docker-compose
+- [ ] Developers have `read` permission only unless they need to re-index
+- [ ] Admin key is rotated if ever exposed
+
+See [Docker Deployment](16-docker.md) for full reverse proxy examples.

package/docs/16-docker.md

@@ -0,0 +1,186 @@
+# Docker Deployment
+
+
+---
+
+## Quick start
+
+```bash
+docker run -d \
+  --name purecontext \
+  -p 3000:3000 \
+  -v /path/to/data:/data \
+  -e PCTX_ADMIN_KEY="$(openssl rand -hex 32)" \
+  --restart unless-stopped \
+  purecontext/purecontext-mcp:latest
+```
+
+Verify:
+
+```bash
+curl http://localhost:3000/health
+# {"status":"ok","version":"1.x.x","repoCount":0}
+```
+
+---
+
+## Docker Compose (recommended)
+
+The `docker-compose.yml` in the project root is ready to use:
+
+```yaml
+version: '3.8'
+services:
+  purecontext:
+    image: purecontext/purecontext-mcp:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./data:/data
+    environment:
+      PCTX_ADMIN_KEY: "${PCTX_ADMIN_KEY}"
+      PCTX_PORT: "3000"
+      PCTX_HOST: "0.0.0.0"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+```bash
+export PCTX_ADMIN_KEY="$(openssl rand -hex 32)"
+docker compose up -d
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PCTX_ADMIN_KEY` | *(required)* | Admin key for `/admin/*` endpoints. Set via environment, never in config files. |
+| `PCTX_DATA_DIR` | `/data` | Data directory inside container — mount a volume here. |
+| `PCTX_PORT` | `3000` | HTTP port. |
+| `PCTX_HOST` | `0.0.0.0` | Bind address. |
+| `PCTX_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error`. |
+| `ANTHROPIC_API_KEY` | — | For AI summarization (Anthropic provider). |
+| `OPENAI_API_KEY` | — | For AI summarization or semantic search (OpenAI). |
+| `GEMINI_API_KEY` | — | For AI summarization (Google Gemini). |
+
+---
+
+## Volume mounts
+
+| Container path | Purpose |
+|---------------|---------|
+| `/data` | SQLite index databases, auth database, config. **Must be a persistent volume.** |
+
+Without a volume mount, all indexes and API keys are lost when the container restarts.
+
+Optional: mount local repo directories for faster indexing (avoids git clone):
+
+```yaml
+volumes:
+  - ./data:/data
+  - /home/user/projects:/projects:ro   # read-only, for indexing
+```
+
+Then call `index_folder` with `/projects/my-repo` as the path.
+
+---
+
+## Updating
+
+```bash
+docker compose pull
+docker compose up -d --force-recreate
+```
+
+The `/data` volume is unaffected. Index files are forward-compatible within a major version.
+
+---
+
+## Health check
+
+The Docker image includes a built-in health check:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
+```
+
+Check status:
+
+```bash
+docker inspect --format='{{.State.Health.Status}}' purecontext
+# healthy
+```
+
+---
+
+## Resource requirements
+
+| Repo size | RAM (at rest) | RAM (during index) | CPU |
+|-----------|---------------|--------------------|-----|
+| < 1k files | ~100 MB | ~200 MB | any |
+| 1k–10k files | ~200 MB | ~500 MB | 2+ cores recommended |
+| 10k–50k files | ~500 MB | ~1 GB | 4+ cores recommended |
+
+SQLite uses WAL mode — reads don't block writes, no special IO requirements.
+
+---
+
+## Reverse proxy (TLS termination)
+
+### nginx
+
+```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;
+        proxy_set_header X-Real-IP $remote_addr;
+        # Required for SSE: disable buffering
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 3600s;
+    }
+}
+```
+
+### Caddy
+
+```
+purecontext.mycompany.com {
+    reverse_proxy localhost:3000 {
+        flush_interval -1   # disable buffering for SSE
+    }
+}
+```
+
+Caddy handles TLS automatically via Let's Encrypt.
+
+---
+
+## Server logs
+
+```bash
+# Stream logs
+docker logs -f purecontext
+
+# Last 100 lines
+docker logs --tail 100 purecontext
+```
+
+Log format: structured JSON lines when `PCTX_LOG_LEVEL=info` or higher. Each line includes timestamp, level, tool name (for MCP calls), repoId, and duration.

package/docs/17-web-ui.md

@@ -0,0 +1,157 @@
+# Web UI
+
+
+The Web UI provides a visual interface for exploring indexed codebases. It is served by the same process as the MCP server when HTTP transport is active.
+
+---
+
+## Accessing the Web UI
+
+The Web UI is available at `http://localhost:3000` (or your server URL) when running in HTTP mode:
+
+```bash
+purecontext-mcp --transport http --port 3000
+```
+
+Then open `http://localhost:3000` in a browser.
+
+### Building the UI
+
+The UI is pre-built in the npm package. For development or rebuilding from source:
+
+```bash
+npm run build:ui   # build only the UI
+npm run build      # build everything
+npm run dev        # watch mode: TypeScript + Vite dev server with hot reload
+```
+
+---
+
+## Repository browser
+
+- List all indexed repositories with symbol counts, file counts, and language breakdown
+- Collapsible file tree with file type icons
+- Click any file to open its symbol outline
+
+---
+
+## Symbol search
+
+- Real-time search with 300ms debounce — results appear as you type
+- Filter by: symbol kind, language, file path pattern
+- Keyboard navigation: arrow keys to move through results, Enter to open
+- Query term highlighting in results
+- Switches between keyword and semantic mode (if semantic search is enabled)
+
+---
+
+## Symbol viewer
+
+- Syntax-highlighted source code (powered by Shiki — VS Code-quality highlighting)
+- Line numbers with anchors (shareable URLs)
+- Light/dark theme toggle (preference persisted in localStorage)
+- **Related symbols panel**: importers, dependencies, same-file symbols
+
+---
+
+## Dependency graph viewer
+
+An interactive force-directed graph of file and symbol dependencies.
+
+### Controls
+
+| Action | Control |
+|--------|---------|
+| Pan | Click and drag |
+| Zoom | Scroll wheel |
+| Fit to view | Double-click background |
+| Select node | Click |
+| Expand node | Click `+` |
+| Forward walk | Enable "Dependencies" mode |
+| Reverse walk | Enable "Importers" mode |
+
+### Layout options
+
+- **Force-directed** (default) — physics simulation, nodes cluster by connectivity
+- **Hierarchical** — root at top, dependencies flow downward
+- **Radial** — selected node at center, connected nodes radiate outward
+
+### Depth slider
+
+Adjust traversal depth (1–5 hops). Higher depth reveals transitive dependencies but may produce large graphs.
+
+### Blast radius view
+
+Switch to "Blast radius" mode to see everything that depends on the selected node — color gradient from red (direct impact) to yellow (indirect).
+
+---
+
+## Architecture heatmap
+
+An overlay on the file tree that color-codes files by a selected metric:
+
+| Metric | Color scale | Use case |
+|--------|-------------|----------|
+| Churn | blue (stable) → red (high churn) | Identify high-risk files before a refactor |
+| Complexity | green → orange → red | Find over-complex files that need attention |
+| Quality score | green (high) → red (low) | Prioritize technical debt |
+| Test coverage | green (covered) → red (uncovered) | Requires external coverage report |
+
+Click any cell in the heatmap to open the file's symbol outline.
+
+---
+
+## Symbol timeline
+
+Per-symbol git history visualized as a timeline. Shows:
+- When the symbol was created (first commit where it appears)
+- Each commit that modified the symbol (with author, date, message)
+- When the symbol was deleted (if applicable)
+
+Requires git history integration enabled (see [Git & History Integration](18-git-history.md)).
+
+---
+
+## Test coverage overlay
+
+Overlays test coverage data on the file tree. Requires an lcov-format coverage report:
+
+1. Run your test suite with coverage output (`npx vitest --coverage`, `pytest --cov`, etc.)
+2. Export as lcov: `coverage.info` / `lcov.info`
+3. In PureContext Web UI: Settings → Coverage → Upload lcov file
+
+Files are color-coded by coverage percentage. Click a file to see line-level coverage in the source viewer.
+
+---
+
+## Multi-repo workspace
+
+When multiple repos are indexed, the sidebar shows a repo switcher. Cross-repo search results appear in a unified list with the source repo identified for each result.
+
+---
+
+## Advanced graph controls
+
+Additional controls available in the graph viewer:
+
+| Feature | Description |
+|---------|-------------|
+| Language filter | Show only nodes of a specific language |
+| Kind filter | Show only files/symbols of a specific kind |
+| Cycle detection | Highlight circular dependency cycles in red |
+| Export | Save graph as SVG or PNG |
+| Minimap | Overview panel for large graphs |
+
+---
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `/` | Focus search bar |
+| `↑` / `↓` | Navigate search results |
+| `Enter` | Open selected symbol |
+| `Esc` | Close panels / clear search |
+| `G` | Open graph view for current symbol |
+| `B` | Show blast radius for current symbol |
+| `H` | Toggle heatmap overlay |