purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE3_TASKS.md

@@ -1,571 +0,0 @@
-# Phase 3 — Task Breakdown
-
-**Goal**: Expand language coverage to Python and Go, add the Next.js adapter, deliver HTTP/SSE transport, harden security, and round out the tool set with text search, layer violation analysis, and a more capable AI summarizer.
-
-**Scope rationale**: Phase 2 moved React into scope but deferred HTTP/SSE transport. The PRD Phase 3 deliverables (React + Next.js, layer violations, semantic search) are partially satisfied — React is done, Next.js is not. The Phase 2 end note called out Python, Go, HTTP/SSE, and AI expansion as Phase 3 targets. This document covers all of it.
-
-**Approach**: Tasks are sequenced so each one builds on the previous. Complete them in order. Each task should be independently testable before moving to the next.
-
----
-
-## Task 24: Python Language Handler
-
-Add Python as the first non-JS/TS language. This validates that the `LanguageHandler` interface generalises cleanly and is the foundation for Go (Task 25) and any future language.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-python.wasm`
-- `src/handlers/python.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.py']`
-  - `grammarPath()`: path to `tree-sitter-python.wasm`
-  - `extractSymbols(tree, source)`:
-    - `function_definition` → kind `'function'`
-    - `class_definition` → kind `'class'`
-    - `decorated_definition` wrapping a `function_definition` → kind `'function'` (pull name from inner node)
-    - `decorated_definition` wrapping a `class_definition` → kind `'class'`
-    - Method: `function_definition` whose parent chain includes a `class_definition` → kind `'method'`
-    - Module-level `expression_statement` / `assignment` with a type annotation → kind `'const'`
-    - Only extract top-level and class-level symbols (not nested function bodies)
-    - Capture name, byte offsets (`startIndex` / `endIndex`), build signature
-  - `extractImports(tree, source)`:
-    - `import_statement`: `import foo`, `import foo as bar` → specifier = module name
-    - `import_from_statement`: `from foo import bar, baz` → specifier = module path, importedNames = [bar, baz]
-    - Relative imports: `from . import x`, `from ..utils import y` → specifier = relative path, resolvedPath = null (leave for resolver to handle)
-    - `isTypeOnly`: always `false` for Python (no type-only imports)
-  - `extractDocstring(node)`:
-    - For function/class nodes: check if first child of the body is a `string` node (triple-quoted docstring)
-    - Extract text, strip quotes and leading whitespace, return first paragraph (up to first blank line)
-
-**Signature building:**
-- Functions: `def name(params) -> returnType:` (truncate params if > 100 chars)
-- Classes: `class Name(bases):` or `class Name:`
-- Constants: `NAME: Type = ...` or `NAME = ...` (truncate value)
-- Keep signatures under 120 chars
-
-**Key technical notes:**
-- Python uses `startIndex` / `endIndex` on nodes (byte offsets), same as TypeScript — no special handling needed
-- `decorated_definition` wraps the actual declaration; extract name from the inner `function_definition` or `class_definition` child
-- Method detection: walk `parent` chain up to find a `class_definition` before hitting module root
-- Python has no explicit `export` concept — index all top-level and class-level definitions
-
-**Verify:** Index `test/fixtures/python-project/` (created in Task 32). Verify functions, classes, methods, and decorated functions are extracted with correct byte offsets. Verify docstrings are captured.
-
-**Tests:** Fixture `.py` files covering: simple function, class with methods, `@decorator` on function, `@decorator` on class, module-level typed constant, `from x import y` / `import x` / relative import, function with docstring, function without docstring, nested function (should NOT be extracted).
-
----
-
-## Task 25: Go Language Handler
-
-Add Go as the second non-JS/TS language. Go's type system (structs, interfaces, methods with receivers) maps cleanly onto the existing `SymbolKind` types.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-go.wasm`
-- `src/handlers/go.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.go']`
-  - `grammarPath()`: path to `tree-sitter-go.wasm`
-  - `extractSymbols(tree, source)`:
-    - `function_declaration` → kind `'function'`
-    - `method_declaration` (has a receiver) → kind `'method'`
-    - `type_declaration` containing a `type_spec`:
-      - `struct_type` → kind `'class'` (closest analog; no true class in Go)
-      - `interface_type` → kind `'interface'`
-      - all others (type aliases, custom types) → kind `'type'`
-    - `const_declaration` → kind `'const'`
-    - Extract both single-value (`const X = ...`) and grouped (`const ( X = ...\n Y = ... )`) const declarations
-    - Skip unexported symbols (names that start with a lowercase letter) — these are package-private and typically noise for navigation
-  - `extractImports(tree, source)`:
-    - `import_declaration` with one or more `import_spec` children
-    - For each `import_spec`: specifier = the quoted path string (strip quotes), alias = the local name if present
-    - All Go imports are package paths (e.g., `"fmt"`, `"github.com/user/pkg"`)
-    - `resolvedPath`: `null` for all Go imports (external module system — no local resolution without go.mod parsing)
-    - `importedNames`: `[]` (Go uses package-level identifiers, not named imports)
-  - `extractDocstring(node)`:
-    - Look for a `comment` node (or sequence of `comment` nodes) immediately preceding the symbol node in the parent's children list
-    - Strip `//` prefix and leading spaces from each line
-    - Concatenate lines, return first sentence (up to first `.` or 100 chars)
-
-**Signature building:**
-- Functions: `func Name(params) returnType`
-- Methods: `func (recv ReceiverType) Name(params) returnType`
-- Structs: `type Name struct { ... }` (show first 2 fields if body is short, else `{ ... }`)
-- Interfaces: `type Name interface { ... }` (show first 2 methods if short)
-- Type aliases: `type Name = BaseType`
-- Constants: `const Name Type = value`
-- Keep signatures under 120 chars
-
-**Key technical notes:**
-- Go method receivers are part of the `method_declaration` node — extract receiver type to qualify the method name (`ReceiverType.MethodName`)
-- Exported symbol rule: Go's only visibility mechanism is first-letter case. Names starting with uppercase are exported.
-- Go has no decorator/annotation system — skip decorator handling entirely
-- `const` groups: a single `const_declaration` may contain multiple `const_spec` children — emit one `SymbolRecord` per spec
-
-**Verify:** Index `test/fixtures/go-project/` (created in Task 32). Verify exported functions, methods (with receiver type in name), struct types, interface types, and constants are extracted. Verify unexported symbols are skipped.
-
-**Tests:** Fixture `.go` files covering: exported function, unexported function (skipped), struct with fields, interface with methods, method with receiver, const single/grouped, import single/grouped, docstring comment preceding function.
-
----
-
-## Task 26: Next.js Adapter
-
-The Next.js adapter extends the React adapter (Phase 2) with route extraction — both the Pages Router and the App Router. This mirrors the relationship between the Vue and Nuxt adapters.
-
-**Deliverables:**
-- `src/adapters/nextjs.ts` — implements `FrameworkAdapter`
-  - `name`: `'nextjs'`
-  - `extensions()`: `[]` — Next.js uses `.tsx`/`.jsx`/`.ts`/`.js` already handled by the TS/JS handler
-  - `detect(projectRoot)`:
-    - Check for `next.config.js`, `next.config.ts`, `next.config.mjs`, or `next.config.cjs` in project root
-    - OR check `package.json` for `next` in `dependencies`
-  - `fileFilter(filePath)`:
-    - **Pages Router**: `pages/**/*.{tsx,jsx,ts,js}` → `true`
-    - **App Router**: `app/**/page.{tsx,jsx}`, `app/**/layout.{tsx,jsx}`, `app/**/loading.{tsx,jsx}`, `app/**/error.{tsx,jsx}`, `app/**/not-found.{tsx,jsx}` → `true`
-    - **API routes (Pages Router)**: `pages/api/**/*.{ts,js}` → `true`
-    - **API routes (App Router)**: `app/**/route.{ts,js}` → `true`
-    - **Middleware**: `middleware.{ts,js}` at project root → `true`
-    - `src/` prefix variants: repeat all patterns with `src/` prepended (Next.js supports `src/app/` and `src/pages/`)
-    - All other files → `false`
-  - `extractFrameworkSymbols(tree, source, filePath)`:
-
-    **Pages Router page** (`pages/**`, not `pages/api/**`):
-    - Emit one `route` symbol per file
-    - Name: filename without extension
-    - Route path: derive from file path using Pages Router conventions
-      - `pages/index.tsx` → `/`
-      - `pages/about.tsx` → `/about`
-      - `pages/blog/[slug].tsx` → `/blog/:slug`
-      - `pages/[...catchAll].tsx` → `/*catchAll`
-      - `pages/[[...optionalCatchAll]].tsx` → `/*optionalCatchAll?`
-    - Scan AST for exported `getServerSideProps` → `frameworkMeta.ssr: true`
-    - Scan AST for exported `getStaticProps` → `frameworkMeta.ssg: true`
-    - Scan AST for exported `getStaticPaths` → `frameworkMeta.dynamic_ssg: true`
-    - `frameworkMeta.router: 'pages'`
-
-    **App Router page** (`app/**/page.{tsx,jsx}`, and other special files):
-    - Emit one `route` symbol per `page.tsx` file
-    - Route path: derive from directory path above `page.tsx`
-      - `app/page.tsx` → `/`
-      - `app/about/page.tsx` → `/about`
-      - `app/blog/[slug]/page.tsx` → `/blog/:slug`
-      - `app/(marketing)/about/page.tsx` → `/about` (route groups in parens are stripped)
-    - Detect `'use client'` directive (first string literal in file) → `frameworkMeta.client_component: true`; absence implies `frameworkMeta.server_component: true`
-    - `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx` → emit with kind `'component'` and appropriate `frameworkMeta.nextjs_special: 'layout' | 'loading' | 'error' | 'not-found'`
-    - `frameworkMeta.router: 'app'`
-
-    **API Routes (Pages Router)** (`pages/api/**`):
-    - Emit one `route` symbol per file
-    - Route path: `/api/...` prefix + Pages Router path derivation
-    - No HTTP method on the symbol (Pages Router uses request object, not filename)
-    - `frameworkMeta.api_route: true`, `frameworkMeta.router: 'pages'`
-
-    **API Routes (App Router)** (`app/**/route.{ts,js}`):
-    - Scan AST for exported functions named `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
-    - Emit one `route` symbol per HTTP method export found
-    - Route path: derive from directory of `route.ts`
-    - `frameworkMeta.http_method`, `frameworkMeta.api_route: true`, `frameworkMeta.router: 'app'`
-
-    **Middleware** (`middleware.ts` at root):
-    - Emit one `middleware` symbol
-    - Scan for `config.matcher` export → `frameworkMeta.matcher`
-    - `frameworkMeta.nextjs_middleware: true`
-
-  - `enrichMetadata(symbol)`:
-    - For kind `'function'` or `'const'` in Next.js files: check if name starts with uppercase and returns JSX → upgrade to `'component'` (same as React adapter)
-    - Preserve all existing `frameworkMeta` fields
-  - Register via `registerAdapter(nextjsAdapter)` at module level
-
-**Key decisions:**
-- Next.js and React adapters can be active simultaneously — React adapter handles components and hooks, Next.js adapter handles routes and middleware
-- App Router route groups (directories wrapped in `()`) are stripped from route paths
-- Parallel routes (`@slot` directories) are not extracted in Phase 3 — too complex, low value
-- `.tsx` in `app/` without `page.tsx` name is ignored by Next.js adapter (React adapter handles it normally)
-
-**Verify:** Index `test/fixtures/nextjs-project/` (created in Task 32). Verify Pages Router produces route symbols with correct paths. Verify App Router produces routes with `router: 'app'`. Verify `pages/api/users.ts` produces an API route. Verify `app/api/users/route.ts` with exported `GET` and `POST` produces two route symbols.
-
-**Tests:** Route path derivation (pure functions, unit-testable): index, nested, dynamic, catch-all, optional catch-all, route group stripping. App Router client component detection. API route method extraction (Pages + App). Middleware symbol with matcher.
-
----
-
-## Task 27: Security Layer
-
-Before shipping HTTP transport (Task 28) — which exposes the server over a network socket — harden the file access layer against path traversal, symlink escape, and accidental credential exposure.
-
-**Deliverables:**
-- `src/core/security.ts`
-  - `SecurityError` extends `PureContextError` — already in `errors.ts`, add if missing
-  - `validatePath(filePath: string, projectRoot: string): string`
-    - Resolve both paths to absolute with `path.resolve()`
-    - Verify resolved path starts with `projectRoot + path.sep`
-    - Throw `SecurityError('path_traversal')` if not
-    - Return the resolved absolute path
-  - `checkSymlinkEscape(resolvedPath: string, projectRoot: string): void`
-    - Use `fs.realpathSync()` to resolve all symlinks
-    - Verify the real path is still within `projectRoot`
-    - Throw `SecurityError('symlink_escape')` if not
-  - `isSecretFile(filePath: string): boolean`
-    - Match against these patterns (case-insensitive):
-      - `.env`, `.env.*` (`.env.local`, `.env.production`, etc.)
-      - `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.crt`, `*.cer`
-      - `id_rsa`, `id_ed25519`, `id_ecdsa`, `id_dsa` (and `*.pub`)
-      - `credentials.json`, `credentials.yaml`, `credentials.yml`
-      - `secrets.json`, `secrets.yaml`, `secrets.yml`
-      - `serviceAccountKey*.json`, `*-service-account.json`
-      - `*.token`, `*.secret`
-    - Returns `true` if the file should be excluded from indexing
-  - `isBinaryFile(content: Buffer): boolean`
-    - Check first 8192 bytes for null bytes (`\x00`) — reliable binary indicator
-    - Return `true` if null bytes found
-  - `checkFileSize(size: number, maxBytes: number): void`
-    - Throw `SecurityError('file_too_large')` if `size > maxBytes`
-    - Default max: 1 MB (1_048_576 bytes), configurable via `config.maxFileSizeBytes`
-
-- Update `src/core/file-discovery.ts`:
-  - Apply `isSecretFile()` during file scanning — skip matching files with a debug log
-  - Apply `isBinaryFile()` after reading file content — skip with debug log
-  - Apply `checkFileSize()` — skip oversized files with a warning log
-
-- Update `src/server/tools/get-symbol-source.ts`:
-  - Call `validatePath()` on every file path before reading from the files table
-  - This prevents crafted symbol IDs from escaping the project root
-
-- Update `src/config/config-schema.ts`:
-  - Add `maxFileSizeBytes: number` (default: 1_048_576)
-  - Add `allowSymlinks: boolean` (default: `false`) — when false, symlink escape check is enforced
-
-**Key decisions:**
-- Security checks are synchronous and cheap — no performance concern on the hot path
-- Secret file exclusion is a safelist of patterns, not a blocklist — conservative by design
-- Binary detection by null-byte check is sufficient; MIME types add complexity without meaningful benefit
-- `allowSymlinks: false` by default — symlinks inside the project root are fine, but symlinks that resolve outside are blocked
-
-**Verify:** Attempt to read a path like `../../etc/passwd` via `get-symbol-source` — verify `SecurityError` is thrown. Index a project with a `.env` file — verify it does not appear in the index. Index a project with a binary file — verify it is skipped cleanly.
-
-**Tests:** `validatePath`: valid path, path traversal with `../`, path traversal with encoded chars. `isSecretFile`: `.env`, `.env.local`, `id_rsa`, `credentials.json`, normal `.ts` file (false). `isBinaryFile`: Buffer with null byte (true), Buffer of plain text (false). `checkFileSize`: oversized buffer throws, normal buffer passes.
-
----
-
-## Task 28: HTTP/SSE Transport
-
-Add HTTP + Server-Sent Events transport so PureContext can be used from web-based MCP clients, remote development environments, and multi-client setups. The security layer from Task 27 must be in place before deploying this.
-
-**Deliverables:**
-- `src/server/transport.ts` — transport abstraction
-  - `TransportMode`: `'stdio' | 'http' | 'both'`
-  - `createTransport(mode: TransportMode, options: TransportOptions): Transport`
-  - `TransportOptions`: `{ port?: number, host?: string, corsOrigins?: string[] }`
-  - For `'stdio'`: wraps `StdioServerTransport` from the MCP SDK (existing behavior)
-  - For `'http'`: wraps `SSEServerTransport` from the MCP SDK
-  - For `'both'`: starts both transports simultaneously
-
-- `src/server/http-server.ts`
-  - `startHttpServer(mcpServer: McpServer, options: TransportOptions): HttpServer`
-  - Use Node.js `http.createServer()` (no Express dependency)
-  - Routes:
-    - `GET /health` → `{ status: 'ok', version, repoCount, uptime }`
-    - `GET /sse` → SSE stream (MCP SSE transport endpoint)
-    - `POST /message` → MCP message handler (SSE transport companion)
-    - All other paths → 404
-  - CORS: set `Access-Control-Allow-Origin` from configured `corsOrigins` (default: `['localhost']`)
-  - Request size limit: reject POST bodies > 1 MB (guard against malformed requests)
-  - Log each incoming request at debug level (method, path, client IP)
-
-- Update `src/config/config-schema.ts`:
-  - Add `transport`: `'stdio' | 'http' | 'both'` (default: `'stdio'`)
-  - Add `http.port`: number (default: `3000`)
-  - Add `http.host`: string (default: `'127.0.0.1'` — loopback only by default, not `0.0.0.0`)
-  - Add `http.corsOrigins`: string[] (default: `['http://localhost:*']`)
-
-- Update `src/config/cli.ts`:
-  - Add `--transport` flag: `purecontext-mcp --transport http`
-  - Add `--port` flag: `purecontext-mcp --port 3001`
-  - CLI flags override config.json values
-
-- Update `src/index.ts`:
-  - Read transport config, start appropriate transport(s)
-  - On HTTP mode: log `PureContext MCP listening on http://{host}:{port}` to stderr
-
-- Update `README.md`:
-  - Add section: HTTP/SSE transport setup
-  - Claude Code / VS Code MCP config snippet for HTTP mode
-
-**Key decisions:**
-- Default `host: '127.0.0.1'` is intentional — binding to `0.0.0.0` exposes the server on all interfaces and requires explicit opt-in
-- The MCP SDK's `SSEServerTransport` handles protocol-level SSE framing — we only need to wire the HTTP server to it
-- No authentication in Phase 3 (loopback-only default mitigates risk; auth is Phase 4 if remote access is needed)
-- `'both'` mode is for development — stdio for Claude Code, HTTP for browser-based clients simultaneously
-
-**Verify:** Start with `--transport http`, connect using an MCP HTTP client (or curl the `/health` endpoint). Index a project via HTTP transport. Start with `--transport both` and verify stdio and HTTP tools both work simultaneously.
-
-**Tests:** HTTP server unit tests with `node:http` requests: health check returns correct fields, unknown path returns 404, CORS headers present on OPTIONS, oversized POST rejected. Transport factory: stdio mode creates StdioServerTransport, http mode starts HTTP server, both mode starts both.
-
----
-
-## Task 29: Full-Text Search Tool
-
-Add `search-text` — full-text search across raw file content. This complements `search-symbols` (which searches symbol metadata) by letting agents grep for literal strings, patterns, or keywords that aren't symbol names.
-
-**Deliverables:**
-- `src/server/tools/search-text.ts`
-  - Tool name: `search-text`
-  - Input schema:
-    ```json
-    {
-      "repo":          { "type": "string", "description": "Repo ID or path" },
-      "query":         { "type": "string", "description": "Literal string or regex pattern to search for" },
-      "is_regex":      { "type": "boolean", "default": false },
-      "file_pattern":  { "type": "string", "description": "Glob pattern to filter files (e.g. '**/*.ts')" },
-      "context_lines": { "type": "number", "default": 2, "description": "Lines of context before and after each match" },
-      "max_results":   { "type": "number", "default": 50 }
-    }
-    ```
-  - Implementation:
-    1. Load repo from DB — verify it exists
-    2. Query `files` table for all files in repo (with `raw_content`)
-    3. If `file_pattern` is provided, filter file paths using minimatch
-    4. For each matching file: split `raw_content` into lines, scan for `query` (literal or regex)
-    5. For each match: record `{ file, line, column, matchText, contextBefore, contextAfter }`
-    6. Stop accumulating after `max_results` matches are found
-  - Output:
-    ```json
-    {
-      "matches": [
-        {
-          "file":          "src/auth/login.ts",
-          "line":          42,
-          "column":        8,
-          "match":         "validateToken(",
-          "context":       "  // Validate the JWT\n  validateToken(token, secret);\n  return decoded;"
-        }
-      ],
-      "total_matches": 7,
-      "files_searched": 143,
-      "truncated": false,
-      "_tokenEstimate": 820
-    }
-    ```
-  - Security: apply `validatePath()` from the security layer on every file path before reading content
-  - Register in `src/server/mcp-server.ts`
-
-**Key decisions:**
-- Search runs against cached `raw_content` in SQLite — no live file reads needed, keeps search fast
-- Regex errors are caught and returned as a tool error (not a server crash)
-- `context_lines` default of 2 gives enough context to understand the match without flooding the response
-- `_tokenEstimate` calculation: sum of all match + context line lengths / 4 (rough token estimate)
-
-**Verify:** Index a project, search for a string that appears in multiple files. Verify matches include correct line numbers and context. Search with an invalid regex — verify graceful error response. Search with `file_pattern` — verify only matching files are searched.
-
-**Tests:** Literal search with single result, literal search with multiple results, regex search, file_pattern filtering, max_results truncation (verify `truncated: true`), invalid regex returns error, empty result set.
-
----
-
-## Task 30: Layer Violation Analyzer
-
-Implement the `get-layer-violations` tool called out in the PRD. This lets agents (and developers) verify that the declared architectural dependency rules are being followed — no core importing handlers, no handlers importing adapters, etc.
-
-**Deliverables:**
-- `src/server/tools/get-layer-violations.ts`
-  - Tool name: `get-layer-violations`
-  - Input schema:
-    ```json
-    {
-      "repo": { "type": "string" },
-      "layers": {
-        "type": "array",
-        "description": "Layer definitions (optional — falls back to config.json). If omitted, reads from project config.",
-        "items": {
-          "type": "object",
-          "properties": {
-            "name":  { "type": "string" },
-            "paths": { "type": "array", "items": { "type": "string" } }
-          }
-        }
-      }
-    }
-    ```
-  - Implementation:
-    1. Resolve layer config: prefer tool input, fall back to `config.json` `layers` field, fall back to error if neither present
-    2. Build a map: for each file in the repo, determine which layer it belongs to (first match wins; files matching no layer are `'unclassified'`)
-    3. Load all `dep_edges` for the repo from `dep_edges` table
-    4. For each edge `(sourceFile → targetFile)`:
-       - Look up `sourceLayer` and `targetLayer`
-       - Check if `sourceLayer → targetLayer` is a declared allowed direction
-       - If not, record as a violation
-    5. Return violations grouped by layer pair
-
-  - Output:
-    ```json
-    {
-      "violations": [
-        {
-          "from_layer":   "core",
-          "to_layer":     "handlers",
-          "from_file":    "src/core/index-manager.ts",
-          "to_file":      "src/handlers/typescript.ts",
-          "import_spec":  "../handlers/typescript.js"
-        }
-      ],
-      "summary": {
-        "total_violations": 1,
-        "by_layer_pair": { "core → handlers": 1 }
-      },
-      "layers_analyzed": ["core", "handlers", "adapters"],
-      "_tokenEstimate": 240
-    }
-    ```
-
-- Update `src/config/config-schema.ts`:
-  - Add `layers` config key:
-    ```json
-    {
-      "layers": {
-        "definitions": [
-          { "name": "core",     "paths": ["src/core/**"] },
-          { "name": "handlers", "paths": ["src/handlers/**"] },
-          { "name": "adapters", "paths": ["src/adapters/**"] },
-          { "name": "server",   "paths": ["src/server/**"] }
-        ],
-        "rules": [
-          { "from": "adapters", "to": "handlers", "allowed": true },
-          { "from": "handlers", "to": "core",     "allowed": true },
-          { "from": "core",     "to": "handlers", "allowed": false },
-          { "from": "core",     "to": "adapters", "allowed": false },
-          { "from": "handlers", "to": "adapters", "allowed": false }
-        ]
-      }
-    }
-    ```
-  - Any `from → to` pair not listed in `rules` is treated as `allowed: true` (opt-in violation detection)
-  - Register in `src/server/mcp-server.ts`
-
-**Key decisions:**
-- Layer assignment is based on file path glob matching — the same glob patterns used for file discovery
-- `unclassified` files are excluded from violation checks (they'd generate too much noise)
-- Violations are directional: `core → handlers` is a violation, `handlers → core` is allowed (in the default config)
-- The default layer config in `config.json` mirrors PureContext's own architecture — useful for dogfooding
-
-**Verify:** Index this repo (PureContext itself). Run `get-layer-violations` with the default layer config. Verify the known-good architecture produces zero violations. Introduce a deliberate violation in a temp file — verify it is detected.
-
-**Tests:** Layer assignment (unit-testable): file in `src/core/` → `'core'`, file in `src/adapters/` → `'adapters'`, file outside any layer → `'unclassified'`. Violation detection: edge from allowed direction (no violation), edge from disallowed direction (violation recorded). Config fallback: no layers in input → reads from config.
-
----
-
-## Task 31: AI Summarization Expansion
-
-Extend the AI summarizer from Phase 2 to support OpenAI-compatible endpoints (enabling self-hosted models, Ollama, LM Studio) and improve batch prompt quality by including symbol context. Also add re-summarization on incremental re-index so symbols that change get fresh summaries.
-
-**Deliverables:**
-- Update `src/summarizer/ai-summarizer.ts`:
-  - Add `OpenAICompatibleSummarizer` alongside the existing Anthropic implementation
-    - Any endpoint that speaks the OpenAI `/v1/chat/completions` API (Ollama, LM Studio, Azure OpenAI, OpenRouter, etc.)
-    - Configured via `ai.endpoint` (the base URL) + `ai.apiKey` + `ai.model`
-    - Uses `fetch` directly (no SDK dependency — the OpenAI API is simple enough)
-  - Improve batch prompt quality:
-    - Current: just symbol signature + 100 chars of source
-    - New: signature + file path + parent class name (if method) + first 3 import specifiers (context about what the file does) + 150 chars of source
-    - Prompt template: `"Summarize each symbol in one sentence. Context: [file_path]. [imports_hint].\n\nSymbols:\n1. [signature]\n[source_snippet]\n..."`
-  - Add `summarizeBatchWithRetry()`: if the provider returns a malformed or incomplete response, retry once with a simpler prompt (signature only) before falling back to signature fallback
-  - No change to graceful degradation behavior — network/API errors still return an empty map
-
-- Update `src/config/config-schema.ts`:
-  - `ai.provider`: `'anthropic' | 'openai-compatible' | 'none'` (was `'anthropic' | 'openai' | 'none'`)
-  - `ai.endpoint`: `string | null` — required for `'openai-compatible'`, ignored for `'anthropic'`
-  - `ai.model`: `string` — default `'claude-haiku-4-5-20251001'` for Anthropic, `'gpt-4o-mini'` for OpenAI-compatible
-  - `ai.apiKey`: `string` — can be a literal key or `'${ENV_VAR}'` notation (resolved from environment at load time)
-  - `ai.batchSize`: `number` — default `50`, controls how many symbols per API call
-
-- Update `src/core/index-manager.ts`:
-  - After incremental re-index (`reindexFiles()`): collect re-indexed symbol IDs
-  - For each re-indexed symbol that previously had an AI-generated summary (detectable by absence of JSDoc/docstring): clear the summary (reset to signature fallback), then re-queue for AI summarization
-  - This ensures stale AI summaries don't persist when code changes
-
-- Update `src/config/config-loader.ts`:
-  - Resolve `'${ENV_VAR}'` references in `ai.apiKey` during load
-  - Warn (do not throw) if `ai.allowRemoteAI` is `true` but `ai.apiKey` is missing
-
-**Key decisions:**
-- OpenAI-compatible support with `fetch` keeps the dependency count low — no `openai` npm package needed
-- Re-summarization on incremental re-index is conservative: only re-summarize symbols that actually changed (content hash comparison), not all symbols in the file
-- `ai.apiKey` env var resolution at load time (not at call time) keeps the hot path simple
-- `ai.batchSize` is configurable because self-hosted models (Ollama) have much lower context limits than cloud APIs
-
-**Verify:** Configure `ai.provider: 'openai-compatible'` with a local Ollama endpoint. Index a small project. Verify AI summaries are generated. Modify a file, trigger re-index — verify the changed symbol's summary is refreshed. Verify `ai.allowRemoteAI: false` still skips AI calls entirely.
-
-**Tests:** OpenAI-compatible provider: mock `fetch`, verify correct payload format, verify response parsing. Retry logic: mock a malformed first response, verify retry with simpler prompt. Re-summarization: stub index manager, verify changed symbols are re-queued but unchanged symbols are not. API key env var resolution.
-
----
-
-## Task 32: Phase 3 Test Fixtures and Integration Tests
-
-Validate the full Phase 3 pipeline end-to-end across all new handlers, adapters, tools, and transports.
-
-**Deliverables:**
-
-- `test/fixtures/python-project/` — representative Python project:
-  - `src/auth/auth.py` — class with methods, decorators, docstrings
-  - `src/utils/format.py` — module-level functions, constants
-  - `src/models/user.py` — dataclass / typed class
-  - `src/api/__init__.py` — empty package file (should produce no symbols)
-  - `tests/test_auth.py` — test file (should be indexed, lower priority)
-  - Imports between files (relative and absolute)
-
-- `test/fixtures/go-project/` — representative Go project:
-  - `main.go` — main package with exported function
-  - `pkg/auth/auth.go` — struct, interface, methods, docstrings
-  - `pkg/utils/format.go` — exported and unexported functions (unexported should be skipped)
-  - `pkg/models/user.go` — struct with exported fields
-  - Import declarations (standard library + internal)
-
-- `test/fixtures/nextjs-project/` — minimal Next.js project:
-  - `package.json` with `"next": "^14.x"` dep
-  - `next.config.js` (triggers detection)
-  - `pages/index.tsx` — home page
-  - `pages/blog/[slug].tsx` — dynamic route
-  - `pages/api/users.ts` — Pages Router API route
-  - `app/page.tsx` — App Router home page
-  - `app/dashboard/page.tsx` — App Router nested page
-  - `app/api/users/route.ts` — App Router API route with `GET` and `POST`
-  - `middleware.ts` — root middleware
-  - `src/components/Button.tsx` — React component (not a Next.js route)
-
-- Integration tests `test/integration/phase3.test.ts`:
-  1. Index `python-project` → verify class, methods, functions extracted with correct byte offsets
-  2. Verify Python docstring captured from `auth.py`
-  3. Verify Python `@decorator` functions extracted with correct name (not the `decorated_definition` node name)
-  4. Index `go-project` → verify exported functions/structs/interfaces extracted, unexported functions NOT extracted
-  5. Verify Go method name includes receiver type (e.g., `AuthService.Login`)
-  6. Verify Go docstring captured from preceding `//` comments
-  7. Index `nextjs-project` → verify Pages Router route `/blog/:slug` produced
-  8. Verify App Router route `/dashboard` produced with `router: 'app'`
-  9. Verify `app/api/users/route.ts` produces two route symbols (GET and POST)
-  10. Verify `src/components/Button.tsx` produces kind `'component'` (React adapter, not Next.js)
-  11. Run `search-text` on `python-project` → verify literal match returns correct line number and context
-  12. Run `search-text` with invalid regex → verify error response, no crash
-  13. Run `get-layer-violations` on PureContext itself with default layer config → verify zero violations
-  14. Start server with `--transport http` → send MCP message via HTTP → verify response
-  15. Phase 1 + Phase 2 tests: run full suite, verify zero regressions
-
-- **Performance benchmark** `test/benchmarks/phase3.bench.ts`:
-  - Index `python-project` → record time and symbol count
-  - Index `go-project` → record time and symbol count
-  - `search-text` on a 200+ file project → verify response under 200ms
-  - Compare Phase 3 symbol counts vs Phase 1 (JS/TS only) on a multi-language project
-
-**Verify:** `npm run test` passes entirely — all Phase 1, 2, and 3 tests green. No regressions. Performance targets from PRD Section 8.2 still met for existing tools.
-
----
-
-## Order of Execution
-
-```
-Task 24: Python language handler          ██░░░░░░░░ Languages
-Task 25: Go language handler              ███░░░░░░░ Languages
-Task 26: Next.js adapter                  ████░░░░░░ Adapters
-Task 27: Security layer                   █████░░░░░ Security
-Task 28: HTTP/SSE transport               ██████░░░░ Transport
-Task 29: Full-text search tool            ███████░░░ Tools
-Task 30: Layer violation analyzer         ████████░░ Tools
-Task 31: AI summarization expansion       █████████░ Summarization
-Task 32: Fixtures + integration tests     ██████████ Polish
-```
-
-Tasks 24 and 25 are fully independent — they can be developed in parallel. Task 26 (Next.js) depends on Phase 2's React adapter being complete but is otherwise independent of Tasks 24–25. Task 27 (security) should be complete before Task 28 (HTTP transport). Tasks 29 and 30 are independent of transport and can start once the core from Phase 1 is stable.
-
-**After Phase 3 is complete**, consider Phase 4: Angular adapter, Express/Fastify/NestJS backend adapters, GitHub repository indexing (`index-repo` tool), and extended language coverage (Rust, Java, C#).