purecontext-mcp 1.5.0 → 1.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/BENCHMARKS.md +153 -0
  2. package/FULL-INSTALLATION-GUIDE.md +341 -0
  3. package/README.md +73 -15
  4. package/USER-GUIDE.md +21 -21
  5. package/dist/version.d.ts +1 -1
  6. package/dist/version.js +1 -1
  7. package/docs/02-installation.md +43 -317
  8. package/docs/07-language-support.md +73 -50
  9. package/docs/08-framework-adapters.md +7 -2
  10. package/docs/15-team-setup.md +70 -200
  11. package/docs/17-web-ui.md +73 -93
  12. package/docs/README.md +60 -39
  13. package/package.json +3 -3
  14. package/user-manual.md +0 -2466
package/docs/17-web-ui.md CHANGED
@@ -1,68 +1,66 @@
1
- # Web UI
1
+ # Web UI — Reference
2
2
 
3
+ This is the reference page: build commands, configuration flags, keyboard shortcuts, heatmap metrics, and graph-viewer controls.
3
4
 
4
- 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.
5
+ For the **user-friendly tour** — when to use the UI vs the chat, what each view is good for, workflow examples — see [`WEB-UI.md`](../WEB-UI.md) at the project root.
5
6
 
6
7
  ---
7
8
 
8
- ## Accessing the Web UI
9
+ ## Activating the UI
9
10
 
10
- The Web UI is available at `http://localhost:3000` (or your server URL) when running in HTTP mode:
11
+ The UI is served by the same process as the MCP server, but only when HTTP transport is active:
11
12
 
12
13
  ```bash
13
14
  purecontext-mcp --transport http --port 3000
15
+ # Web UI: http://localhost:3000
16
+ # MCP endpoint: http://localhost:3000/mcp/sse
14
17
  ```
15
18
 
16
- Then open `http://localhost:3000` in a browser.
17
-
18
- ### Building the UI
19
-
20
- The UI is pre-built in the npm package. For development or rebuilding from source:
19
+ The UI is pre-built into the npm package. For source builds:
21
20
 
22
21
  ```bash
23
22
  npm run build:ui # build only the UI
24
23
  npm run build # build everything
25
- npm run dev # watch mode: TypeScript + Vite dev server with hot reload
24
+ npm run dev # watch mode: TypeScript + Vite dev server with HMR
26
25
  ```
27
26
 
28
27
  ---
29
28
 
30
- ## Repository browser
29
+ ## Configuration
31
30
 
32
- - List all indexed repositories with symbol counts, file counts, and language breakdown
33
- - Collapsible file tree with file type icons
34
- - Click any file to open its symbol outline
35
-
36
- ---
31
+ | Field | Default | Description |
32
+ |-------|--------:|-------------|
33
+ | `webUI.enabled` | `true` | Set `false` to disable UI even in HTTP mode (API-only) |
34
+ | `webUI.theme` | `"system"` | `"light"` / `"dark"` / `"system"` default; users can override |
35
+ | `webUI.basePath` | `"/"` | Mount the UI under a subpath (e.g., `/purecontext`) |
36
+ | `webUI.maxGraphNodes` | `500` | Hard cap on graph viewer node count for performance |
37
37
 
38
- ## Symbol search
39
-
40
- - Real-time search with 300ms debounce — results appear as you type
41
- - Filter by: symbol kind, language, file path pattern
42
- - Keyboard navigation: arrow keys to move through results, Enter to open
43
- - Query term highlighting in results
44
- - Switches between keyword and semantic mode (if semantic search is enabled)
38
+ When deployed behind a reverse proxy at a subpath, set `webUI.basePath` to match the proxy path.
45
39
 
46
40
  ---
47
41
 
48
- ## Symbol viewer
42
+ ## Keyboard shortcuts
49
43
 
