purecontext-mcp 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purecontext-mcp",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Token-efficient source code navigation MCP server for AI agents",
   "type": "module",
   "license": "MIT",

package/docs/dev/API_STABILITY.md

@@ -1,319 +0,0 @@
-# PureContext MCP — API Stability Contract
-
-**Version:** 1.0.0  
-**Date:** 2026-04-26
-
-This document defines which parts of the PureContext MCP interface are stable public API and what change policy applies to each.
-
----
-
-## Stability Policy
-
-> "Tool names, required parameters, and top-level response fields will not change in 1.x.
-> Optional parameters and new response fields may be added in minor releases."
-
-| Change type | Version impact |
-|-------------|---------------|
-| Remove or rename a tool | 2.0.0 (major) |
-| Remove or rename a required parameter | 2.0.0 (major) |
-| Remove a top-level response field | 2.0.0 (major) |
-| Change the type or semantics of a stable field | 2.0.0 (major) |
-| Add a new tool | 1.x.0 (minor) |
-| Add an optional parameter | 1.x.0 (minor) |
-| Add a new response field | 1.x.0 (minor) |
-| Bug fix with no API surface change | 1.0.x (patch) |
-
----
-
-## Stable Tools
-
-### `index_folder`
-
-Indexes a project directory. Discovers source files, parses symbols and imports, builds the dependency graph.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `path` | `string` | Absolute path to the project root |
-
-**Optional parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `force` | `boolean` | Re-index even if content hashes are unchanged |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `repoId` | `string` | 16-char hex repo identifier (deterministic) |
-| `filesIndexed` | `number` | Number of files processed |
-| `symbolsExtracted` | `number` | Total symbols found |
-| `durationMs` | `number` | Wall-clock time for the indexing run |
-
----
-
-### `resolve_repo`
-
-Resolves a local path to its `repoId`. Reports whether the project has been indexed.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `path` | `string` | Absolute path to the project root |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `repoId` | `string` | 16-char hex repo identifier, or `null` if not indexed |
-| `indexed` | `boolean` | Whether the project is currently indexed |
-| `lastIndexed` | `string \| null` | ISO 8601 timestamp of last index run |
-
----
-
-### `list_repos`
-
-Lists all indexed repositories.
-
-**Required parameters:** none
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `repos` | `RepoSummary[]` | Array of indexed repo summaries |
-| `repos[].repoId` | `string` | 16-char hex identifier |
-| `repos[].path` | `string` | Absolute path to project root |
-| `repos[].filesIndexed` | `number` | File count at last index |
-| `repos[].lastIndexed` | `string` | ISO 8601 timestamp |
-
----
-
-### `search_symbols`
-
-Searches symbols by name fragment. Returns signatures and summaries without source code.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-| `query` | `string` | Name fragment or FTS5 query |
-
-**Optional parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `kind` | `SymbolKind` | Filter by symbol kind |
-| `filePath` | `string` | Filter to a specific file |
-| `limit` | `number` | Max results (default: 20) |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `symbols` | `SymbolSummary[]` | Matched symbols |
-| `symbols[].id` | `string` | Deterministic symbol ID |
-| `symbols[].name` | `string` | Symbol name |
-| `symbols[].kind` | `string` | Symbol kind |
-| `symbols[].filePath` | `string` | Relative file path |
-| `symbols[].signature` | `string` | One-line signature |
-| `symbols[].summary` | `string` | One-line description |
-| `_tokenEstimate` | `number` | Estimated token count for this response |
-
----
-
-### `get_symbol_source`
-
-Retrieves the raw source of one symbol by ID.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-| `symbolId` | `string` | Symbol ID from `search_symbols` |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `source` | `string` | Raw source text of the symbol |
-| `filePath` | `string` | Relative path to containing file |
-| `startByte` | `number` | Byte offset where symbol starts |
-| `endByte` | `number` | Byte offset where symbol ends |
-| `_tokenEstimate` | `number` | Estimated token count |
-
----
-
-### `get_file_outline`
-
-Returns all symbols defined in a file with signatures and summaries.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-| `filePath` | `string` | Relative path to the file |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `filePath` | `string` | Relative file path (normalised) |
-| `symbols` | `SymbolSummary[]` | All symbols in the file |
-| `_tokenEstimate` | `number` | Estimated token count |
-
----
-
-### `get_repo_outline`
-
-Returns all files with their top-level symbols.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-
-**Optional parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `limit` | `number` | Max files to return (default: 100) |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `files` | `FileOutline[]` | Per-file symbol summaries |
-| `files[].filePath` | `string` | Relative file path |
-| `files[].symbols` | `SymbolSummary[]` | Top-level symbols |
-| `_tokenEstimate` | `number` | Estimated token count |
-
----
-
-### `get_file_tree`
-
-Returns the directory tree of an indexed project with file counts per directory.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `tree` | `DirectoryNode` | Nested directory tree |
-| `tree.name` | `string` | Directory or file name |
-| `tree.type` | `'dir' \| 'file'` | Node type |
-| `tree.children` | `DirectoryNode[]` | Child nodes (dirs only) |
-| `_tokenEstimate` | `number` | Estimated token count |
-
----
-
-### `get_context_bundle`
-
-Forward-walks the dependency graph from a symbol and returns everything needed to understand it (transitive imports).
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-| `symbolId` | `string` | Starting symbol ID |
-
-**Optional parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `maxDepth` | `number` | Max traversal depth (default: 3) |
-| `maxTokens` | `number` | Stop collecting when estimate exceeds this |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `symbols` | `SymbolSummary[]` | All symbols in the bundle |
-| `files` | `string[]` | Distinct files touched |
-| `_tokenEstimate` | `number` | Estimated token count |
-
----
-
-### `get_blast_radius`
-
-Reverse-walks from a symbol to find all files that (transitively) import it. Use before modifying or deleting a symbol.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-| `symbolId` | `string` | Starting symbol ID |
-
-**Optional parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `maxDepth` | `number` | Max traversal depth (default: 5) |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `importers` | `string[]` | Files that transitively import the symbol |
-| `count` | `number` | Total importer count |
-| `_tokenEstimate` | `number` | Estimated token count |
-
----
-
-### `find_importers`
-
-Returns the direct importers of a file with their symbols.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-| `filePath` | `string` | Relative path to the file |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `importers` | `ImporterEntry[]` | Direct importers |
-| `importers[].filePath` | `string` | Importer file path |
-| `importers[].importedNames` | `string[]` | Names imported from the target |
-| `_tokenEstimate` | `number` | Estimated token count |
-
----
-
-### `find_dead_code`
-
-Returns exported symbols in files that nothing else imports.
-
-**Required parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `repoId` | `string` | Target repository |
-
-**Optional parameters:**
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `limit` | `number` | Max symbols to return (default: 50) |
-
-**Stable response fields:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `symbols` | `SymbolSummary[]` | Potentially dead exported symbols |
-| `_tokenEstimate` | `number` | Estimated token count |
-
----
-
-## Stable Configuration Fields
-
-Config file: `~/.purecontext/config.json`
-
-The following fields are stable in 1.x:
-
-| Field | Type | Default | Notes |
-|-------|------|---------|-------|
-| `indexDir` | `string` | `~/.purecontext/indexes/` | Storage location for SQLite index files |
-| `fileLimit` | `number` | `1000` | Max files indexed per project |
-| `watchDebounceMs` | `number` | `2000` | File watcher debounce window (ms) |
-| `excludePatterns` | `string[]` | `[]` | Additional glob patterns to exclude |
-| `adapters` | `'auto' \| 'none' \| string[]` | `'auto'` | Framework adapter activation |
-
-The `ai.*` configuration group is **not stable** in 1.x — it may change as AI summarization features mature.
-
----
-
-## Stable Symbol Kinds
-
-The following `SymbolKind` values are stable in 1.x:
-
-`function` · `class` · `method` · `const` · `type` · `interface` · `enum` · `component` · `composable` · `hook` · `route` · `decorator` · `middleware`
-
-New kinds may be added in minor releases. Clients should handle unknown kinds gracefully.

