purecontext-mcp 1.2.0 → 1.5.1

package/FRAMEWORK-ADAPTERS.md

@@ -0,0 +1,351 @@
+# Framework Adapters
+
+A language handler knows what a function or class looks like. A framework adapter knows that `app.get('/users/:id', ...)` is actually a **route**, that a Vue Single File Component is a **component**, and that a Django `models.Model` subclass is a **model** with a table behind it.
+
+PureContext ships with adapters for the frameworks most production codebases are written against. They run automatically — drop the index on a NestJS project and `/users` routes show up as first-class symbols you can search for by path, not just by handler-function name.
+
+This page is the user-facing tour. For parameter-level details (exact regex patterns, full `frameworkMeta` shapes), see the [reference manual](docs/08-framework-adapters.md).
+
+---
+
+## How adapters change what you see
+
+Without an adapter, searching for "user routes" in an Express app returns *function names* — `handleGetUser`, `createUserHandler`, `usersRouter` — and you have to read each one to confirm it's actually a route.
+
+With the Express adapter active, the same search returns:
+
+```
+search_symbols(query: "users") →
+
+  GET    /users         src/routes/users.ts    route
+  POST   /users         src/routes/users.ts    route
+  GET    /users/:id     src/routes/users.ts    route
+  DELETE /users/:id     src/routes/users.ts    route
+```
+
+That's the difference. Adapters extract the *intent* of code (a route, a component, an ORM entity) rather than just its syntactic shape.
+
+---
+
+## Auto-detection
+
+Adapters are detected from project config — `package.json`, `composer.json`, `Gemfile`, `pubspec.yaml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`. If you have `react` in dependencies, the React adapter runs. If `manage.py` sits at the project root, the Django adapter runs.
+
+You don't usually need to configure anything. If you do:
+
+```json
+{
+  "adapters": "auto"           // default
+  "adapters": "none"           // disable all adapters
+  "adapters": ["vue", "nuxt"]  // explicit allow-list
+}
+```
+
+Multiple adapters run side by side. A Vue + Nuxt project activates both. A Nest app that also uses TypeORM gets routes from Nest *and* entities from TypeORM.
+
+---
+
+## JavaScript and TypeScript
+
+### Vue 3
+
+Detected by `vue` in `package.json` or any `.vue` file present.
+
+Extracts from Single File Components:
+- The component itself (named from `defineComponent` or filename) → `component`
+- Exported `useFoo` functions → `composable`
+
+Useful for: jumping to a `<MyButton>` mentioned in a template, or finding every composable that touches the auth store.
+
+### Nuxt
+
+Detected by `nuxt.config.ts` / `.js` / `.mts` / `.mjs`.
+
+Layers Nuxt's conventional routing on top of the Vue adapter:
+- `pages/blog/[slug].vue` → `route /blog/:slug`
+- `server/api/users.get.ts` → `route GET /api/users`
+- `middleware/auth.ts` and `plugins/*` → `middleware`
+- Composables in `composables/` are flagged with `nuxt_auto_import: true`
+
+### React
+
+Detected by `react` in `package.json`. This adapter doesn't extract new symbols — it *enriches* what the TypeScript handler already found:
+- PascalCase functions that return JSX → `component`
+- `useFoo` functions → `hook`
+
+So `MyButton` shows up as a `component` rather than a generic `function`, and `useAuth` shows up as a `hook` rather than a generic `function`.
+
+### Next.js
+
+Detected by `next.config.*` or `next` in dependencies. Supports both routers:
+
+**Pages Router** (`pages/`):
+- `pages/blog/[slug].tsx` → `route /blog/:slug`
+- Detects `getServerSideProps` (SSR) and `getStaticProps` (SSG)
+- API routes from `pages/api/`
+
+**App Router** (`app/`):
+- `app/(marketing)/about/page.tsx` → `route /about` (route groups stripped)
+- `'use client'` directive flagged on metadata
+- API routes from `app/**/route.ts` with HTTP method exports
+
+**Middleware** (`middleware.ts`) → `middleware` symbol with the matcher config.
+
+### Angular
+
+Detected by `@angular/core`. Decorated classes become first-class:
+- `@Component` → `component` (with `selector`)
+- `@Injectable` → `class` (service)
+- `@NgModule` → `class` (module)
+- `@Directive` → `component`
+- `@Pipe` → `component` (with the pipe name)
+- `RouterModule.forRoot` / `forChild` configs → `route` symbols
+
+### NestJS
+
+Detected by `@nestjs/core`. Combines the controller prefix with each method's path:
+
+```typescript
+@Controller('users')
+class UsersController {
+  @Get(':id') findOne() { ... }   // → route GET /users/:id
+}
+```
+
+- `@Injectable` → `class` (with `nestjs_provider: true`)
+- `@Module` → `class` (with `nestjs_module: true`)
+- Guards and `CanActivate` implementations → `middleware`
+
+### Express
+
+Detected by `express`. Extracts string-literal route registrations:
+
+```javascript
+app.get('/path', handler)         // → route GET /path
+router.post('/path', handler)     // → route POST /path
+app.use('/path', middleware)      // → middleware /path
+```
+
+Dynamic paths built from variables or template literals are skipped — there's no reliable way to recover the runtime value from static analysis.
+
+### Fastify
+
+Detected by `fastify`. Same pattern as Express: `fastify.get(path, handler)` → `route`.
+
+---
+
+## Python
+
+### Django
+
+Detected by `manage.py` at the project root, or `django` in requirements.
+
+- `models.Model` subclasses → `model` (with field types: `CharField`, `ForeignKey`, etc.)
+- Class-based views (`APIView`, `ViewSet`, etc.) → `view`
+- Function-based views with `@login_required` / `@api_view` → `view`
+- `path(...)` / `re_path(...)` in `urls.py` → `route`
+- `@receiver(post_save)` → `signal`
+
+### FastAPI
+
+Detected by `fastapi`. Extracts decorated handlers:
+
+```python
+@app.get('/items/{id}')           # → route GET /items/{id}
+@router.post('/items')            # → route POST /items
+```
+
+FastAPI's `{param}` path syntax is preserved as-is in the route metadata.
+
+### Flask
+
+Detected by `Flask`. Extracts:
+- `@app.route('/path')` → `route`
+- `@app.get`, `@app.post`, etc. → `route`
+- Blueprint routes (`@bp.route(...)`) → `route`
+- Class-based views inheriting `MethodView` → `view`
+
+Flask's `<int:user_id>` path syntax is preserved.
+
+---
+
+## Go
+
+### Gin, Echo, Fiber
+
+Detected by their respective `go.mod` entries. All three follow the same pattern — `r.GET("/path", handler)` becomes a `route`. Route groups apply their prefix to children.
+
+The Fiber adapter handles title-cased methods (`app.Get`, `app.Post`); Gin and Echo use lowercase methods.
+
+---
+
+## PHP
+
+### Laravel
+
+Detected by `laravel/framework` in `composer.json`.
+
+- `Route::get('/path', ...)` → `route`
+- `Route::resource('users', Controller::class)` → expands into the seven CRUD routes (index/show/create/store/edit/update/destroy)
+- `Route::group(['prefix' => '/api'], ...)` → prefix applied to children
+- `class User extends Model` → `model`
+- Controller public methods → `view` (action)
+- Middleware classes → `middleware`
+
+### Symfony
+
+Detected by `symfony/framework-bundle`. Supports both routing styles:
+
+```php
+#[Route('/path', methods: ['GET'])]   // PHP 8 attributes
+@Route('/path')                       // docblock annotations
+```
+
+Both produce `route` symbols.
+
+---
+
+## Ruby
+
+### Rails
+
+Detected by `gem 'rails'` in `Gemfile`.
+
+- `ApplicationRecord` subclasses → `model` (with `has_many` associations captured)
+- Controller public methods → `view` (action)
+- `get '/path'`, `resources :users` in `routes.rb` → `route` (resources expand to the seven REST actions)
+
+### Sinatra
+
+Detected by `gem 'sinatra'` or `require 'sinatra'`. `get '/path' do ... end` → `route`.
+
+---
+
+## Kotlin
+
+### Ktor
+
+Detected by `io.ktor`. Extracts from the routing DSL:
+
+```kotlin
+route("/api") {
+  get("/users") { ... }    // → route /api/users
+}
+authenticate { ... }       // → frameworkMeta.authenticated: true
+```
+
+### Spring (Kotlin)
+
+Detected by `org.springframework.boot`. Same extraction as Spring Boot below — adapter handles both Java and Kotlin sources.
+
+---
+
+## Rust
+
+### Axum
+
+Detected by `axum` in `Cargo.toml`. Extracts router chains:
+
+```rust
+.route("/users", get(list_users))
+.route("/users/:id", get(get_user))
+.layer(auth_middleware)   // → middleware
+```
+
+### Actix-web
+
+Detected by `actix-web`. Extracts attribute macros: `#[get("/path")]` → `route`. `.wrap(...)` calls become `middleware`.
+
+### Rocket
+
+Detected by `rocket`. Extracts `#[get("/path")]` → `route`. `#[catch(404)]` becomes an error catcher, and `Fairing` implementations become middleware.
+
+---
+
+## Java
+
+### Spring Boot
+
+Detected by `spring-boot-starter` in build files.
+
+- `@GetMapping` / `@PostMapping` (combined with class-level `@RequestMapping` prefix) → `route`
+- `@Service`, `@Component`, `@Repository` → beans with bean metadata
+- `@Bean` factory methods → tracked as bean producers
+- `@Scheduled` methods → scheduled tasks
+
+### Micronaut
+
+Detected by `io.micronaut`. `@Get("/path")`, `@Post(...)` → `route`. `@Client` interfaces are captured.
+
+### Quarkus
+
+Detected by `io.quarkus`. JAX-RS `@GET` + `@Path` combinations → `route`. `@ApplicationScoped` → bean.
+
+---
+
+## ORM adapters
+
+ORMs sit slightly off the routing-adapter spine because they don't add routes — they add *entities*, which downstream queries (`find_references`, `get_blast_radius`) treat the same as any other symbol.
+
+| Adapter | Detected by | Extracts |
+|---------|-------------|----------|
+| **Hibernate** (Java) | `hibernate-core` / `jakarta.persistence` | `@Entity` classes, table name, columns with types and nullability, `@OneToMany` / `@ManyToOne` relationships, named queries |
+| **SQLAlchemy** (Python) | `sqlalchemy` | `Base` / `DeclarativeBase` subclasses, `__tablename__`, `Column(Type)` fields, `relationship()` associations, `@hybrid_property`. Supports both 1.x and 2.0 (`mapped_column`) styles. |
+| **Django ORM** | `manage.py` | `models.Model` subclasses with field types (`CharField`, `IntegerField`, `ForeignKey`, `ManyToManyField`, etc.) |
+| **Prisma** | `prisma` in `package.json` or `schema.prisma` present | Model definitions and relations from `schema.prisma` |
+| **TypeORM** | `typeorm` in `package.json` | `@Entity` classes and `@Column` / `@Relation` fields |
+
+Once entities are first-class symbols, you can ask "what writes to the `users` table?" the same way you'd ask "what calls `validateToken`?".
+
+---
+
+## Mobile
+
+### Flutter
+
+Detected by `sdk: flutter` in `pubspec.yaml`. Extracts from `.dart` files:
+
+- `StatelessWidget` subclasses → `widget`
+- `StatefulWidget` subclasses → `widget` (linked to the State class)
+- `ChangeNotifier` subclasses → `class` with `flutter_notifier: true`
+
+---
+
+## Disabling an adapter
+
+If an adapter is misclassifying things in your project, turn it off:
+
+```json
+{
+  "adapters": ["vue", "react"]   // explicit list — others stay off
+}
+```
+
+Or to disable framework extraction entirely:
+
+```json
+{
+  "adapters": "none"
+}
+```
+
+The language handler still runs — you'll still get functions and classes, you just won't get `route` / `component` / `model` annotations on top.
+
+---
+
+## Adding a new adapter
+
+Adapters follow the same three-layer rule as language handlers (Core → Handlers → Adapters; never the reverse). To add one:
+
+1. Create a file in `src/adapters/`, implementing `FrameworkAdapter`
+2. `detect(projectRoot)` returns true if the framework is present
+3. `extractFrameworkSymbols(tree, source, filePath)` returns the framework-specific symbols
+4. Optionally `enrichMetadata(symbol)` to add `frameworkMeta` to existing symbols
+5. Add tests against fixture projects in `test/adapters/`
+
+See `docs/25-architecture-overview.md` for the architecture rules and `src/adapters/vue.ts` for a good reference implementation.
+
+---
+
+→ Full parameter-level reference: [docs/08-framework-adapters.md](docs/08-framework-adapters.md)
+→ The language handlers that adapters sit on top of: [LANGUAGE-SUPPORT.md](LANGUAGE-SUPPORT.md)