50
- - Syntax-highlighted source code (powered by Shiki — VS Code-quality highlighting)
51
- - Line numbers with anchors (shareable URLs)
52
- - Light/dark theme toggle (preference persisted in localStorage)
53
- - **Related symbols panel**: importers, dependencies, same-file symbols
44
+ | Shortcut | Action |
45
+ |----------|--------|
46
+ | `/` | Focus search bar |
47
+ | `↑` / `↓` | Navigate search results |
48
+ | `Enter` | Open selected symbol |
49
+ | `Esc` | Close panels / clear search |
50
+ | `G` | Open graph view for current symbol |
51
+ | `B` | Show blast radius for current symbol |
52
+ | `H` | Toggle heatmap overlay |
53
+ | `T` | Toggle light/dark theme |
54
54
 
55
55
  ---
56
56
 
57
- ## Dependency graph viewer
58
-
59
- An interactive force-directed graph of file and symbol dependencies.
57
+ ## Graph viewer
60
58
 
61
59
  ### Controls
62
60
 
63
61
  | Action | Control |
64
62
  |--------|---------|
65
- | Pan | Click and drag |
63
+ | Pan | Click and drag background |
66
64
  | Zoom | Scroll wheel |
67
65
  | Fit to view | Double-click background |
68
66
  | Select node | Click |
@@ -70,88 +68,70 @@ An interactive force-directed graph of file and symbol dependencies.
70
68
  | Forward walk | Enable "Dependencies" mode |
71
69
  | Reverse walk | Enable "Importers" mode |
72
70
 
73
- ### Layout options
74
-
75
- - **Force-directed** (default) — physics simulation, nodes cluster by connectivity
76
- - **Hierarchical** — root at top, dependencies flow downward
77
- - **Radial** — selected node at center, connected nodes radiate outward
71
+ ### Layouts
78
72
 
79
- ### Depth slider
73
+ | Layout | Behavior |
74
+ |--------|----------|
75
+ | Force-directed (default) | Physics simulation; nodes cluster by connectivity |
76
+ | Hierarchical | Root at top, dependencies flow downward |
77
+ | Radial | Selected node at center; connected nodes radiate outward |
80
78
 
81
- Adjust traversal depth (1–5 hops). Higher depth reveals transitive dependencies but may produce large graphs.
79
+ ### Filters and overlays
82
80
 
83
- ### Blast radius view
84
-
85
- Switch to "Blast radius" mode to see everything that depends on the selected node — color gradient from red (direct impact) to yellow (indirect).
81
+ | Feature | Description |
82
+ |---------|-------------|
83
+ | Depth slider | Traversal depth 1–5 hops |
84
+ | Language filter | Show only nodes of a specific language |
85
+ | Kind filter | Show only files/symbols of a specific kind |
86
+ | Cycle detection | Highlight circular dependency cycles in red |
87
+ | Blast-radius mode | Color gradient: red (direct impact) → yellow (indirect) |
88
+ | Export | Save graph as SVG or PNG |
89
+ | Minimap | Overview panel for large graphs |
86
90
 
87
91
  ---
88
92
 
89
93
  ## Architecture heatmap
90
94
 
91
- An overlay on the file tree that color-codes files by a selected metric:
92
-
93
- | Metric | Color scale | Use case |
94
- |--------|-------------|----------|
95
- | Churn | blue (stable) → red (high churn) | Identify high-risk files before a refactor |
96
- | Complexity | green → orange → red | Find over-complex files that need attention |
97
- | Quality score | green (high) → red (low) | Prioritize technical debt |
98
- | Test coverage | green (covered) → red (uncovered) | Requires external coverage report |
95
+ Color-codes files by a chosen metric.
99
96
 
100
- Click any cell in the heatmap to open the file's symbol outline.
97
+ | Metric | Color scale | Source |
98
+ |--------|-------------|--------|
99
+ | Churn | blue (stable) → red (high churn) | git log history |
100
+ | Complexity | green → orange → red | per-file cyclomatic complexity |
101
+ | Quality score | green (high) → red (low) | aggregated metrics |
102
+ | Test coverage | green (covered) → red (uncovered) | uploaded lcov file |
101
103
 
