purecontext-mcp 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -0,0 +1,212 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.1.0] - 2026-05-07
+
+### Added
+
+**New MCP tools**
+- `find_references` — find all usage/call sites for a symbol across the repo (identifier-level, not import-level)
+- `get_file_content` — retrieve raw cached file content with optional line-range slicing (`startLine`/`endLine`)
+- `get_symbols` — batch-fetch multiple symbols by ID, returning source in a single round-trip
+- `invalidate_cache` — force a full or per-file re-index by clearing content hashes; accepts optional `filePath` to scope invalidation
+
+**Tool capability enhancements**
+- `search_symbols`: new `debug` parameter — includes per-result relevance scoring breakdown (FTS5 rank, kind boost, exact-match bonus)
+- `get_symbol_source`: new `context_lines` parameter (extra lines above/below) and `verify` flag (re-reads from disk to confirm source is current)
+- `index_repo`: clone and index a remote Git repository by URL; supports private repos via `token`; clones stored at `~/.purecontext/clones/`
+- AI summarization via Gemini Flash — configurable as an embedding/summarization provider alongside Anthropic and OpenAI
+
+**Ecosystem & data tools**
+- Context provider framework — plugin interface (`ContextProvider`) for domain-specific symbol enrichment; providers auto-detected from project config
+- dbt integration — indexes models, sources, seeds, macros, and exposures; dbt Jinja pre-processor expands `{{ ref() }}` / `{{ source() }}` before SQL parsing; column definitions from `schema.yml` stored in `frameworkMeta.columns`
+- OpenAPI/Swagger handler — parses `.yaml`/`.yml` files detected as OpenAPI specs; indexes endpoints and schemas as symbols
+- SQL handler — indexes tables, views, functions, and stored procedures; works standalone and with dbt Jinja expansion
+- `search_columns` tool — search dbt/SQL column definitions by name or description, with upstream/downstream lineage
+
+**Language coverage expansion to 34 languages**
+
+16 new language handlers added (previously 18):
+
+| Language | Extensions | Key symbol types |
+|----------|-----------|-----------------|
+| 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 (pattern-configurable) |
+| 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` | endpoint, schema |
+| PHP (doc coverage) | existing | PHPDoc `/** */` extraction improved |
+
+**Cross-repo intelligence**
+- `search_cross_repo` tool — unified symbol search across all repos in a workspace; supports keyword, semantic, and hybrid modes; results include `repoId` and `repoPath`
+- `find_similar` tool — find semantically similar code across repos using HNSW cosine similarity; configurable `minSimilarity` threshold (requires semantic search enabled)
+- Cross-repo dependency tracking — `dep_edges` extended with `sourceRepoId`/`targetRepoId` columns; `get_blast_radius` and `find_importers` can now follow edges across repo boundaries
+- MCP Resources — indexed symbol outlines exposed as MCP Resources (`purecontext://repo/<repoId>/outline`) for clients that support resource subscriptions
+
+**Git & history integration**
+- Git metadata indexing — during `index_folder`, PureContext walks `git log` and maps commits to symbols via byte-range overlap; stored in new `git_metadata` SQLite table; configurable via `git.enabled`, `git.maxCommits`, `git.branches`
+- `get_symbol_history` tool — symbol-level commit history (hash, author, date, message, diff) without agents needing to run git commands
+- `get_churn_metrics` tool — file or symbol churn scores (commits, lines changed, authors, churn score) with optional `since` date filter; surfaces high-risk files
+
+**AI-powered architecture analysis**
+- `get_quality_metrics` tool — per-file quality scores: cyclomatic complexity, coupling (fan-in/fan-out), cohesion, doc coverage, and a composite 0–100 score
+- `detect_antipatterns` tool — detects god classes, circular dependencies, deep inheritance, feature envy, and other common anti-patterns; results include severity and symbol ID
+- `get_architecture_doc` tool — auto-generates a Markdown or Mermaid architecture summary from the dependency graph and quality metrics
+- `get_layer_violations` tool — detects import boundary violations given a layer definition (e.g., controllers must not import repositories directly)
+
+**Enhanced Web UI**
+- Architecture heatmap — colour-coded file tree where heat indicates churn score or quality score; helps identify hot spots at a glance
+- Symbol timeline — visual history of commits touching a symbol, linked to `get_symbol_history` data
+- Test coverage overlay — when a coverage JSON report is present, file tree nodes show line coverage percentages
+- Multi-repo workspace view — repository picker with cross-repo search tab; switch between repos without reloading
+- Advanced dependency graph — zoom/pan, node grouping by directory, edge filtering by kind, and path highlighting between two selected nodes
+
+**Distribution & platform**
+- Index export (`npx purecontext-mcp export`) — archives the SQLite database and HNSW index into a portable `.pctx.tar.gz` file
+- Index import (`npx purecontext-mcp import`) — restores an exported archive; repo is immediately searchable, no re-indexing required
+- Public registry — pre-built indexes for popular open-source projects hosted on CDN; pull with `npx purecontext-mcp pull <package>@<version>`; browse with `npx purecontext-mcp registry list`
+- Webhook auto-reindex — HTTP endpoint (`POST /webhook/reindex`) accepts GitHub/GitLab push payloads and triggers incremental re-indexing automatically
+- GitHub Actions composite action — `.github/actions/purecontext-cache/action.yml`; caches the index between CI runs using `actions/cache`, exports after indexing, imports on cache hit
+- VS Code extension — `vscode-purecontext` extension wraps the MCP server with a sidebar panel for symbol search, file outline, and dependency graph directly in the editor
+
+### Changed
+
+- `search_symbols` response now includes `repoId` in every result (was implicit from the request parameter) — enables direct use in cross-repo result lists
+- `list_repos` now includes `gitEnabled` and `lastGitIndexed` fields when git metadata indexing is active
+- Default `fileLimit` raised from 1000 to 5000 (language expansion makes larger repos viable)
+- `_meta` envelope included in all tool responses (previously only retrieval tools); fields: `timing_ms`, `tokens_saved`, `total_tokens_saved`, `cost_avoided`
+
+---
+
+## [1.0.0] - 2026-04-26
+
+This is the first stable release of PureContext MCP. The public tool API is now under
+semver: breaking changes require a major version bump, new tools and fields increment
+the minor version, and bug fixes increment the patch version.
+
+### Added
+
+**Core symbol indexing (TypeScript and JavaScript)**
+- Tree-sitter AST parsing via WASM bindings (`web-tree-sitter`) — no native compilation required for the parser itself
+- Extracts functions, classes, methods, constants, types, interfaces, and enums with one-line signatures
+- Deterministic symbol IDs (SHA-256 of `filePath:name:kind`) for stable cross-session references
+- SQLite storage (`better-sqlite3`) with four tables: `symbols`, `files`, `dep_edges`, `repos`
+- Incremental re-indexing via chokidar file watcher with debounce
+
+**Language support (16 languages)**
+- TypeScript and JavaScript (full symbol + import extraction)
+- Python, Go, Rust, Java, C, C++, C#, Swift, Kotlin, Dart
+- Elixir, Haskell, Scala, R
+- PHP, Lua, Ruby
+
+**Framework adapters (20+ frameworks)**
+- Vue 3 (SFC `<script setup>`, composables, components)
+- Nuxt 3 (pages, layouts, composables, server routes, plugins)
+- React and Next.js (components, hooks, server/client components, API routes)
+- Angular (components, services, pipes, guards, modules, directives)
+- Express and Fastify (routes, middleware, plugins)
+- Django, FastAPI, Flask (views, serializers, models, routers, dependencies)
+- SQLAlchemy and Prisma (models, schemas, migrations)
+- Axum and Actix-web (handlers, middleware, extractors)
+- Echo, Fiber, Gin (handlers, middleware, groups)
+- Spring and Hibernate (controllers, services, repositories, entities)
+
+**MCP tool surface (12 tools)**
+- `index_folder` — index a project directory
+- `resolve_repo` — resolve a path to its repo ID
+- `list_repos` — list all indexed repositories
+- `search_symbols` — search by name fragment with kind and path filters
+- `get_symbol_source` — retrieve raw source by byte offsets
+- `get_file_outline` — all symbols in a file with signatures
+- `get_repo_outline` — all files with top-level symbols
+- `get_file_tree` — directory tree with file counts
+- `get_context_bundle` — transitive forward-walk from a symbol
+- `get_blast_radius` — reverse-walk to find all dependents
+- `find_importers` — direct importers of a file
+- `find_dead_code` — exported symbols that nothing imports
+
+**Dependency graph**
+- Import resolution with tsconfig path alias support
+- Forward (context bundle) and reverse (blast radius) BFS traversal
+- Dead code detection across the entire project graph
+
+**FTS5 keyword search with relevance ranking**
+- Full-text search over symbol names and signatures
+- camelCase query preprocessor (`getUserById` → `get user by id`)
+- Hyphen-aware tokenization
+- Relevance ranker: exact name match → prefix match → content match
+
+**Semantic search — HNSW vector index**
+- Optional embedding-based symbol search via `hnswlib-wasm`
+- Configurable embedding provider (Anthropic, OpenAI, or none)
+- Index persists alongside the SQLite database
+
+**Token savings tracker**
+- Each tool response includes `_tokenEstimate` so agents can gauge context size
+- Cumulative session savings reported by `list_repos`
+
+**Multi-tenant rate limiting**
+- Per-client request quotas configurable in `config.json`
+- Token bucket algorithm with burst allowance
+
+**Web UI**
+- Vite + Vue 3 dashboard served from the MCP process
+- Symbol search, file outline, dependency graph visualisation
+- 28 Playwright end-to-end tests
+
+**Worker thread pool for enterprise repos**
+- Parallel tree-sitter parsing across a configurable thread pool
+- Designed for 10k–50k file codebases
+- Graceful degradation to single-threaded mode when the pool is unavailable
+
+**npm release infrastructure**
+- `prebuildify` prebuilt binaries for Node 18/20/22 × Windows/macOS/Linux
+- GitHub Actions CI: 9-job matrix (3 OS × 3 Node versions) on every push and PR
+- Release workflow: prebuild + publish triggered by `v*` tags
+- `files` allowlist in `package.json` — published package < 20 MB
+- `scripts/check-sqlite.js` postinstall canary with actionable error message
+- `scripts/verify-package.sh` pre-release verification helper
+
+**Public launch polish**
+- `--health` flag — checks prerequisites (grammars, SQLite, index directory) and exits with JSON output; non-zero exit code on any failure
+- Actionable error messages throughout: missing grammar files, SQLite open failures, and config validation all produce human-readable guidance instead of raw stack traces
+- Opt-in telemetry — reports anonymised usage counts (tool invocations, file counts); disabled by default, enabled via `telemetry.enabled: true` in config
+
+**Team and cloud features**
+- HTTP/SSE transport — start the server with `--transport http` (or `--transport both` for stdio + HTTP simultaneously); port and bind address configurable via `--port`/`--host` or `config.json`
+- API key management — `purecontext-mcp keys create/list/revoke` CLI; keys stored as bcrypt hashes, shown once on creation; format `pctx_<workspaceId>_<24-char-random>_<checksum>`
+- Workspace support — logical namespaces that group repos and API keys; managed via the admin key (`PCTX_ADMIN_KEY` env var)
+- Docker deployment — official `purecontext/purecontext-mcp` image; `docker-compose.yml` included in the repo; `/health` HTTP endpoint for container health checks
+
+### Changed
+
+- Minimum Node.js version: **18.0.0** (uses native `fetch`, `worker_threads`, `structuredClone`)
+- Default `fileLimit` raised from 500 to 1000
+
+### Fixed
+
+- `web-tree-sitter` character-vs-byte offset bug in handler text extraction (all language handlers now use byte offsets throughout)
+- Forward-slash normalisation for file paths stored in SQLite (Windows compatibility)
+- FTS5 hyphen tokenization — hyphens in symbol names are now indexed correctly
+
+---
+
+## [0.1.0] - 2026-04-10
+
+Initial internal release. Core TypeScript/JavaScript indexing, SQLite storage, and MCP stdio transport.