package/docs/dev/DECISIONS.md

@@ -1,22 +0,0 @@
-# Architecture & Product Decisions
-
-This file records significant decisions that aren't obvious from the code — the *why* behind choices that will matter when revisiting them later.
-
----
-
-## 2026-05-02 — Workspace plan limits temporarily disabled
-
-**Decision:** Free-plan repo and file limits are set to near-unlimited values until paid plans launch.
-
-- `FREE_REPO_LIMIT` = 999 (real value: 3)
-- `FREE_FILE_LIMIT` = 10,000,000 (real value: 10,000)
-
-**Why:** There is no paid plan yet and no `purecontext.dev/pricing` page to send users to. Enforcing hard limits while everything is free would frustrate users who hit a wall with no way to upgrade.
-
-**What to do when paid plans launch (Phase 19):**
-1. Restore real limits in `src/core/index-manager.ts`
-2. Build and deploy `purecontext.dev/pricing` 
-3. Update error messages in `src/core/errors.ts` (`WorkspaceLimitError`) — the upgrade URL is already wired in, it just needs a live destination
-4. Wire up Stripe/Paddle for plan upgrades
-
-The DB schema, admin API, and plan tiers (`free` / `team` / `enterprise`) are already fully implemented — limit enforcement is the only missing piece.