102
104
  ---
103
105
 
104
- ## Symbol timeline
106
+ ## Test coverage upload
105
107
 
106
- Per-symbol git history visualized as a timeline. Shows:
107
- - When the symbol was created (first commit where it appears)
108
- - Each commit that modified the symbol (with author, date, message)
109
- - When the symbol was deleted (if applicable)
108
+ The coverage overlay needs an lcov-format report:
110
109
 
111
- Requires git history integration enabled (see [Git & History Integration](18-git-history.md)).
110
+ 1. Run your test suite with coverage output (`vitest --coverage`, `pytest --cov`, `jest --coverage`, etc.)
111
+ 2. Export as lcov: typical output paths are `coverage/lcov.info` or `coverage.info`
112
+ 3. In the UI: Settings → Coverage → Upload lcov file
112
113
 
113
- ---
114
-
115
- ## Test coverage overlay
116
-
117
- Overlays test coverage data on the file tree. Requires an lcov-format coverage report:
118
-
119
- 1. Run your test suite with coverage output (`npx vitest --coverage`, `pytest --cov`, etc.)
120
- 2. Export as lcov: `coverage.info` / `lcov.info`
121
- 3. In PureContext Web UI: Settings → Coverage → Upload lcov file
122
-
123
- Files are color-coded by coverage percentage. Click a file to see line-level coverage in the source viewer.
114
+ Coverage data is stored per workspace and persists across UI sessions.
124
115
 
125
116
  ---
126
117
 
127
- ## Multi-repo workspace
128
-
129
- 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.
118
+ ## URL conventions
130
119
 
131
- ---
120
+ | Pattern | Purpose |
121
+ |---------|---------|
122
+ | `/r/:repoId` | Repository home |
123
+ | `/r/:repoId/f/:filePath` | File outline |
124
+ | `/r/:repoId/s/:symbolId` | Symbol viewer |
125
+ | `/r/:repoId/s/:symbolId#L42` | Symbol viewer with line anchor |
126
+ | `/r/:repoId/graph?root=:symbolId&depth=3` | Graph viewer with preset |
127
+ | `/r/:repoId/heatmap?metric=churn` | Heatmap with preset metric |
132
128
 
133
- ## Advanced graph controls
134
-
135
- Additional controls available in the graph viewer:
136
-
137
- | Feature | Description |
138
- |---------|-------------|
139
- | Language filter | Show only nodes of a specific language |
140
- | Kind filter | Show only files/symbols of a specific kind |
141
- | Cycle detection | Highlight circular dependency cycles in red |
142
- | Export | Save graph as SVG or PNG |
143
- | Minimap | Overview panel for large graphs |
129
+ URLs are stable — link them in PR descriptions or share with teammates.
144
130
 
145
131
  ---
146
132
 
147
- ## Keyboard shortcuts
133
+ ## Related reference
148
134
 
149
- | Shortcut | Action |
150
- |----------|--------|
151
- | `/` | Focus search bar |
152
- | `↑` / `↓` | Navigate search results |
153
- | `Enter` | Open selected symbol |
154
- | `Esc` | Close panels / clear search |
155
- | `G` | Open graph view for current symbol |
156
- | `B` | Show blast radius for current symbol |
157
- | `H` | Toggle heatmap overlay |
135
+ - [Transport Modes](14-transport-modes.md) — required HTTP setup for UI to activate
136
+ - [Git & History Integration](18-git-history.md) — powers the symbol timeline and churn heatmap
137
+ - [Configuration](04-configuration.md) — full `webUI.*` schema
package/docs/README.md CHANGED
@@ -1,71 +1,92 @@
1
- # PureContext MCP — User Manual
1
+ # PureContext MCP — Reference Manual
2
2
 
