purecontext-mcp 1.5.0 → 1.5.2

package/docs/07-language-support.md

@@ -1,26 +1,31 @@
-# Language Support
+# Language Support — Reference
 
+This is the reference page: the per-language symbol-kind table and grammar notes.
 
-PureContext supports **34 languages** via tree-sitter WASM grammars. All grammars are bundled in the `grammars/` directory — no separate install needed.
+For the **user-friendly tour** — category groupings, framework integration notes, "Adding a new language" guide — see [`LANGUAGE-SUPPORT.md`](../LANGUAGE-SUPPORT.md) at the project root.
 
 ---
 
-## Supported languages
+PureContext supports **34 languages** via tree-sitter WASM grammars plus four regex-based handlers for CSS-family languages. All grammars are bundled in `grammars/` — no separate install needed.
 
-| Language | Extensions | Symbol Types | Doc Comments |
+---
+
+## Symbol-kind matrix (tree-sitter handlers)
+
+| Language | Extensions | Symbol Kinds | Doc Comments |
 |----------|-----------|--------------|--------------|
 | TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | function, class, method, const, type, interface, enum | JSDoc `/** */` |
 | JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | function, class, method, const | JSDoc `/** */` |
-| Python | `.py` | function, class, method, const | Docstrings `"""` |
+| Python | `.py` | function, class, method, const | `"""` docstrings |
 | Go | `.go` | function, method, class (struct), interface, const, type | `//` preceding comments |
 | Rust | `.rs` | function, method, class (struct), enum, interface (trait), const, type | `///` doc comments |
 | Java | `.java` | class, interface, enum, method, const | Javadoc `/** */` |
 | C# | `.cs` | class, interface, enum, struct, record, method, const, property | XML docs `/// <summary>` |
-| PHP | `.php` | function, class, interface, trait, enum, method, const | PHPDoc `/** */` |
-| Ruby | `.rb` | function, class, method, module, const | `#` comments |
-| Kotlin | `.kt`, `.kts` | function, class, interface, enum, method, typealias, object | KDoc `/**` |
+| PHP | `.php` | function, class, interface, trait, enum, method, const, property | PHPDoc `/** */` |
+| Ruby | `.rb` | function, class, method, module, const, property (DSL macros) | `#` comments |
+| Kotlin | `.kt`, `.kts` | function, class, interface, enum, method, typealias, object, property | KDoc `/**` |
 | C | `.c`, `.h` | function, struct, enum, macro, type | `//` and `/* */` |
-| C++ | `.cpp`, `.cxx`, `.cc`, `.hpp`, `.hxx`, `.hh` | All C types + namespace, template | `///` Doxygen |
+| C++ | `.cpp`, `.cxx`, `.cc`, `.hpp`, `.hxx`, `.hh` | All C kinds + namespace, template, template-class | `///` Doxygen |
 | Lua | `.lua` | function, method, const | `--` comments |
 | Dart | `.dart` | class, mixin, extension, enum, function, method, const, type | `///` doc comments |
 | Swift | `.swift` | class, struct, protocol, actor, extension, method, enum, type | `///` DocC |
@@ -28,61 +33,79 @@ PureContext supports **34 languages** via tree-sitter WASM grammars. All grammar
 | Haskell | `.hs`, `.lhs` | function, data (class), typeclass (interface), instance, type, newtype | Haddock `-- \|` |
 | Scala | `.scala`, `.sc` | class, trait, object, case class, function, method, type, enum | Scaladoc `/** */` |
 | R | `.r`, `.R`, `.Rmd` | function, const, S3/S4/R6 class | Roxygen2 `#'` |