package/docs/01-introduction.md

@@ -0,0 +1,69 @@
+# Introduction
+
+
+## What is PureContext MCP?
+
+PureContext MCP is a **token-efficient source code navigation server** for AI agents. Instead of reading entire files, AI agents can retrieve exactly the symbols they need — functions, classes, methods, routes, and more — saving 90–98% of context tokens.
+
+It implements the **Model Context Protocol (MCP)** so it works natively with Claude Code and any other MCP-compatible AI client.
+
+## The token efficiency problem
+
+When an AI agent wants to understand a `validateToken` function inside an 800-line file, the naive approach is to read the entire file. That costs roughly 2,000 tokens just to locate one 45-line function.
+
+With PureContext, the agent asks for `validateToken` by name and gets back those 45 lines — roughly 150 tokens. The rest of the file is never loaded.
+
+```
+Without PureContext:  800-line file → ~2,000 tokens
+With PureContext:     45-line symbol → ~150 tokens
+                      Savings: 93%
+```
+
+This compounds quickly. A typical agent conversation that touches 20 symbols across 10 files saves hundreds of thousands of tokens per session.
+
+## How PureContext solves it
+
+PureContext builds a **structured index** of your codebase using tree-sitter AST parsing:
+
+1. **Index** — Scan the project, parse each file with a tree-sitter grammar, extract every symbol (functions, classes, routes, components…) with its byte offsets, signature, and docstring.
+2. **Store** — Write structured symbol metadata to a SQLite database. Build a dependency graph from import/require statements.
+3. **Serve** — Expose MCP tools so AI agents can search by name, retrieve source, traverse dependencies, and explore the project structure — all without reading whole files.
+
+## Key concepts
+
+| Term | Meaning |
+|------|---------|
+| **repo** | An indexed project directory. Identified by a deterministic `repoId`. |
+| **symbol** | A named, addressable code entity: function, class, method, route, component, etc. |
+| **kind** | The category of a symbol: `function`, `class`, `method`, `route`, `component`, `hook`, and more. |
+| **signature** | A one-line human-readable declaration: `function validateToken(token: string): boolean` |
+| **summary** | A one-line description, sourced from docstring → framework inference → AI → signature fallback. |
+| **repoId** | 16-char hex, deterministic: `SHA-256(absolutePath).slice(0, 16)` |
+| **symbolId** | 16-char hex, deterministic: `SHA-256(filePath:name:kind).slice(0, 16)` |
+| **dep edge** | An import relationship: file A imports file B. Used to build the dependency graph. |
+
+## Key capabilities
+
+- Index TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, Kotlin, C, C++, Lua, Dart, Swift, Elixir, Haskell, Scala, R, Bash, Terraform, Protobuf, GraphQL, and 10 more — **34 languages total**
+- Framework-aware extraction: Vue, React, Nuxt, Next.js, Angular, NestJS, Express, Fastify, Django, Flask, FastAPI, Gin, Rails, Laravel, Spring Boot, and more
+- Dependency graph: find what a symbol depends on (`get_context_bundle`) and what depends on it (`get_blast_radius`)
+- Full-text search (FTS5) and semantic search (HNSW vector index) for finding code by name or meaning
+- Web UI for visual codebase exploration — graph viewer, heatmap, symbol timeline
+- Multi-tenant hosting for team deployments
+- Git integration: symbol-level history, churn metrics, diff analysis
+- Cross-repo search across multiple indexed projects
+
+## Who is this for?
+
+- **Developers using Claude Code or other AI agent locally** — index your project once, then use PureContext tools in every conversation to navigate code without burning context tokens.
+- **Teams with a shared codebase** — deploy PureContext as a shared server so everyone queries the same index. No per-developer re-indexing.
+- **AI application developers** — use the MCP API directly to build agents that navigate source code efficiently.
+
+## What PureContext is not
+
+PureContext is a navigation and indexing layer, not a general-purpose tool:
+
+- Not a code editor or IDE
+- Not a runtime debugger or test runner
+- Not a full language server (no type-checking, no completions)
+- Not a replacement for reading code — it makes targeted reading fast and cheap