3
- PureContext MCP indexes your codebase and gives AI agents a way to navigate it without reading entire files. Instead of loading hundreds of lines of code to find one function, Claude (or any other MCP-compatible AI) can search by name, retrieve just the symbol it needs, and understand the dependency chain — all in a fraction of the tokens.
3
+ This is the **reference manual**: parameter-level documentation for every tool, configuration option, language handler, framework adapter, and deployment option.
4
4
 
5
- This manual covers everything from installation through advanced features. Use the sections below to navigate to what you need, or read in order for a full introduction.
5
+ For the **user guide** — narrative explanations, worked examples, and real-world workflows — see [`USER-GUIDE.md`](../USER-GUIDE.md) and the `WHY-PURECONTEXT.md` / `FINDING-CODE.md` / `WORKFLOW-*.md` files at the project root.
6
6
 
7
- ---
7
+ Each row below has two columns: the reference page in this directory, and the user-friendly companion at the project root when one exists.
8
8
 
9
- ## Getting Started
9
+ ---
10
10
 
11
- These three sections get you from zero to a working setup.
11
+ ## Getting started
12
12
 
13
- - [Introduction](01-introduction.md) — What PureContext is, why token efficiency matters, key concepts
14
- - [Installation](02-installation.md) — Install via npm, verify your setup, upgrade and uninstall
15
- - [Quick Start](03-quick-start.md) — Index a project and search your first symbol in minutes
13
+ | Reference | Companion |
14
+ |-----------|-----------|
15
+ | [Introduction](01-introduction.md) — concise spec, glossary, key concepts | [Why PureContext](../WHY-PURECONTEXT.md) — narrative case |
16
+ | [Installation](02-installation.md) — prereqs, support matrix, verify, upgrade | [Full Installation Guide](../FULL-INSTALLATION-GUIDE.md) — per-IDE walkthrough |
17
+ | [Quick Start](03-quick-start.md) — index a project and search in minutes | [Navigating a New Codebase](../NAVIGATING-NEW-CODE.md) — day-one workflow |
16
18
 
17
19
  ---
18
20
 
19
- ## Reference
20
-
21
- Complete reference material for configuration, the CLI, and every MCP tool.
21
+ ## Core reference
22
22
 
23
- - [Configuration](04-configuration.md) — Full `config.json` schema, every field explained, environment variable overrides
24
- - [CLI Reference](05-cli-reference.md) — Every command and flag: `config --init`, `--health`, `--transport`, and more
23
+ - [Configuration](04-configuration.md) — Full `config.json` schema and environment variable overrides
24
+ - [CLI Reference](05-cli-reference.md) — Every command and flag (`config --init`, `--health`, `--transport`, etc.)
25
25
  - [MCP Tools Reference](06-tools-reference.md) — Every tool with inputs, outputs, and examples — grouped by category
26
26
 
27
27
  ---
28
28
 
29
- ## Language & Framework Support
29
+ ## Language and framework support
30
30
 
31
- - [Language Support](07-language-support.md) — All 34 supported languages: what gets indexed and known limitations
32
- - [Framework Adapters](08-framework-adapters.md) — Vue, React, Nuxt, Next.js, Angular, NestJS, Express, Django, Rails, Spring, and 20+ more
31
+ | Reference | Companion |
32
+ |-----------|-----------|
33
+ | [Language Support](07-language-support.md) — symbol-kind matrix, visibility filters, grammar notes | [Language Support](../LANGUAGE-SUPPORT.md) — narrative tour by category |
34
+ | [Framework Adapters](08-framework-adapters.md) — detection rules, extracted kinds, `frameworkMeta` | [Framework Adapters](../FRAMEWORK-ADAPTERS.md) — what each adapter changes in practice |
33
35
 
34
36
  ---
35
37
 
36
- ## Core Features
38
+ ## Core features
37
39
 