-| Bash | `.sh`, `.bash` | function |
-| Perl | `.pl`, `.pm` | function, package |
-| Terraform / HCL | `.tf`, `.hcl` | resource, module, variable, output |
-| Nix | `.nix` | function, attribute |
-| Protobuf | `.proto` | message, service, enum, rpc |
-| GraphQL | `.graphql`, `.gql` | type, query, mutation, subscription, fragment |
-| Groovy | `.groovy` | function, class, method |
-| Erlang | `.erl`, `.hrl` | function, module |
-| Gleam | `.gleam` | function, type |
-| GDScript | `.gd` | function, class, signal |
-| XML | `.xml` | element (configurable patterns) |
-| Objective-C | `.m`, `.h` | function, class, method |
-| Fortran | `.f90`, `.f95`, `.for`, `.f` | function, subroutine, module |
-| SQL | `.sql` | table, view, function, procedure |
-| OpenAPI / YAML | `.yaml`, `.yml` (OpenAPI detected by content) | endpoint, schema |
+| Bash | `.sh`, `.bash`, extensionless (shebang-detected) | function | — |
+| Perl | `.pl`, `.pm` | function, package | — |
+| Groovy | `.groovy` | function, class, method | — |
+| Erlang | `.erl`, `.hrl` | function (bare name; arity in `frameworkMeta`), module | — |
+| Gleam | `.gleam` | function, type | — |
+| GDScript | `.gd` | function, class, signal | — |
+| Objective-C | `.m`, `.h` (guarded) | function, class, protocol, method (full selector), property, category | — |
+| Fortran | `.f90`, `.f95`, `.for`, `.f`, `.F90` (case-insensitive) | function, subroutine, module | — |
+| Terraform / HCL | `.tf`, `.tfvars`, `.hcl` | variable, output, resource, data, module, provider, locals | — |
+| Nix | `.nix` | function, attribute | — |
+| SQL | `.sql` | table, view, function, procedure | — |
+| Protobuf | `.proto` | message, service, enum, rpc | — |
+| GraphQL | `.graphql`, `.gql` | type, query, mutation, subscription, fragment | — |
+| OpenAPI / YAML | `.yaml`, `.yml` (content-detected) | endpoint, schema | — |
+| XML | `.xml` | element (disambiguated as `tag@module` in multi-module repos) | — |
+| Angular HTML | `.html` (guarded) | component selector, structural directive, control flow, event binding, template ref | — |
 
 ---
 
-## What gets indexed
+## Symbol-kind matrix (regex handlers, no WASM grammar)
 
-For all languages, the indexer extracts:
+| Language | Extensions | Symbol Kinds |
+|----------|-----------|--------------|
+| SCSS / SASS | `.scss`, `.sass` | `@mixin` → function, `@function` → function, top-level `$var` → const, `%placeholder` → class, `@keyframes` → type |
+| LESS | `.less` | `.mixin(@params)` → function, top-level `@var` → const, `@keyframes` → type |
+| CSS | `.css` | `--custom-property` → const (opt-in via `indexing.cssVariables: true`) |
 
-- **Symbol name** — the identifier as it appears in source
-- **Symbol kind** — function, class, method, route, component, etc.
-- **Byte offsets** (`startByte`, `endByte`) — for precise source retrieval without reading the whole file
-- **Signature** — a one-line declaration (TypeScript shows full type annotations, Python shows type hints if present)
-- **Summary** — sourced from docstring, framework inference, AI, or signature fallback
-- **Import/dependency edges** — for the dependency graph
+CSS-family languages don't have a stable tree-sitter grammar, so PureContext uses targeted regex extraction. Only named, reusable constructs are indexed — plain selectors would flood the index with noise.
 
 ---
 
-## What is excluded automatically
+## Visibility filtering
 
-The indexer skips these automatically:
+| Language | What is excluded |
+|----------|------------------|
+| Go | Unexported identifiers (lowercase first letter) |
+| C | `static` functions (translation-unit internal) |
+| Java | `private` members |
+| C# | `private` members; interface members are implicitly public |
+| PHP | `private` members |
+| Dart | `_`-prefixed identifiers |
+| Rust | Non-`pub` impl methods |
 
-- `node_modules/`, `.git/`, `dist/`, `build/`, `.claude/`, `target/`, `.next/`, `.nuxt/`
-- `*.lock` files, `.env*` files
-- Binary files (detected by null-byte scanning of the first 8 KB)
-- Files > 1 MB (configurable via `maxFileSizeBytes`)
-- Secret files: `*.pem`, `*.key`, `id_rsa`, `credentials.json`, `serviceAccountKey*.json`, etc.
-- Language-specific private symbols:
-  - Go: unexported names (lowercase)
-  - C: `static` functions (translation-unit internal)
-  - Java/C#/PHP: `private` members
-  - Dart: `_`-prefixed names
+`get_public_api` and related tools depend on these rules being applied consistently.
 
 ---
 
