purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE18_TASKS.md

@@ -1,345 +0,0 @@
-# Phase 18 — Team & Cloud Features (Monetization Foundation)
-
-**Goal**: Extend PureContext from a single-user local tool into a team-capable server with shared indexes, API key authentication, and workspace management — the technical foundation for a paid team/cloud tier.
-
-**Scope rationale**: PureContext currently runs on each developer's machine with a local SQLite index. Teams working on the same codebase re-index independently, wasting compute and getting out of sync. A shared index server means: one machine indexes the repo, all team members query it. This is the natural team feature and the natural monetization lever — the server is where access control, billing, and enterprise features live. Phases 16–17 establish a solid open-source single-user product. Phase 18 adds the team layer on top, entirely through the HTTP transport that already exists in `src/server/http-server.ts`.
-
-**Architecture shift:**
-
-```
-Phase 1–17 (local mode):         Phase 18 (server mode):
-  AI Agent                          AI Agent (each team member)
-      ↓ stdio                           ↓ HTTP + API key
-  MCP Server (local)                MCP Server (shared, always-on)
-      ↓                                   ↓
-  Local SQLite index                Shared SQLite index(es)
-                                        ↓
-                                    Workspace + API key DB
-```
-
-Both modes continue to work. `stdio` mode remains the default for individual use. `--server` flag starts the HTTP mode.
-
----
-
-## Task 127: API Key Authentication
-
-Add API key authentication to the HTTP transport so the shared server can authenticate multiple team members.
-
-**Current state**: The HTTP server in `src/server/http-server.ts` has no authentication. Any client with network access can call any endpoint.
-
-**Deliverables:**
-
-- `src/core/db/api-keys.ts` — already exists (from Phase 12). Review and extend:
-  - `createApiKey(db, workspaceId, label, permissions)` — generates a `pctx_` prefixed key (e.g., `pctx_abc123def456`).
-  - `validateApiKey(db, key)` — returns `{ workspaceId, permissions }` or null.
-  - `revokeApiKey(db, keyId)`.
-  - `listApiKeys(db, workspaceId)` — returns keys with labels and last-used timestamps (never the key value itself after creation).
-  - Add `last_used_at` column to `api_keys` table (migration: `ALTER TABLE api_keys ADD COLUMN last_used_at INTEGER`).
-  - Key format: `pctx_` + 32 random hex chars. Store only the SHA-256 hash in DB (never the plaintext).
-
-- `src/server/http-server.ts`:
-  - Add authentication middleware:
-    ```typescript
-    function requireApiKey(req, res, next) {
-      const key = req.headers['authorization']?.replace('Bearer ', '');
-      if (!key) return res.status(401).json({ error: 'API key required. Pass as Authorization: Bearer pctx_...' });
-      const auth = validateApiKey(db, key);
-      if (!auth) return res.status(403).json({ error: 'Invalid or revoked API key.' });
-      req.auth = auth;
-      updateLastUsed(db, key);
-      next();
-    }
-    ```
-  - Apply to all `/api/*` routes.
-  - Exempt: `GET /health`, `GET /` (UI), static assets.
-  - Rate limit per API key (re-use Phase 12 rate limiter, key = API key hash).
-
-- `src/server/admin-api.ts` — already exists (from Phase 12). Extend:
-  - `POST /admin/keys` — create API key. Requires admin key (separate `PCTX_ADMIN_KEY` env var).
-  - `DELETE /admin/keys/:id` — revoke key. Admin only.
-  - `GET /admin/keys` — list keys (without values). Admin only.
-  - `GET /admin/keys/:id/usage` — last used, request count. Admin only.
-
-- `src/config/keys-cli.ts` — already exists. Extend:
-  - `purecontext-mcp keys create --label "Alice's machine"` — creates and prints a key once.
-  - `purecontext-mcp keys list` — lists keys with labels and last-used.
-  - `purecontext-mcp keys revoke <keyId>` — revokes a key.
-  - These commands connect to the local server (or the configured remote URL) using the admin key.
-
-- `src/config/config-schema.ts`:
-  - Add `server.requireAuth: boolean` (default: `false` for local stdio mode, `true` for `--server` mode).
-  - Add `server.adminKey: string` — read from env `PCTX_ADMIN_KEY` first, then config (never commit to source).
-
-**Key technical notes:**
-- In `stdio` mode (default), authentication is disabled entirely — the local user doesn't need API keys to use their own machine.
-- In `--server` mode, authentication is on by default. The first-run message explains how to create a key.
-- The admin key is separate from user API keys. It should only be set via environment variable in production (`PCTX_ADMIN_KEY=...`), never in config.json (which might be committed).
-- Store only SHA-256(key) in the database. The plaintext key is shown once on creation and never again.
-- `pctx_` prefix makes keys easily identifiable in logs and grep.
-
-**Tests:**
-
-- `test/server/api-auth.test.ts`:
-  - Request without key → 401 with helpful message.
-  - Request with invalid key → 403.
-  - Request with valid key → 200, `req.auth` populated.
-  - Revoked key → 403.
-  - `last_used_at` updated on use.
-  - Admin endpoints reject non-admin keys.
-  - `/health` endpoint accessible without auth.
-  - Rate limiter applies per API key (not global).
-
-- `test/cli/keys-cli.test.ts`:
-  - `keys create` prints key once in `pctx_` format.
-  - `keys list` shows labels and masked keys.
-  - `keys revoke` removes key from DB.
-
-**Verify:** Start server with `--server`. Attempt `curl localhost:3000/api/repos` without auth — get 401. Create a key with `keys create`. Use it in `curl -H "Authorization: Bearer pctx_..."`. Get 200.
-
----
-
-## Task 128: Workspace Management
-
-Add workspace support so multiple teams or projects can share one server with isolated indexes.
-
-**Current state**: The multi-tenant framework exists from Phase 12 (`src/core/db/tenants.ts`). Phase 18 surfaces it to users via the CLI and makes it the organizational unit for billing/access control.
-
-**Deliverables:**
-
-- `src/core/db/tenants.ts` — review and extend:
-  - `createWorkspace(db, name, ownerId)` → `workspaceId`.
-  - `listWorkspaces(db)` → all workspaces with member count and repo count.
-  - `addMember(db, workspaceId, userId, role)` — roles: `owner`, `admin`, `member`, `readonly`.
-  - `getWorkspaceForKey(db, apiKeyHash)` — used in auth middleware to scope queries.
-  - Every indexed repo is associated with a workspace: `repos.workspace_id` column.
-
-- `src/core/db/schema.ts`:
-  - Migration: add `workspace_id TEXT` column to `repos` table.
-  - Add `workspaces` table: `id TEXT PK, name TEXT, created_at INTEGER, plan TEXT`.
-  - `plan` values: `'free'` (up to 3 repos, 10k files each), `'team'` (unlimited), `'enterprise'` (unlimited + support).
-  - Default workspace: on first run, create a `default` workspace. All existing repos migrate to it.
-
-- `src/server/tools/index-repo.ts`:
-  - `index_folder` tool: accept optional `workspaceId` parameter. If omitted, use the workspace associated with the API key.
-  - All symbol queries are automatically scoped to `req.auth.workspaceId`.
-
-- `src/server/tools/list-repos.ts`:
-  - Return only repos in the caller's workspace.
-  - Add `workspaceId` field to each repo in the response.
-
-- `src/server/admin-api.ts`:
-  - `POST /admin/workspaces` — create workspace.
-  - `GET /admin/workspaces` — list all workspaces with repo and member counts.
-  - `POST /admin/workspaces/:id/members` — add member with role.
-  - `DELETE /admin/workspaces/:id/members/:userId` — remove member.
-  - `GET /admin/workspaces/:id/usage` — file count, symbol count, API calls this month.
-
-- `src/config/cli.ts`:
-  - `purecontext-mcp workspaces list` — show all workspaces.
-  - `purecontext-mcp workspaces create --name "My Team"` — create workspace, print ID.
-
-- Plan limits enforcement (minimal version):
-  - `free` plan: if workspace has ≥ 3 repos, `index_folder` returns a `LimitError` with message: "Free plan is limited to 3 repos. Upgrade to Team at purecontext.dev/pricing."
-  - File count limit per repo: `free` = 10k, `team` = unlimited.
-  - Limits are checked in `index-manager.ts` before indexing starts.
-  - The `plan` field can be set via admin API (manually, for now — no payment integration in Phase 18).
-
-**Key technical notes:**
-- "Workspace" is the billing unit. One workspace = one paying customer.
-- Workspace isolation is enforced at the query level: `WHERE workspace_id = ?` on all symbol/repo queries. A team member cannot query another workspace's repos, even with a valid key.
-- The default workspace on a local install has `plan: 'team'` (unlimited) so single users are never impacted by limits.
-- Plan limits are intentionally simple in Phase 18 — the goal is to have the infrastructure in place, not to build a full billing system.
-
-**Tests:**
-
-- `test/server/workspace-isolation.test.ts`:
-  - Two workspaces, two API keys. Index a repo in workspace A. Verify workspace B's key cannot see it in `list_repos`.
-  - Query from workspace B returns empty, not an error.
-  - Admin can see all workspaces.
-
-- `test/core/workspace-limits.test.ts`:
-  - `free` plan: index 3 repos (succeeds). Index 4th repo (fails with LimitError, correct message).
-  - `team` plan: index 10 repos (all succeed).
-  - File limit: `free` workspace with 10001 files returns LimitError before indexing starts.
-
-**Verify:** Create two workspaces with separate API keys. Index different repos in each. Confirm each key only sees its own repos. Confirm admin sees both.
-
----
-
-## Task 129: Server Mode — `--server` Flag and Docker Support
-
-Make it easy to deploy PureContext as an always-on shared server for a team, including a Docker image.
-
-**Deliverables:**
-
-- `src/index.ts`:
-  - Add `--server` flag: starts the HTTP server instead of the stdio MCP server.
-  - `--server --port 3000 --host 0.0.0.0` — bind options.
-  - `--server` implies `requireAuth: true` by default (overridable with `--no-auth` for local testing).
-  - Print on startup:
-    ```
-    PureContext MCP Server v1.0.0
-    Listening on http://0.0.0.0:3000
-    Auth: enabled (set PCTX_ADMIN_KEY to manage API keys)
-    Workspaces: 1 (default)
-    ```
-
-- `Dockerfile`:
-  ```dockerfile
-  FROM node:20-slim
-  WORKDIR /app
-  COPY package*.json ./
-  RUN npm ci --omit=dev
-  COPY dist/ ./dist/
-  COPY grammars/ ./grammars/
-  COPY src/ui/dist/ ./src/ui/dist/
-  EXPOSE 3000
-  ENV PCTX_DATA_DIR=/data
-  VOLUME ["/data"]
-  CMD ["node", "dist/index.js", "--server", "--host", "0.0.0.0"]
-  ```
-  - Data volume at `/data` holds indexes and config (maps to `~/.purecontext` behavior).
-  - `PCTX_DATA_DIR` env var overrides the default `~/.purecontext` path.
-
-- `docker-compose.yml` (example, not production):
-  ```yaml
-  version: '3.8'
-  services:
-    purecontext:
-      image: purecontext/purecontext-mcp:latest
-      ports: ["3000:3000"]
-      volumes: ["./data:/data"]
-      environment:
-        PCTX_ADMIN_KEY: "change-me-before-deploying"
-  ```
-
-- `src/config/config-loader.ts`:
-  - Support `PCTX_DATA_DIR` environment variable as the data directory (overrides `~/.purecontext`).
-  - Support `PCTX_ADMIN_KEY`, `PCTX_PORT`, `PCTX_HOST` environment variables.
-  - Priority: env var > config file > default.
-
-- `.github/workflows/docker.yml`:
-  - On release tag push: build Docker image and push to `ghcr.io/org/purecontext-mcp:latest` and `ghcr.io/org/purecontext-mcp:1.0.0`.
-  - Also push to Docker Hub if `DOCKERHUB_TOKEN` secret is set.
-
-- `docs/SELF_HOSTING.md`:
-  - Step-by-step: Docker Compose setup, create admin key, create workspace, create user keys, connect agents.
-  - Environment variable reference.
-  - How to update: pull new image, restart container (SQLite DB is in the volume, persists across updates).
-
-**Key technical notes:**
-- The Docker image must use the prebuilt `better-sqlite3` binary from Phase 16 — no compilation at container startup.
-- `PCTX_DATA_DIR` makes the container stateless (state lives in the volume). This is critical for restarts and updates without data loss.
-- `--no-auth` is intentionally not documented prominently — it's only for local development.
-- The Docker image should be as small as possible. `node:20-slim` base with `--omit=dev` keeps it under 300MB.
-
-**Tests:**
-
-- `test/server/server-mode.test.ts`:
-  - Start server with `--server --port 0` (random port). Assert `/health` returns 200.
-  - Assert auth is required (no key → 401).
-  - Assert `PCTX_DATA_DIR` redirects index storage.
-  - Assert `PCTX_ADMIN_KEY` enables admin endpoints.
-
-- `test/config/env-vars.test.ts`:
-  - `PCTX_PORT=4000` → server binds to 4000.
-  - `PCTX_DATA_DIR=/tmp/test` → config and indexes read from `/tmp/test`.
-  - Env vars override config file values.
-
-**Verify:** `docker build -t purecontext-test .`. `docker run -e PCTX_ADMIN_KEY=testkey -p 3000:3000 purecontext-test`. `curl localhost:3000/health` → 200. `curl -H "Authorization: Bearer testkey" localhost:3000/admin/workspaces` → JSON list.
-
----
-
-## Task 130: MCP-over-HTTP Transport
-
-Expose the full MCP tool set over HTTP (not just the REST API wrappers) so agents can connect to the shared server using the standard MCP HTTP+SSE transport.
-
-**Current state**: The HTTP server exposes REST endpoints that wrap MCP tools (for the Web UI). But AI agents using MCP expect the MCP protocol, not REST. Currently the only MCP transport is stdio (local). Adding MCP-over-HTTP means agents can connect to a remote shared server using the same MCP protocol they use locally.
-
-**MCP HTTP+SSE transport** (as specified by the MCP protocol):
-- Client opens `GET /mcp/sse` → server-sent events stream for server→client messages.
-- Client sends tool calls to `POST /mcp/message` → synchronous JSON responses.
-- Authentication: API key in `Authorization: Bearer` header on both.
-
-**Deliverables:**
-
-- `src/server/transport.ts`:
-  - Implement `HttpSseTransport` class alongside the existing `StdioTransport`.
-  - `HttpSseTransport` handles:
-    - `GET /mcp/sse`: opens SSE stream, registers session.
-    - `POST /mcp/message`: receives tool call JSON, routes to MCP server, returns result.
-    - Session cleanup on disconnect.
-  - Authentication: delegate to the same `requireApiKey` middleware from Task 127.
-
-- `src/server/mcp-server.ts`:
-  - Make the MCP server transport-agnostic: accept either `StdioTransport` or `HttpSseTransport`.
-  - No tool changes needed — all 12 tools work through both transports.
-
-- `src/index.ts`:
-  - In `--server` mode: use `HttpSseTransport` instead of `StdioTransport`.
-  - In stdio mode (default): use `StdioTransport` as before.
-
-- Claude Code integration for remote server:
-  - Document in README how to connect Claude Code to a remote PureContext server:
-    ```bash
-    claude mcp add purecontext-remote \
-      --transport http \
-      --url https://purecontext.mycompany.com/mcp/sse \
-      --header "Authorization: Bearer pctx_yourkey"
-    ```
-  - This is the team use case: one server URL shared across all team members, each with their own API key.
-
-- `docs/TEAM_SETUP.md`:
-  - Full walkthrough: deploy server → create workspace → each developer gets their own API key → add to Claude Code.
-  - Troubleshooting: connection timeouts, auth errors, proxy configuration.
-
-**Key technical notes:**
-- The MCP HTTP+SSE transport is specified by the MCP protocol spec — use `@modelcontextprotocol/sdk`'s HTTP transport implementation if it exists, otherwise implement per the spec.
-- Each SSE connection is one agent session. Multiple agents can connect simultaneously (important for team use).
-- The workspace scoping from Task 128 applies: each API key's tool calls are scoped to its workspace. The agent doesn't need to know about workspaces — scoping is transparent.
-- SSE connections should have a keepalive ping every 30 seconds to prevent proxy/load balancer timeouts.
-
-**Tests:**
-
-- `test/server/mcp-http.test.ts`:
-  - Open SSE connection. Send `list_repos` tool call via POST. Assert result received via SSE.
-  - Two concurrent SSE connections. Assert they don't interfere.
-  - Disconnected client: assert session cleaned up.
-  - Unauthenticated SSE connection: assert 401.
-  - Tool scoping: two API keys in different workspaces each see only their own repos via the same MCP endpoint.
-
-**Verify:** Configure Claude Code with `--transport http` pointing to local test server. Run `list_repos` from Claude Code. Assert repos appear. Run `index_folder` on a remote path. Assert it indexes and symbols are searchable.
-
----
-
-## Order of Execution
-
-```
-Task 127: API key authentication          ████████░░  Foundation (all others depend on it)
-Task 128: Workspace management            ████████░░  After 127 (needs auth for scoping)
-Task 129: --server flag + Docker          ██████░░░░  After 127 (needs auth to be meaningful)
-Task 130: MCP-over-HTTP transport         █████████░  After 127 + 129 (needs server mode)
-```
-
-**Critical path:** 127 → 128 → 129 → 130.
-
-Tasks 128 and 129 have partial independence (Docker doesn't strictly need workspaces), but workspace scoping should be tested in the Docker environment so it's cleaner to do 128 first.
-
----
-
-## Phase 18 Completion
-
-**Before Phase 18:**
-- Local only: each developer maintains their own index.
-- No authentication: any client with network access can call the HTTP API.
-- No team isolation: impossible to share one server across teams.
-- No deployment path: no Docker, no self-hosting docs.
-
-**After Phase 18:**
-- Shared server: one always-on server, multiple team members querying it with individual API keys.
-- Workspace isolation: teams are isolated at the query level.
-- Docker image: `docker run purecontext/purecontext-mcp` starts a production server in minutes.
-- MCP-over-HTTP: agents connect to the remote server using the standard MCP protocol.
-- Monetization foundation: `plan` field on workspaces, limits enforced, admin API for manual plan management. Payment integration (Stripe etc.) is out of scope for Phase 18 — that's Phase 19.
-
-**This phase draws the line between free (individual stdio) and paid (team server).** The individual stdio use case remains completely free and unchanged. The team server is what you charge for.

package/docs/dev/PHASE19_TASKS.md

@@ -1,261 +0,0 @@
-# Phase 19 — Missing Core Tools
-
-**Goal**: Close the four most significant tool-level gaps versus jCodeMunch: batch symbol retrieval, raw file content access, identifier-level reference search, and cache invalidation.
-
-**Scope rationale**: These are foundational capabilities. AI agents regularly need to fetch a known list of symbols in one round-trip, retrieve arbitrary file content, find all *usages* of a symbol (not just imports), and force a clean re-index. None of these are hard to build and all unblock real workflows that currently require awkward workarounds.
-
----
-
-## Task 131: `find_references` Tool
-
-Find every file that *uses* (calls, references) a given identifier across the indexed repo — distinct from `find_importers`, which works at the import-statement level.
-
-**Current state**: `find_importers` traverses the `dep_edges` table to find files that import a given file. There is no tool that finds files containing actual *usage* of a named identifier (function call, type reference, variable access).
-
-**Deliverables**:
-
-- `src/server/tools/find-references.ts` — new MCP tool
-  ```typescript
-  interface FindReferencesInput {
-    repoId: string;
-    identifier: string;         // Symbol name to search for
-    kind?: SymbolKind;          // Optional: narrow to a specific kind
-    includeDefinition?: boolean; // Default false — exclude the file that defines it
-  }
-
-  interface ReferenceLocation {
-    filePath: string;
-    lineNumber: number;
-    lineContent: string;        // Trimmed line showing the reference in context
-    symbolContext?: string;     // Name of the enclosing symbol, if detectable
-  }
-
-  interface FindReferencesOutput {
-    identifier: string;
-    totalFiles: number;
-    references: ReferenceLocation[];
-    _meta: ResponseMeta;
-  }
-  ```
-- Implementation strategy: use the existing `search_text` infrastructure to scan cached file content for word-boundary matches of the identifier, then cross-reference against the `symbols` table to determine line numbers and enclosing symbols
-- Word-boundary matching: `\bidentifier\b` regex to avoid false positives (e.g. `setUser` not matching `setUserName`)
-- When `includeDefinition: false`, exclude files where the identifier is a top-level symbol definition in `symbols` table
-- Register tool in `src/server/mcp-server.ts`
-
-**Key technical notes**:
-- This is a text-search over cached file content — not AST-aware. AST-aware reference tracking is out of scope (requires full name resolution)
-- The distinction from `find_importers`: that tool uses the dependency graph (import statements); this tool scans actual content for identifier occurrences
-- `symbolContext` can be derived by finding which symbol's byte range contains the matched line
-- Respect the same file filter / exclusion list as other tools (node_modules, generated files)
-- Performance: for large repos use the FTS5 `files_fts` table if available; fall back to scanning `file_store` rows
-
-**Tests**: `test/server/find-references.test.ts`
-- Reference found in multiple files
-- Definition file excluded when `includeDefinition: false`
-- Word-boundary matching (no false positives on partial names)
-- `kind` filter narrows results
-- Returns `_meta` with token savings
-
-**Verify**:
-```bash
-# After indexing a project
-npx purecontext-mcp  # then via MCP client:
-# find_references { repoId: "...", identifier: "parseSymbol", includeDefinition: false }
-```
-
----
-
-## Task 132: `get_file_content` Tool
-
-Retrieve raw cached file content for any indexed file, with optional line-range slicing.
-
-**Current state**: `get_symbol_source` retrieves the source of a specific symbol by byte offsets. There is no way for an agent to retrieve an arbitrary file's content or a line range within it — agents are forced to use `get_symbol_source` repeatedly or request entire outlines.
-
-**Deliverables**:
-
-- `src/server/tools/get-file-content.ts` — new MCP tool
-  ```typescript
-  interface GetFileContentInput {
-    repoId: string;
-    filePath: string;           // Relative to repo root
-    startLine?: number;         // 1-based, inclusive. Omit for start of file
-    endLine?: number;           // 1-based, inclusive. Omit for end of file
-    withLineNumbers?: boolean;  // Default true — prefix each line with its number
-  }
-
-  interface GetFileContentOutput {
-    filePath: string;
-    totalLines: number;
-    returnedLines: number;
-    content: string;
-    _meta: ResponseMeta;
-  }
-  ```
-- Read from `file_store` (the existing cached content table in `src/core/db/file-store.ts`)
-- Apply line slicing after splitting on `\n`
-- When `withLineNumbers: true`, prefix lines: `  42 │ const x = ...`
-- If the file is not in the cache (not yet indexed), return a clear error: `FileNotCachedError`
-- Register tool in `src/server/mcp-server.ts`
-
-**Key technical notes**:
-- Do not read from disk — always serve from the SQLite `file_store` cache. This guarantees consistency with the indexed symbol offsets
-- Impose a max return size: 500 lines per call (configurable via `MAX_FILE_CONTENT_LINES` env var). If range exceeds limit, return first N lines and indicate truncation in `_meta`
-- `filePath` must be validated against `path.normalize` to prevent path traversal — reject any path containing `..`
-- Token savings calculation: compare returned content size vs full file size
-
-**Tests**: `test/server/get-file-content.test.ts`
-- Full file retrieval
-- Line range slicing (start/end combinations)
-- `withLineNumbers` formatting
-- Path traversal rejection
-- Max lines truncation with indicator
-- File not cached → `FileNotCachedError`
-
-**Verify**:
-```bash
-# get_file_content { repoId: "...", filePath: "src/core/types.ts", startLine: 1, endLine: 50 }
-```
-
----
-
-## Task 133: `get_symbols` Batch Retrieval Tool
-
-Fetch full source for a list of known symbol IDs in a single MCP call.
-
-**Current state**: `get_symbol_source` retrieves one symbol per call. Agents that have identified a set of relevant symbols (e.g. from `search_symbols` results) must make N sequential calls. `search_symbols` returns metadata but not source.
-
-**Deliverables**:
-
-- `src/server/tools/get-symbols.ts` — new MCP tool
-  ```typescript
-  interface GetSymbolsInput {
-    repoId: string;
-    symbolIds: string[];        // Up to 50 symbol IDs per call
-    contextLines?: number;      // Optional: N lines of surrounding context per symbol
-    verify?: boolean;           // Check content hash against disk before returning
-  }
-
-  interface SymbolResult {
-    symbolId: string;
-    name: string;
-    kind: SymbolKind;
-    filePath: string;
-    source: string;
-    signature: string;
-    summary: string;
-    hashDrift?: boolean;        // Only present when verify: true
-  }
-
-  interface GetSymbolsOutput {
-    found: SymbolResult[];
-    notFound: string[];         // Symbol IDs that didn't exist
-    _meta: ResponseMeta;
-  }
-  ```
-- Batch-fetch from `symbol_store` using `WHERE id IN (...)` — single SQL query
-- Retrieve source for each via byte offsets from `file_store` (same logic as `get_symbol_source`)
-- `contextLines`: expand byte range by N lines before/after the symbol boundaries
-- `verify`: re-hash the file from disk and compare against `files.content_hash`; set `hashDrift: true` if mismatch
-- Cap at 50 symbol IDs per call; return `TooManySymbolsError` if exceeded
-- Register tool in `src/server/mcp-server.ts`
-
-**Key technical notes**:
-- Single SQL `IN` query is more efficient than N individual lookups — this is the main value proposition
-- For `contextLines`, convert byte offsets to line numbers, then expand, then re-convert to byte range. Store line-indexed views in memory rather than re-scanning the full file
-- `verify` is expensive (disk read per unique file) — only do it when explicitly requested
-- Token savings: sum of all symbol source sizes returned
-
-**Tests**: `test/server/get-symbols.test.ts`
-- Batch fetch of 3 known symbols
-- Mixed found/not-found IDs
-- `contextLines` expansion
-- `verify` with matching hash
-- `verify` with hash drift detection
-- Exceeding 50 IDs → `TooManySymbolsError`
-
-**Verify**:
-```bash
-# get_symbols { repoId: "...", symbolIds: ["abc123", "def456", "ghi789"] }
-```
-
----
-
-## Task 134: `invalidate_cache` Tool
-
-Delete a repo's index from the database, forcing a full re-index on the next `index_folder` or `index_repo` call.
-
-**Current state**: There is no way for users or agents to clear a stale or corrupted index without manually deleting the SQLite file. This is a common need when the codebase has been heavily restructured, when the index gets corrupted, or when testing.
-
-**Deliverables**:
-
-- `src/server/tools/invalidate-cache.ts` — new MCP tool
-  ```typescript
-  interface InvalidateCacheInput {
-    repoId?: string;    // Invalidate a specific repo by ID
-    repoPath?: string;  // Or resolve by path (converted to repoId internally)
-    all?: boolean;      // Nuke all indexed repos (requires explicit confirmation)
-  }
-
-  interface InvalidateCacheOutput {
-    deleted: {
-      repoId: string;
-      repoPath: string;
-      symbolsDeleted: number;
-      filesDeleted: number;
-    }[];
-    _meta: ResponseMeta;
-  }
-  ```
-- Exactly one of `repoId`, `repoPath`, or `all: true` must be provided
-- Deletion sequence (all in a single SQLite transaction):
-  1. Delete from `dep_edges` where `source_file` in repo
-  2. Delete from `symbols` where `repo_id = ?`
-  3. Delete from `files` where `repo_id = ?`
-  4. Delete from `repos` where `id = ?`
-- Return counts of deleted rows for confirmation
-- When `all: true`, iterate over all repos and delete each
-- Add `invalidateCache(repoId: string): InvalidateResult` to `src/core/db/symbol-store.ts`
-- Register tool in `src/server/mcp-server.ts`
-
-**Key technical notes**:
-- Use a single transaction to ensure atomicity — partial deletion leaves the DB in a valid but inconsistent state
-- After invalidation the HNSW semantic index (if present) must also be cleared for that repo — call the semantic index cleanup hook
-- Log the operation at `info` level: repo ID, path, rows deleted
-- Do NOT delete the SQLite file itself — just the rows. This avoids re-creating the schema and is safer if the DB is shared
-
-**Tests**: `test/server/invalidate-cache.test.ts`
-- Invalidate by `repoId`
-- Invalidate by `repoPath`
-- `all: true` clears all repos
-- Missing both `repoId` and `repoPath` → validation error
-- Verify rows are gone after invalidation
-- Subsequent `index_folder` re-indexes successfully
-
-**Verify**:
-```bash
-# invalidate_cache { repoId: "abc123def456" }
-# Then: index_folder { path: "/path/to/repo" }  # Should re-index from scratch
-```
-
----
-
-## Order of Execution
-
-Tasks are independent and can be parallelized:
-
-```
-131 (find_references)    ──┐
-132 (get_file_content)   ──┤──▶ All can land in any order
-133 (get_symbols)        ──┤
-134 (invalidate_cache)   ──┘
-```
-
-`get_symbols` (133) reuses logic from `get_symbol_source` — implement that first if doing sequentially.
-
----
-
-## Phase 19 Completion
-
-**Before**: 18 tools, no identifier-level reference search, no raw file retrieval, no batch symbol fetch, no cache invalidation.
-
-**After**: 22 tools. Agents can fetch a known symbol list in one call, retrieve file content by line range, find all usages of any identifier, and force a clean re-index — closing the four largest day-to-day workflow gaps vs jCodeMunch.