package/docs/dev/DOCUMENTATION_PLAN.md

@@ -1,113 +0,0 @@
-# PureContext MCP — Documentation Plan
-
-This file is the master plan and coverage tracker for the user-facing documentation.
-It lives in `docs/user-manual/` — **separate from development phase task files** (`docs/PHASE*_TASKS.md`).
-
-## How to use this file
-
-- **When writing docs:** find the section below, set its status to `draft` → `written`, fill in the file.
-- **When a new dev phase ships:** add its phase number to the relevant rows in the coverage table, set status back to `needs-update`, and note what changed in the "Notes" column.
-- **When planning new phases:** add new rows to the coverage table before writing any code, so the documentation gap is visible from day one.
-
-## Status legend
-
-| Status | Meaning |
-|--------|---------|
-| `planned` | Section identified, file stub created, no content yet |
-| `draft` | Content started, incomplete or unreviewed |
-| `written` | Content complete and reviewed |
-| `needs-update` | Written but a new phase added features that must be reflected |
-
----
-
-## Coverage Table
-
-| # | Doc File | Section Title | Status | Phases Covered | Notes |
-|---|----------|---------------|--------|----------------|-------|
-| 01 | `01-introduction.md` | What is PureContext MCP? | written | 1 | Core concept, token efficiency pitch, key capabilities overview |
-| 02 | `02-installation.md` | Installation | written | 1, 16 | npm install, from source, prebuilt binaries, Node version matrix |
-| 03 | `03-quick-start.md` | Quick Start | written | 1, 16, 17 | First index, first search, connect to Claude Code in 3 steps |
-| 04 | `04-configuration.md` | Configuration Reference | written | 1, 17, 18 | config.json schema, all fields, env vars, CLI config commands |
-| 05 | `05-cli-reference.md` | CLI Reference | written | 1, 17 | All CLI flags: --init, --check, --health, --server, transport flags |
-| 06 | `06-tools-reference.md` | MCP Tools Reference | written | 1–3, 8, 19, 20, 21, 23, 24, 25 | Every tool: inputs, outputs, examples; grouped by category |
-| 07 | `07-language-support.md` | Language Support | written | 1, 4–7, 9, 22 | All 34 languages; what is extracted per language; grammar notes |
-| 08 | `08-framework-adapters.md` | Framework Adapters | written | 4, 5, 10 | Vue, React, Nuxt, Next.js, Angular, NestJS, Express, Django, etc. |
-| 09 | `09-dependency-graph.md` | Dependency Graph Tools | written | 3 | context_bundle, blast_radius, find_importers, find_dead_code |
-| 10 | `10-semantic-search.md` | Semantic Search | written | 11 | HNSW vector index, embeddings, when to use vs keyword search |
-| 11 | `11-search-quality.md` | Search Quality & Ranking | written | 14 | FTS5, camelCase splitting, relevance ranking, query tips |
-| 12 | `12-ai-summarization.md` | AI Summarization | written | 2, 20 | Providers (Anthropic, OpenAI, Gemini Flash), batch mode, cost tips |
-| 13 | `13-token-savings.md` | Token Savings Tracker | written | 8 | How savings are measured, reading the stats, interpreting results |
-| 14 | `14-transport-modes.md` | Transport Modes | written | 1, 18 | stdio vs HTTP/SSE; when to use each; connection examples |
-| 15 | `15-team-setup.md` | Team Setup & Multi-Tenant | written | 12, 18 | Workspaces, API keys, rate limits, shared server walkthrough |
-| 16 | `16-docker.md` | Docker Deployment | written | 18 | docker run, docker-compose, volume mounts, env vars |
-| 17 | `17-web-ui.md` | Web UI | written | 13, 26 | Graph viewer, search UI, heatmap, symbol timeline, coverage overlay, multi-repo workspace |
-| 18 | `18-git-history.md` | Git & History Integration | written | 24 | Symbol history, diff analysis, churn metrics, PR analysis |
-| 19 | `19-cross-repo.md` | Cross-Repo Intelligence | written | 23 | Multi-repo search, code similarity, cross-repo deps, MCP Resources |
-| 20 | `20-architecture-analysis.md` | AI-Powered Architecture Analysis | written | 25 | Quality metrics, anti-pattern detection, arch docs, refactoring detector |
-| 21 | `21-ecosystem-tools.md` | Ecosystem & Data Tools | written | 21 | Context providers, dbt integration, search_columns, OpenAPI/Swagger, SQL handler |
-| 22 | `22-distribution.md` | Distribution & Platform | written | 27 | Index export/import, public registry, webhooks, GitHub Actions, VS Code extension |
-| 23 | `23-performance.md` | Performance & Scalability | written | 15 | Worker thread pool, large repo tuning, memory usage, benchmarks |
-| 24 | `24-security.md` | Security | written | 12, 18 | API key model, rate limiting, workspace isolation, self-hosting hardening |
-| 25 | `25-architecture-overview.md` | Architecture Overview | written | 1–3 | Three-layer design, data flow, SQLite schema, tree-sitter pipeline |
-| 26 | `26-troubleshooting.md` | Troubleshooting | written | 1, 17 | Common errors, --health output, debug logging, known issues |
-| 27 | `27-api-stability.md` | API Stability & Changelog | written | 16 | Semver policy, public API contract, link to CHANGELOG.md |
-
----
-
-## Phase → Documentation mapping
-
-Use this reverse index when a new dev phase ships to find which doc files need updating.
-
-| Phase | Focus | Doc files to update |
-|-------|-------|---------------------|
-| 1 | Core engine, stdio MCP, JS/TS, basic tools | 01, 02, 03, 04, 05, 06, 14, 25, 26 |
-| 2 | AI summarization (first pass) | 12 |
-| 3 | Dependency graph tools | 06, 09 |
-| 4 | Vue adapter | 07, 08 |
-| 5 | React adapter | 07, 08 |
-| 6 | Language expansion (Python, Go, Rust, Java, C#, PHP, Ruby, Kotlin) | 07 |
-| 7 | Language expansion (C, C++, Lua, Dart, Swift) | 07 |
-| 8 | Token savings tracker | 06, 13 |
-| 9 | Languages: Elixir, Haskell, Scala, R | 07 |
-| 10 | Adapters: Rust/Java web, ORM | 08 |
-| 11 | Semantic search (HNSW) | 06, 10 |
-| 12 | Rate limiting & multi-tenant | 15, 24 |
-| 13 | Web UI | 17 |
-| 14 | Search quality (FTS5 + ranking) | 06, 11 |
-| 15 | Performance & scalability | 23 |
-| 16 | npm release readiness, prebuilt binaries | 02, 27 |
-| 17 | Public launch polish (fileLimit, errors, --health, telemetry) | 03, 04, 05, 26 |
-| 18 | Team/cloud (API keys, workspaces, Docker, MCP-HTTP) | 04, 14, 15, 16, 24 |
-| 19 | Missing core tools (find_references, get_file_content, get_symbols, invalidate_cache) | 06 |
-| 20 | Tool capability enhancements (debug mode, context_lines/verify, GitHub API, Gemini Flash) | 06, 12 |
-| 21 | Ecosystem & data tools (context provider, dbt, search_columns, OpenAPI, SQL) | 06, 21 |
-| 22 | Language coverage expansion (Bash, Terraform, Protobuf, GraphQL + 10 more) | 07 |
-| 23 | Cross-repo intelligence (multi-repo search, similarity, MCP Resources) | 06, 19 |
-| 24 | Git & history integration (symbol history, diff analysis, churn) | 06, 18 |
-| 25 | AI-powered architecture analysis (metrics, antipatterns, arch docs, refactoring) | 06, 20 |
-| 26 | Enhanced Web UI (heatmap, timeline, coverage, multi-repo, advanced graph) | 17 |
-| 27 | Distribution & platform (export/import, registry, webhooks, Actions, VS Code) | 22 |
-
----
-
-## Adding a new development phase
-
-When a new phase is planned, do the following **before** writing any code:
-
-1. Add a row to the **Phase → Documentation mapping** table above.
-2. For each affected doc file, set its status to `needs-update` (or `planned` if it's a brand-new section).
-3. If the phase introduces a wholly new feature area with no existing doc section, add a new row to the **Coverage Table** and create a stub file in `docs/user-manual/`.
-4. After the phase ships, update the content in each affected doc file and flip the status to `written`.
-
----
-
-## Existing documentation to migrate / reconcile
-
-| File | Notes |
-|------|-------|
-| `user-manual.md` (project root) | 1,564-line flat file covering Phases 1–18. Source of truth for sections 01–16. Migrate content into per-topic files then remove or redirect. |
-| `README.md` (project root) | Tool reference table, team setup, config table. Overlaps with 06, 04, 15. Keep a short README pointing into `docs/user-manual/`. |
-| `docs/SELF_HOSTING.md` | Should feed into `16-docker.md` and `24-security.md`. |
-| `docs/TEAM_SETUP.md` | Should feed into `15-team-setup.md`. |
-| `docs/TELEMETRY.md` | Should be summarized in `04-configuration.md`. |
-| `docs/API_STABILITY.md` | Should be summarized/linked in `27-api-stability.md`. |