38
- - [Dependency Graph Tools](09-dependency-graph.md) — Find what a symbol depends on, what depends on it, and what is dead code
39
- - [Semantic Search](10-semantic-search.md) — Search by meaning rather than name using HNSW vector index
40
- - [Search Quality & Ranking](11-search-quality.md) — How FTS5, camelCase splitting, and relevance ranking work; search tips
41
- - [AI Summarization](12-ai-summarization.md) — Auto-generate symbol descriptions with Anthropic, OpenAI, or Gemini
42
- - [Token Savings Tracker](13-token-savings.md) — See exactly how many tokens (and dollars) PureContext saves per session
40
+ - [Dependency Graph Tools](09-dependency-graph.md) — what a symbol depends on, what depends on it, dead-code detection
41
+ - [Semantic Search](10-semantic-search.md) — HNSW vector index, embedding providers, hybrid mode
42
+ - [Search Quality & Ranking](11-search-quality.md) — FTS5, camelCase splitting, relevance ranking
43
+ - [AI Summarization](12-ai-summarization.md) — provider config, batch sizes, cost model
44
+ - [Token Savings Tracker](13-token-savings.md) — per-session token (and dollar) accounting
45
+
46
+ Companion narratives: [Finding Code](../FINDING-CODE.md), [AI Summaries](../AI-SUMMARIES.md), [AST-Level Search](../AST-SEARCH.md), [Code Intelligence](../CODE-INTELLIGENCE.md).
43
47
 
44
48
  ---
45
49
 
46
50
  ## Deployment
47
51
 
48
- - [Transport Modes](14-transport-modes.md) — stdio (local) vs HTTP/SSE (team/browser); TLS via reverse proxy
49
- - [Team Setup & Multi-Tenant](15-team-setup.md) — Shared server, workspaces, API keys, rate limiting
50
- - [Docker Deployment](16-docker.md) — `docker run`, Docker Compose, volumes, environment variables, health checks
52
+ | Reference | Companion |
53
+ |-----------|-----------|
54
+ | [Transport Modes](14-transport-modes.md) — stdio vs HTTP/SSE, TLS via reverse proxy | — |
55
+ | [Team Setup & Multi-Tenant](15-team-setup.md) — permissions, rate limit, admin API reference | [Using PureContext with a Team](../TEAM-SETUP.md) — narrative deployment |
56
+ | [Docker Deployment](16-docker.md) — image tags, compose, volumes, env vars, healthchecks | — |
57
+
58
+ ---
59
+
60
+ ## Advanced features
61
+
62
+ | Reference | Companion |
63
+ |-----------|-----------|
64
+ | [Web UI](17-web-ui.md) — config flags, keyboard shortcuts, URL conventions | [The Web UI](../WEB-UI.md) — when to leave the chat |
65
+ | [Git & History Integration](18-git-history.md) — symbol history, churn, diff analysis | [Code History](../CODE-HISTORY.md) — narrative |
66
+ | [Cross-Repo Intelligence](19-cross-repo.md) — multi-repo search, similarity, MCP Resources | — |
67
+ | [AI-Powered Architecture Analysis](20-architecture-analysis.md) — metrics, anti-patterns, auto-docs | [Code Health](../CODE-HEALTH.md), [Health Dashboards](../HEALTH-DASHBOARDS.md), [Visualizing Code Structure](../VISUALIZING-CODE.md) |
68
+ | [Ecosystem & Data Tools](21-ecosystem-tools.md) — dbt, OpenAPI handler, SQL handler, column search | — |
69
+ | [Distribution & Platform](22-distribution.md) — export/import, registry, webhooks, GitHub Actions | — |
70
+
71
+ Companion narratives also relevant here: [Making Changes Safely](../SAFE-CHANGES.md), [Understanding Code Relationships](../UNDERSTANDING-RELATIONSHIPS.md), [Refactoring Safely](../REFACTORING-SAFELY.md).
51
72
 
52
73
  ---
53
74
 
54
- ## Advanced Features
75
+ ## Operations and stability
55
76
 