-## Grammar notes
+## File-system exclusions
+
+Applied before any handler runs:
+
+- Directories: `node_modules/`, `.git/`, `dist/`, `build/`, `target/`, `.next/`, `.nuxt/`, `.claude/`
+- Lock files (`*.lock`), env files (`.env*`)
+- Binary files (null-byte scan of first 8 KB; no hardcoded extension list)
+- Files larger than 1 MB (override via `indexing.maxFileSizeBytes`)
+- Secret patterns: `*.pem`, `*.key`, `id_rsa`, `credentials.json`, `serviceAccountKey*.json`
 
-Grammars are bundled as `.wasm` files in the `grammars/` directory. They are loaded once per worker thread at startup. Grammar versions are pinned in `package.json` and tested against the test fixtures in `test/handlers/`.
+---
+
+## Grammar notes and known limitations
 
-Known limitations:
-- **TypeScript JSX** (`.tsx`): the `tree-sitter-tsx` grammar is separate from `tree-sitter-typescript` and is used for all `.tsx` files.
-- **Python**: type hints in stubs (`.pyi`) are not indexed — only `.py` files.
+- **TypeScript JSX** (`.tsx`) uses `tree-sitter-tsx`, a separate grammar from `tree-sitter-typescript`. Both are bundled.
+- **Python stubs** (`.pyi`) are not indexed — only `.py` files.
+- **Objective-C** `.h` files are guarded: parsed as ObjC only if the first 16 KB contain `@interface` or `@protocol`; otherwise treated as C.
+- **Angular HTML** `.html` files are guarded: parsed as Angular templates only if a sibling `.component.ts` exists or the first 4 KB contain Angular markers.
 - **Terraform**: complex `dynamic` blocks may not be fully extracted.
-- **XML**: element extraction uses configurable patterns — not all XML files are indexed by default.
+- **XML**: element extraction uses configurable patterns; not every tag is indexed by default. Root-element symbols are stored as `tag@module` in multi-module repos to avoid collisions.
+- **OpenAPI**: schema-name extraction supports hyphens (`[\w-]+`), so GitHub-style schemas like `pull-request` are indexed.
+
+---
+
+## Related reference
 
+- [Framework Adapters](08-framework-adapters.md) — adapter layer that adds framework-specific symbols on top of these handlers
+- [Configuration](04-configuration.md) — `indexing.*` flags including `cssVariables`, `maxFileSizeBytes`, `xmlElementPatterns`
+- [Architecture Overview](25-architecture-overview.md) — three-layer design (Core → Handlers → Adapters)

package/docs/08-framework-adapters.md

@@ -1,9 +1,14 @@
-# Framework Adapters
+# Framework Adapters — Reference
 
+This is the reference page: detection criteria, extracted symbol kinds, and `frameworkMeta` shape for every adapter.
+
+For the **user-friendly tour** — how adapters change what you see in search results, with examples and "useful for" notes — see [`FRAMEWORK-ADAPTERS.md`](../FRAMEWORK-ADAPTERS.md) at the project root.
+
+---
 
 Framework adapters layer domain-specific symbol extraction on top of language handlers. They are auto-detected from project config files.
 
-## How adapters work
+## The `FrameworkAdapter` interface
 
 Each adapter implements the `FrameworkAdapter` interface:
 

package/docs/15-team-setup.md

@@ -1,209 +1,56 @@
-# Team Setup & Multi-Tenant
+# Team Setup & Multi-Tenant — Reference
 
+This is the reference page: API key permissions, rate-limit configuration, admin API endpoints, and the production hardening checklist.
 
-Run PureContext as a shared server so your whole team queries the same index — no per-developer re-indexing.
+For the **user-friendly walkthrough** — why a shared server matters, deployment options, end-to-end setup with examples — see [`TEAM-SETUP.md`](../TEAM-SETUP.md) at the project root.
 
 ---
 
-## Overview
+## Workspace and key model
 