package/FULL-INSTALLATION-GUIDE.md

@@ -0,0 +1,341 @@
+# 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@latest
+```
+
+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@latest
+```
+
+`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@latest
+```
+
+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@latest"]
+    }
+  }
+}
+```
+
+If you installed globally (`npm install -g purecontext-mcp`), you can use the binary directly:
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "purecontext-mcp@latest"
+    }
+  }
+}
+```
+
+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@latest"]
+    }
+  }
+}
+```
+
+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@latest"]
+    }
+  }
+}
+```
+
+### VS Code (with MCP support)
+
+Create `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "purecontext": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["purecontext-mcp@latest"]
+    }
+  }
+}
+```
+
+### 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.
+
+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.
+
+### Recommended: `purecontext-mcp install`
+
+PureContext ships with a multi-IDE installer that writes the workflow rules into the conventions file each tool expects. Run it once inside your project root:
+
+```bash
+npx purecontext-mcp install all
+```
+
+This auto-detects which AI tools are configured in the project (by looking for marker files such as `.cursor/`, `.windsurfrules`, `CLAUDE.md`, `.continue/`, etc.) and installs the rules for each.
+
+When no `--scope` flag is given, the CLI prompts you to choose where to install:
+
+```
+Where should PureContext be installed?
+  1) Local  — this project only
+  2) Global — all projects (user-level config)
+  3) Both
+```
+
+Pass `--scope` to skip the prompt:
+
+```bash
+npx purecontext-mcp install all --scope=local    # this project only
+npx purecontext-mcp install all --scope=global   # user-level, all projects
+npx purecontext-mcp install all --scope=both     # both places at once
+```
+
+For a single tool:
+
+```bash
+npx purecontext-mcp install cursor --scope=global
+npx purecontext-mcp install windsurf
+npx purecontext-mcp install continue
+# ...etc.
+```
+
+Useful flags:
+
+```bash
+npx purecontext-mcp install --list           # show detection state, write nothing
+npx purecontext-mcp install all --dry-run    # preview which writers would run
+```
+
+### Supported tools
+
+| Tool | Local | Global | Notes |
+|------|-------|--------|-------|
+| `claude` | `CLAUDE.md` in project | `~/.claude/CLAUDE.md` + hooks | Global installs PostToolUse re-index, PreCompact snapshot, and edit guard. |
+| `cursor` | `.cursor/rules/purecontext.mdc` | `~/.cursor/rules/purecontext.mdc` | MDC frontmatter with `alwaysApply: true`. |
+| `windsurf` | `.windsurfrules` | `~/.windsurfrules` | Marked block appended or replaced in place. |
+| `continue` | `.continue/config.json` | `~/.continue/config.json` | JSON-aware merge; other fields are preserved. |
+| `cline` | `.clinerules` | local only | No known global config path. |
+| `roo-code` | `.roo/rules-code.md` | local only | No known global config path. |
+| `vscode` | `.github/copilot-instructions.md` | local only | Picked up by GitHub Copilot in VS Code. |
+| `claude-desktop` | always global | always global | Merges MCP server entry; leaves other servers untouched. |
+
+### Idempotency
+
+Every writer is safe to re-run. The Markdown writers wrap their content in HTML comment markers:
+
+```html
+<!-- purecontext-mcp-start -->
+... PureContext workflow rules ...
+<!-- purecontext-mcp-end -->
+```
+
+On re-run, the marked block is replaced in place. Anything outside the markers (your own rules, other tools' rules) is preserved. The JSON writers (`continue`, `claude-desktop`) parse and merge structurally rather than re-emitting the whole file.
+
+### Manual install (if you'd rather paste)
+
+The two source-of-truth files are at the repository root:
+
+- **`AGENT_INSTRUCTIONS_SHORT.md`** — Compact (~2 KB). Mandatory first step, tool selection table, core rules, common usage patterns. Use for agents with limited system prompt space.
+- **`AGENT_INSTRUCTIONS.md`** — Full (~15 KB). Adds parameter notes, every usage pattern, known limitations, decision trees, anti-patterns. Use for complex multi-step workflows.
+
+To use these manually:
+
+```bash
+# Claude Code
+cat AGENT_INSTRUCTIONS_SHORT.md >> CLAUDE.md
+
+# Cursor — paste into .cursorrules or via Cursor Settings → Rules
+# Windsurf — paste into .windsurfrules or workspace memory
+# Anything else — paste into whatever rule/memory config it supports
+```
+
+---
+
+## 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
+
+Run the command that matches how you installed PureContext:
+
+**Installed with Volta:**
+```bash
+volta install purecontext-mcp
+```
+
+**Installed with npm globally:**
+```bash
+npm install -g purecontext-mcp@latest
+```
+
+**Running via npx (no global install):** npx may serve a cached older version. Force the latest:
+```bash
+npx purecontext-mcp@latest
+```
+To always get the latest version automatically, use `purecontext-mcp@latest` in your MCP client config instead of the bare package name.
+
+**Installed from source:**
+```bash
+cd /path/to/purecontext-mcp
+git pull
+npm install
+npm run build
+```
+
+> **Note:** `npm update -g purecontext-mcp` does not work reliably — use `npm install -g purecontext-mcp@latest` instead.
+
+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
+```