package/docs/02-installation.md

@@ -0,0 +1,267 @@
+# Installation
+
+
+## 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` (remote repo cloning) |
+
+## Install via npm (recommended)
+
+```bash
+npm install -g purecontext-mcp
+```
+
+After this, `purecontext-mcp` is available as a global command.
+
+If you prefer not to install globally, use `npx` to run without installing:
+
+```bash
+npx purecontext-mcp
+```
+
+`npx` downloads the package on first use and caches it. This is the recommended approach for most AI client integrations because it picks up new versions automatically without a manual upgrade step.
+
+## Prebuilt binaries
+
+PureContext uses `better-sqlite3` for SQLite access. Pre-built native binaries are bundled for:
+
+| Platform | Node 18 | Node 20 | Node 22 |
+|----------|---------|---------|---------|
+| Windows x64 | ✓ | ✓ | ✓ |
+| macOS x64 | ✓ | ✓ | ✓ |
+| macOS arm64 | ✓ | ✓ | ✓ |
+| Linux x64 | ✓ | ✓ | ✓ |
+| Linux arm64 | ✓ | ✓ | ✓ |
+
+When a prebuilt binary matches your platform, `npm install` completes without any native compilation. No Python, no `node-gyp`, no build tools needed.
+
+If your platform/Node combination is not in the table above, `npm install` will attempt a native compile. You will need:
+- Python 3.x
+- A C++ compiler (MSVC on Windows, clang/gcc on macOS/Linux)
+- `node-gyp`: `npm install -g node-gyp`
+
+---
+
+## Connecting to your AI client
+
+PureContext works with any MCP-compatible AI client. Choose the setup that matches your environment.
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add purecontext-mcp -- npx purecontext-mcp
+```
+
+Verify:
+
+```bash
+claude mcp list
+# purecontext-mcp   connected   npx purecontext-mcp
+```
+
+### Claude Desktop
+
+Edit `~/.claude/claude_desktop_config.json` (create it if it doesn't exist):
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "npx",
+      "args": ["purecontext-mcp"]
+    }
+  }
+}
+```
+
+If you installed globally (`npm install -g purecontext-mcp`), you can use the binary directly:
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "purecontext-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving the file.
+
+### Cursor
+
+Create or edit `.cursor/mcp.json` in your project directory for a project-scoped connection, or `~/.cursor/mcp.json` for a global one:
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "npx",
+      "args": ["purecontext-mcp"]
+    }
+  }
+}
+```
+
+Reload the Cursor window after saving (`Ctrl+Shift+P` → "Developer: Reload Window").
+
+### Windsurf
+
+Open Windsurf Settings and navigate to the MCP section, or edit the MCP configuration file directly:
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "npx",
+      "args": ["purecontext-mcp"]
+    }
+  }
+}
+```
+
+### VS Code (with MCP support)
+
+Create `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "purecontext": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["purecontext-mcp"]
+    }
+  }
+}
+```
+
+### Connecting to a shared team server (HTTP)
+
+If your team runs a shared PureContext server, connect with an HTTP transport instead of launching a local process. The config format is the same across all clients — only the transport section changes:
+
+**Claude Code CLI:**
+
+```bash
+claude mcp add purecontext-shared \
+  --transport http \
+  --url https://purecontext.yourcompany.com/mcp/sse \
+  --header "Authorization: Bearer pctx_yourpersonalkey"
+```
+
+**Claude Desktop / Cursor / Windsurf (config file):**
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "transport": "http",
+      "url": "https://purecontext.yourcompany.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer pctx_yourpersonalkey"
+      }
+    }
+  }
+}
+```
+
+Your API key is issued by your team's PureContext administrator. See [Team Setup](15-team-setup.md) for how to deploy and manage a shared server.
+
+---
+
+## Teaching your AI agent to use PureContext well
+
+Installing PureContext gives your AI agent access to the tools. Adding the agent instructions tells it *how* to use them efficiently — which tool to pick for each situation, in what order to call them, and what patterns to avoid.
+
+Two instruction files are provided at the repository root:
+
+**`AGENT_INSTRUCTIONS_SHORT.md`** — A compact reference (~2 KB). Covers the mandatory first step, the complete tool selection table, the core rules, and the most common usage patterns. Use this for agents with limited system prompt space or when you want minimal overhead.
+
+**`AGENT_INSTRUCTIONS.md`** — The full reference (~15 KB). Adds detailed parameter notes, every usage pattern, known limitations, decision trees, and anti-patterns. Use this when you want the agent to have complete context, especially for complex multi-step workflows.
+
+### Adding instructions to Claude Code
+
+Add the short version to your project's `CLAUDE.md`:
+
+```bash
+cat AGENT_INSTRUCTIONS_SHORT.md >> CLAUDE.md
+```
+
+Or add the full version if the project is large and complex:
+
+```bash
+cat AGENT_INSTRUCTIONS.md >> CLAUDE.md
+```
+
+Claude Code reads `CLAUDE.md` at the start of every session. The instructions become part of every conversation in that project automatically — no need to repeat them.
+
+### Adding instructions to Cursor
+
+Paste the contents of `AGENT_INSTRUCTIONS_SHORT.md` into your Cursor rules file (`.cursorrules` in the project root, or via Cursor Settings → Rules).
+
+### Adding instructions to Windsurf
+
+Paste the contents into your Windsurf workspace memory or rules configuration.
+
+### Adding instructions to any other agent
+
+The files are plain Markdown. Paste the contents into whatever system prompt, memory, or rules configuration your agent supports. The short version works well for constrained contexts. The full version is better when you can afford the space.
+
+### What the instructions do
+
+Without them, an AI agent given access to PureContext may default to reading entire files (wasting tokens) rather than using `search_symbols`, or may not know to call `list_repos` first to get the `repoId` required by every tool. The instructions encode the correct workflow: check if indexed → search by name or meaning → retrieve source only for what you'll use.
+
+---
+
+## Verifying the installation
+
+```bash
+purecontext-mcp --version
+# 1.x.x
+
+purecontext-mcp config --check
+# ✓ Node.js 20.11.0
+# ✓ SQLite (better-sqlite3 9.x)
+# ✓ Grammar: tree-sitter-typescript.wasm
+# ✓ Grammar: tree-sitter-javascript.wasm
+# ... (all 34 grammars)
+# ✓ Config: ~/.purecontext/config.json
+```
+
+`config --check` validates the installation, verifies all grammar files are present, and reports the effective configuration.
+
+## Upgrading
+
+```bash
+npm update -g purecontext-mcp
+```
+
+Index files (SQLite databases) are forward-compatible within a major version. After upgrading from `1.x` to `1.y`, existing indexes continue to work. A major version upgrade (e.g., `1.x` → `2.0`) may require a re-index — the CLI will warn if it detects an incompatible index version.
+
+## Install from source
+
+Use this when contributing, testing unreleased features, or running a local build.
+
+```bash
+git clone <repository-url> purecontext-mcp
+cd purecontext-mcp
+npm install
+npm run build
+npm link   # makes 'purecontext-mcp' available globally from this build
+```
+
+## Uninstalling
+
+```bash
+npm uninstall -g purecontext-mcp
+```
+
+This removes the binaries. Index files and configuration are not removed. To clean everything up:
+
+```bash
+rm -rf ~/.purecontext   # Removes indexes, config, savings stats
+```

package/docs/03-quick-start.md

@@ -0,0 +1,135 @@
+# 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.