-```
-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.
+| Concept | Description |
+|---------|-------------|
+| Workspace | The unit of isolation. One team = one workspace. All repos and keys belong to a workspace. |
+| API key | A per-developer credential. Shown once on creation and never displayed again. Stored as a SHA-256 hash. |
+| Admin key | A long-lived secret (`PCTX_ADMIN_KEY`) that authenticates workspace and key management calls. Set via env var only. |
 
 ---
 
-## 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 levels
 
 | Permission | Allowed operations |
-|------------|-------------------|
-| `read` | Search symbols, get outlines, get source |
-| `write` | + `index_folder`, `index_repo` |
+|------------|--------------------|
+| `read` | Search symbols, get outlines, fetch source |
+| `write` | + `index_folder`, `index_repo`, `invalidate_cache` |
 | `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`.
+For AI agents that only query, use `read`. For CI pipelines that re-index on push, use `write`. Never issue `admin` to a developer or agent — keep it on the admin key alone.
 
 ---
 
-## 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 per API key.
 
-## Rate limiting
+| Field | Default | Description |
+|-------|--------:|-------------|
+| `rateLimit.enabled` | `true` | Disable to allow unbounded usage (single-tenant only) |
+| `rateLimit.maxTokens` | `100` | Bucket capacity per key |
+| `rateLimit.refillRate` | `10` | Tokens added per second |
+| `rateLimit.perToolLimits.<tool>` | varies | Per-tool cost override |
 
-HTTP mode uses a token-bucket algorithm to prevent any single client from overwhelming the server:
+Default per-tool costs:
 
-- 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
+| Tool | Cost |
+|------|-----:|
+| `search_symbols`, `search_text`, `search_semantic` | 1 |
+| `get_symbol_source`, `get_file_outline`, `get_context_bundle` | 1 |
+| `index_folder`, `index_repo` | 10 |
+| `health_radar`, `get_debt_report`, `detect_antipatterns` | 5 |
 
-When rate limited, responses return `429 Too Many Requests` with a `Retry-After` header.
+When a bucket empties, the server returns `429 Too Many Requests` with a `Retry-After` header.
 
-Configure per-tool costs in `config.json`:
+Example config:
 
 ```json
 {
@@ -223,29 +70,52 @@ Configure per-tool costs in `config.json`:
 
 ## Admin API reference
 
-All endpoints require `Authorization: Bearer <PCTX_ADMIN_KEY>`.
+All endpoints require `Authorization: Bearer <PCTX_ADMIN_KEY>`. Base URL: the server's bind address (default `http://localhost:3000`).
 
 | 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 |
+| `/admin/workspaces` | `POST` | Create workspace. Body: `{name, plan}`. Returns `{id, name, plan, created_at}`. |
+| `/admin/workspaces` | `GET` | List workspaces. |
+| `/admin/workspaces/:id` | `DELETE` | Delete workspace and all data. |
+| `/admin/keys` | `POST` | Create API key. Body: `{label, permissions[], workspace_id}`. **Raw key returned once.** |
+| `/admin/keys` | `GET` | List keys (label + prefix + permissions; never raw key). |
+| `/admin/keys/:prefix` | `DELETE` | Revoke key by hash prefix. |
+| `/admin/keys/:prefix/usage` | `GET` | Per-key usage counters. |
+| `/admin/stats` | `GET` | Server-wide statistics. |
+| `/health` | `GET` | Public health check (no auth). Returns `{status, version, repoCount}`. |
 
 ---
 
-## Production checklist
+## Server-mode environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PCTX_ADMIN_KEY` | yes | Admin secret. Minimum 32 hex chars recommended. |
+| `PCTX_DATA_DIR` | no | Override default `/data` (Docker) or `~/.purecontext` (npm). |
+| `PCTX_BIND_HOST` | no | Default `0.0.0.0` in server mode. |
+| `PCTX_BIND_PORT` | no | Default `3000`. |
+| `PCTX_LOG_LEVEL` | no | `debug` / `info` / `warn` / `error`. |
+
+CLI flags `--server`, `--host`, `--port` take precedence over env vars.
+
+---
 
-- [ ] `PCTX_ADMIN_KEY` is a long random secret (≥ 32 hex chars), set via env var only — never in a committed config file
+## Production hardening checklist
+
+- [ ] `PCTX_ADMIN_KEY` is a ≥32-char random secret, 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
+- [ ] Port 3000 is not directly exposed to the public internet (terminate TLS at the proxy)
+- [ ] `/data` volume sits on a backed-up disk
+- [ ] `restart: unless-stopped` set in docker-compose
+- [ ] Developers have `read` permission only unless they specifically need to re-index
 - [ ] Admin key is rotated if ever exposed
+- [ ] Rate limiting enabled and tuned for your team size
+
+---
+
+## Related reference
 
-See [Docker Deployment](16-docker.md) for full reverse proxy examples.
+- [Transport Modes](14-transport-modes.md) — stdio vs HTTP/SSE deep dive
+- [Docker Deployment](16-docker.md) — container image, compose examples, reverse-proxy templates
+- [Security](24-security.md) — threat model, API-key storage, path-traversal protections
+- [Configuration](04-configuration.md) — full `config.json` schema