56
- - [Web UI](17-web-ui.md) — Visual graph viewer, heatmap, symbol timeline, test coverage overlay
57
- - [Git & History Integration](18-git-history.md) — Symbol-level commit history, churn metrics, PR diff analysis
58
- - [Cross-Repo Intelligence](19-cross-repo.md) — Search across multiple repos, find similar code, MCP Resources
59
- - [AI-Powered Architecture Analysis](20-architecture-analysis.md) — Quality metrics, anti-pattern detection, auto-generated architecture docs
60
- - [Ecosystem & Data Tools](21-ecosystem-tools.md) — dbt integration, OpenAPI/Swagger handler, SQL handler, column search
61
- - [Distribution & Platform](22-distribution.md) — Index export/import, public registry, webhooks, GitHub Actions, VS Code extension
77
+ - [Performance & Scalability](23-performance.md) — worker thread pool, large-repo tuning, memory
78
+ - [Security](24-security.md) — API key model, workspace isolation, path-traversal protections, hardening
79
+ - [Troubleshooting](26-troubleshooting.md) — common errors, `--health` output, debug logging
80
+ - [Architecture Overview](25-architecture-overview.md) — three-layer design, data flow, SQLite schema
81
+ - [API Stability & Changelog](27-api-stability.md) — semver policy, stable vs experimental tools, version history
62
82
 
63
83
  ---
64
84
 
65
- ## Operations & Reference
85
+ ## End-to-end workflows
86
+
87
+ The user-guide root has narrative walkthroughs for full real-world scenarios:
66
88
 
67
- - [Performance & Scalability](23-performance.md) — Worker thread pool, large repo tuning, memory usage
68
- - [Security](24-security.md) — API key model, workspace isolation, path traversal prevention, hardening checklist
69
- - [Troubleshooting](26-troubleshooting.md) — Common errors, `--health` output, debug logging, re-indexing from scratch
70
- - [Architecture Overview](25-architecture-overview.md) — How PureContext works internally: three-layer design, data flow, SQLite schema
71
- - [API Stability & Changelog](27-api-stability.md) — Semver policy, stable vs experimental tools, version history
89
+ - [Onboarding to a New Codebase](../WORKFLOW-ONBOARDING.md)
90
+ - [Refactoring Legacy Code](../WORKFLOW-REFACTORING.md)
91
+ - [Reviewing a Pull Request](../WORKFLOW-PR-REVIEW.md)
92
+ - [Running a Tech Debt Sprint](../WORKFLOW-TECH-DEBT.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "purecontext-mcp",
3
- "version": "1.5.0",
3
+ "version": "1.5.2",
4
4
  "description": "Token-efficient source code navigation MCP server for AI agents",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -37,13 +37,14 @@
37
37
  "AGENT_REFERENCE.md",
38
38
  "AI-SUMMARIES.md",
39
39
  "AST-SEARCH.md",
40
+ "BENCHMARKS.md",
40
41
  "CHANGELOG.md",
41
42
  "CODE-HEALTH.md",
42
43
  "CODE-HISTORY.md",
43
44
  "CODE-INTELLIGENCE.md",
44
45
  "FINDING-CODE.md",
45
46
  "FRAMEWORK-ADAPTERS.md",
46
- "FULL-INSTALLATAION-GUIDE.md",
47
+ "FULL-INSTALLATION-GUIDE.md",
47
48
  "HEALTH-DASHBOARDS.md",
48
49
  "LANGUAGE-SUPPORT.md",
49
50
  "LICENSE",
@@ -53,7 +54,6 @@
53
54
  "TEAM-SETUP.md",
54
55
  "UNDERSTANDING-RELATIONSHIPS.md",
55
56
  "USER-GUIDE.md",
56
- "user-manual.md",
57
57
  "VISUALIZING-CODE.md",
58
58
  "WEB-UI.md",
59
59
  "WHY-PURECONTEXT.md",