purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/SELF_HOSTING.md

@@ -1,142 +0,0 @@
-# Self-Hosting PureContext MCP
-
-This guide covers deploying PureContext as an always-on shared server for a team using Docker.
-
-## Prerequisites
-
-- Docker and Docker Compose installed
-- A Linux/macOS host (or any Docker-capable machine)
-- Outbound network access for team members to reach the server
-
----
-
-## Quick Start with Docker Compose
-
-1. **Create a working directory:**
-   ```bash
-   mkdir purecontext && cd purecontext
-   ```
-
-2. **Download the compose file:**
-   ```bash
-   curl -O https://raw.githubusercontent.com/gococ/purecontext-mcp/main/docker-compose.yml
-   ```
-
-3. **Set the admin key** (required before starting):
-   ```bash
-   export PCTX_ADMIN_KEY="$(openssl rand -hex 32)"
-   echo "Admin key: $PCTX_ADMIN_KEY"   # Save this somewhere safe
-   ```
-
-4. **Start the server:**
-   ```bash
-   PCTX_ADMIN_KEY="$PCTX_ADMIN_KEY" docker compose up -d
-   ```
-
-5. **Verify it is running:**
-   ```bash
-   curl http://localhost:3000/health
-   # {"status":"ok","version":"1.0.0","repoCount":0,...}
-   ```
-
----
-
-## Create a Workspace
-
-A workspace is the organizational unit for a team. Each workspace gets its own API keys.
-
-```bash
-curl -X POST http://localhost:3000/admin/workspaces \
-  -H "Authorization: Bearer $PCTX_ADMIN_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "My Team"}'
-# {"id":"a1b2c3d4","name":"My Team","plan":"team",...}
-```
-
-Save the workspace `id` — you need it when creating API keys.
-
----
-
-## Create API Keys for Team Members
-
-Each developer gets their own API key. Keys are shown once on creation and never again.
-
-```bash
-# Using the CLI (if purecontext-mcp is installed locally):
-purecontext-mcp keys create --label "Alice's laptop"
-
-# Or via the admin API:
-curl -X POST http://localhost:3000/admin/keys \
-  -H "Authorization: Bearer $PCTX_ADMIN_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"label": "Alice'\''s laptop", "workspaceId": "a1b2c3d4"}'
-# {"key":"pctx_abc123...","id":"...","label":"Alice's laptop"}
-```
-
-Give each developer their `pctx_...` key. They use it to connect Claude Code.
-
----
-
-## Connect Claude Code to the Shared Server
-
-Each developer runs this once on their machine:
-
-```bash
-claude mcp add purecontext-remote \
-  --transport http \
-  --url https://purecontext.mycompany.com/mcp \
-  --header "Authorization: Bearer pctx_yourkey"
-```
-
-Replace `purecontext.mycompany.com` with your server's hostname/IP and `pctx_yourkey` with the developer's personal API key.
-
----
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PCTX_ADMIN_KEY` | *(required)* | Admin key for `/admin/*` endpoints. Set this via environment, never in config files. |
-| `PCTX_DATA_DIR` | `/data` (Docker) | Directory for indexes and auth DB. Maps to `~/.purecontext` in local installs. |
-| `PCTX_PORT` | `3000` | TCP port to listen on. |
-| `PCTX_HOST` | `0.0.0.0` | Interface to bind to. |
-
----
-
-## Updating
-
-The SQLite data lives in the Docker volume (`./data`), so it persists across image updates:
-
-```bash
-docker compose pull
-docker compose up -d
-```
-
-Your indexes and API keys are unaffected.
-
----
-
-## Production Checklist
-
-- [ ] `PCTX_ADMIN_KEY` is set to a strong random value (at least 32 hex chars)
-- [ ] Server is behind a reverse proxy (nginx/Caddy) with TLS
-- [ ] Port 3000 is not directly exposed to the internet (terminate TLS at the proxy)
-- [ ] Volume (`./data`) is on a backed-up disk
-- [ ] `restart: unless-stopped` is set in compose (already in the example file)
-
----
-
-## Troubleshooting
-
-**401 on all requests:**
-Make sure you are passing the API key in the `Authorization` header: `Authorization: Bearer pctx_...`
-
-**403 on `/admin/*` routes:**
-Admin routes require the `PCTX_ADMIN_KEY` value, not a regular user API key.
-
-**Connection timeout from Claude Code:**
-- Verify the server URL is reachable from the developer's machine: `curl https://purecontext.mycompany.com/health`
-- Check firewall rules and reverse proxy configuration
-
-**"Workspace not found" errors:**
-The API key must be associated with a workspace. Re-create the key using `POST /admin/keys` with the correct `workspaceId`.

package/docs/dev/TEAM_SETUP.md

@@ -1,316 +0,0 @@
-# PureContext Team Setup Guide
-
-This guide walks through deploying PureContext as a shared server for a development team, creating workspaces and API keys, and connecting each developer's Claude Code instance to the shared index.
-
-## Overview
-
-```
-Phase 1–17 (local mode):          Phase 18+ (server mode):
-  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 — faster, consistent, and the natural monetization layer for team features.
-
----
-
-## 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'll need it to manage keys and workspaces.
-
-### Docker Compose
-
-```yaml
-# docker-compose.yml
-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
-```
-
-### Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PCTX_ADMIN_KEY` | Admin authentication token | Required in server mode |
-| `PCTX_DATA_DIR` | Data directory for indexes | `~/.purecontext` |
-| `PCTX_PORT` | HTTP port | `3000` |
-| `PCTX_HOST` | Bind address | `0.0.0.0` |
-
-### Verify the server is running
-
-```bash
-curl http://localhost:3000/health
-# {"status":"ok","version":"1.0.0","repoCount":0,"uptime":1.2}
-```
-
----
-
-## 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"
-
-# Create a workspace
-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
-# Create a key for a developer
-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):
-# {
-#   "key": "pctx_00000000_..._1234",
-#   "label": "alice-macbook",
-#   "permissions": ["read", "write"],
-#   "key_hash_prefix": "deadbeef"
-# }
-```
-
-**Repeat for each developer.** Each person gets a unique key.
-
-### Permission levels
-
-| Permission | Can do |
-|------------|--------|
-| `read` | Search symbols, get outlines, get source |
-| `write` | + Index new repos (`index_folder`) |
-| `admin` | + Manage keys and workspaces |
-
----
-
-## Step 4 — Index the Codebase
-
-Index the shared codebase from the server (or from any machine with `write` permission and network access to the repo path).
-
-```bash
-# Initialize a session first
-SESSION_RESPONSE=$(curl -s -X POST "$SERVER/mcp/sse" \
-  -H "Authorization: Bearer pctx_yourwritekey" \
-  -H "Accept: application/json, text/event-stream" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "method": "initialize",
-    "params": {
-      "protocolVersion": "2024-11-05",
-      "capabilities": {},
-      "clientInfo": {"name": "cli", "version": "1.0.0"}
-    },
-    "id": 1
-  }')
-
-SESSION_ID=$(echo "$SESSION_RESPONSE" | grep -i "mcp-session-id" | awk '{print $2}' | tr -d '\r')
-
-# Index the repository
-curl -s -X POST "$SERVER/mcp/sse" \
-  -H "Authorization: Bearer pctx_yourwritekey" \
-  -H "mcp-session-id: $SESSION_ID" \
-  -H "Accept: application/json, text/event-stream" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "method": "tools/call",
-    "params": {
-      "name": "index_folder",
-      "arguments": {"path": "/path/to/repo"}
-    },
-    "id": 2
-  }'
-```
-
-Or simply connect Claude Code (step 5) and ask it to index via chat.
-
----
-
-## Step 5 — Connect Claude Code
-
-Each developer runs this once on their machine (using their personal API key):
-
-```bash
-claude mcp add purecontext-remote \
-  --transport http \
-  --url https://purecontext.mycompany.com/mcp/sse \
-  --header "Authorization: Bearer pctx_yourpersonalkey"
-```
-
-After adding, restart Claude Code and verify the connection:
-
-```
-/mcp
-# Should show purecontext-remote as connected
-```
-
-Then in a conversation:
-
-```
-List my indexed repositories using list_repos
-```
-
----
-
-## Step 6 — Manage Keys Over Time
-
-```bash
-# List all keys
-curl -s "$SERVER/admin/keys" -H "Authorization: Bearer $ADMIN_KEY" | jq .
-
-# Revoke a key by hash prefix (e.g. when someone leaves the team)
-curl -s -X DELETE "$SERVER/admin/keys/deadbeef" \
-  -H "Authorization: Bearer $ADMIN_KEY"
-
-# Check key usage
-curl -s "$SERVER/admin/keys/deadbeef/usage" \
-  -H "Authorization: Bearer $ADMIN_KEY" | jq .
-```
-
----
-
-## Production Checklist
-
-- [ ] `PCTX_ADMIN_KEY` is a long random secret (≥ 32 hex chars), set via env var only
-- [ ] Server is behind a reverse proxy (nginx/Caddy) with TLS
-- [ ] `/data` volume is backed up regularly (it contains all indexes)
-- [ ] Admin key is NOT in any config file that could be committed to git
-
-### nginx reverse proxy 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;
-        # Important for SSE: disable buffering
-        proxy_buffering off;
-        proxy_cache off;
-        proxy_read_timeout 3600s;
-    }
-}
-```
-
-### Caddy example
-
-```
-purecontext.mycompany.com {
-    reverse_proxy localhost:3000 {
-        flush_interval -1  # disable buffering for SSE
-    }
-}
-```
-
----
-
-## Troubleshooting
-
-### Connection timeouts on GET /mcp/sse
-
-The SSE connection sends a `: ping` comment every 30 seconds to keep the stream alive. If your proxy or load balancer has a shorter idle timeout, increase it. With nginx, use `proxy_read_timeout 3600s`.
-
-### Authentication errors
-
-```bash
-# Test your key
-curl -s -X POST "$SERVER/mcp/sse" \
-  -H "Authorization: Bearer pctx_yourkey" \
-  -H "Accept: application/json, text/event-stream" \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'
-```
-
-- `401` → key missing or wrong format
-- `401` → key revoked or not found in DB
-- `403` → key lacks required permission
-
-### Health check
-
-```bash
-curl http://localhost:3000/health
-```
-
-Returns 200 even without authentication — use this to verify the server is running.
-
-### Server logs (Docker)
-
-```bash
-docker logs -f purecontext
-```
-
-### Update
-
-```bash
-docker pull purecontext/purecontext-mcp:latest
-docker compose up -d --force-recreate
-```
-
-The SQLite index is in the `/data` volume — it persists across container restarts and updates.

package/docs/dev/TELEMETRY.md

@@ -1,99 +0,0 @@
-# PureContext MCP — Telemetry
-
-PureContext MCP includes **opt-in anonymous telemetry** so the maintainers can understand which languages, adapters, and features are actually used in the wild. This data helps us prioritize work and improve the tool.
-
-## Opt-in, not opt-out
-
-**No data is sent unless you explicitly enable telemetry.**
-
-The default is `telemetry.enabled: false`. When you run `purecontext-mcp config --init`, you will be asked whether you want to enable telemetry. You can change your answer at any time by editing `~/.purecontext/config.json`.
-
-## What is collected
-
-When telemetry is enabled, the following is sent after each indexing operation and on server startup:
-
-### `index_complete` event
-
-```json
-{
-  "event": "index_complete",
-  "version": "1.0.0",
-  "nodeVersion": "20.11.0",
-  "platform": "linux",
-  "languages": ["typescript", "javascript"],
-  "adapterNames": ["vue", "nuxt"],
-  "fileCount": 342,
-  "symbolCount": 4821,
-  "durationMs": 1240,
-  "workerCount": 4,
-  "sessionId": "a1b2c3d4-...",
-  "timestamp": "2026-04-26T10:00:00.000Z"
-}
-```
-
-### `server_start` event
-
-```json
-{
-  "event": "server_start",
-  "version": "1.0.0",
-  "nodeVersion": "20.11.0",
-  "platform": "linux",
-  "sessionId": "a1b2c3d4-...",
-  "timestamp": "2026-04-26T10:00:00.000Z"
-}
-```
-
-**`sessionId`** is a random UUID generated fresh each time the process starts. It is **not** persisted between sessions — it cannot be used to track you across restarts.
-
-## What is never collected
-
-- File paths, directory names, or repo names
-- Symbol names, function names, or any source code content
-- Import specifiers or file contents
-- IP addresses or any personally identifiable information
-- Anything not listed in the "What is collected" section above
-
-## Local audit log
-
-Every event sent is also appended to `~/.purecontext/telemetry.jsonl` so you can inspect exactly what was transmitted. This file is local only and never shared automatically.
-
-## How to enable or disable
-
-**Enable:**
-
-```json
-// ~/.purecontext/config.json
-{
-  "telemetry": {
-    "enabled": true
-  }
-}
-```
-
-**Disable (default):**
-
-```json
-{
-  "telemetry": {
-    "enabled": false
-  }
-}
-```
-
-Run `purecontext-mcp config --init` to regenerate the config file with an interactive opt-in prompt.
-
-## Where data is sent
-
-Events are POSTed to `https://telemetry.purecontext.dev/v1/event`. You can override this endpoint in config:
-
-```json
-{
-  "telemetry": {
-    "enabled": true,
-    "endpoint": "https://your-own-telemetry-server.example.com/v1/event"
-  }
-}
-```
-
-Network errors are silently discarded — telemetry failures never affect PureContext's normal operation.