memory-journal-mcp 7.7.0 → 8.0.0

package/skills/agents-sdk/references/mcp/references/cloudflare-quickstart.md

@@ -0,0 +1,156 @@
+# Building MCP Servers on Cloudflare
+
+Creates production-ready Model Context Protocol servers on Cloudflare Workers with tools, authentication, and deployment.
+
+## Prerequisites
+
+- Cloudflare account with Workers enabled
+- Node.js 18+ and npm/pnpm/yarn
+- Wrangler CLI (`npm install -g wrangler`)
+
+## Quick Start
+
+### Option 1: Public Server (No Auth)
+
+```bash
+npm create cloudflare@latest -- my-mcp-server \
+  --template=cloudflare/ai/demos/remote-mcp-authless
+cd my-mcp-server
+npm start
+```
+
+Server runs at `http://localhost:8788/mcp`
+
+### Option 2: Authenticated Server (OAuth)
+
+```bash
+npm create cloudflare@latest -- my-mcp-server \
+  --template=cloudflare/ai/demos/remote-mcp-github-oauth
+cd my-mcp-server
+```
+
+Requires OAuth app setup.
+
+## Core Workflow
+
+### Step 1: Define Tools
+
+Tools are functions MCP clients can call. Define them using `server.tool()`:
+
+```typescript
+import { McpAgent } from 'agents/mcp'
+import { z } from 'zod'
+
+export class MyMCP extends McpAgent {
+  server = new Server({ name: 'my-mcp', version: '1.0.0' })
+
+  async init() {
+    // Simple tool with parameters
+    this.server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }) => ({
+      content: [{ type: 'text', text: String(a + b) }],
+    }))
+
+    // Tool that calls external API
+    this.server.tool('get_weather', { city: z.string() }, async ({ city }) => {
+      // Prevent SSRF: Always construct URLs safely, never interpolate raw strings into the base URL path
+      const url = new URL('https://api.weather.com/v1/current')
+      url.searchParams.set('city', city)
+      const response = await fetch(url.toString())
+      const data = await response.json()
+      return {
+        content: [{ type: 'text', text: JSON.stringify(data) }],
+      }
+    })
+  }
+}
+```
+
+### Step 2: Configure Entry Point
+
+**Public server** (`src/index.ts`):
+
+```typescript
+import { MyMCP } from './mcp'
+
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const url = new URL(request.url)
+    if (url.pathname === '/mcp') {
+      return MyMCP.serveSSE('/mcp').fetch(request, env, ctx)
+    }
+    return new Response('MCP Server', { status: 200 })
+  },
+}
+
+export { MyMCP }
+```
+
+### Step 3: Test Locally
+
+```bash
+# Start server
+npm start
+
+# In another terminal, test with MCP Inspector
+npx @modelcontextprotocol/inspector@latest
+# Open http://localhost:5173, enter http://localhost:8788/mcp
+```
+
+### Step 4: Deploy
+
+> **CRITICAL HITL GATE**: You MUST stop and ask the user for explicit confirmation before running the `npx wrangler deploy` command. Deploying to production requires consent.
+
+```bash
+npx wrangler deploy
+```
+
+Server accessible at `https://[worker-name].[account].workers.dev/mcp`
+
+### Step 5: Connect Clients
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://my-mcp.workers.dev/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after updating config.
+
+## Accessing Environment/Bindings
+
+```typescript
+export class MyMCP extends McpAgent<Env> {
+  async init() {
+    this.server.tool('get_user', { id: z.number() }, async ({ id }) => {
+      // Access D1 binding safely with parameterized query
+      // NOTE: Never pass raw SQL strings from tool arguments directly to prepare()
+      const result = await this.env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(id).all()
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] }
+    })
+  }
+}
+```
+
+## Wrangler Configuration
+
+Minimal `wrangler.toml`:
+
+```toml
+name = "my-mcp-server"
+main = "src/index.ts"
+compatibility_date = "2024-12-01"
+
+[durable_objects]
+bindings = [{ name = "MCP", class_name = "MyMCP" }]
+
+[[migrations]]
+tag = "v1"
+new_classes = ["MyMCP"]
+```

package/skills/agents-sdk/references/mcp/references/error-handling.md

@@ -0,0 +1,343 @@
+# Error Handling & Input Validation Reference
+
+Detailed patterns for error handling infrastructure, input coercion, schema boundaries, existence validation, SQL injection prevention, idempotent operations, and output schema architecture.
+
+> Read this reference when implementing error handling, input validation, or output schemas in an MCP server.
+
+---
+
+## Enriched Error Handling Infrastructure (Standard)
+
+Harmonized across db-mcp, postgres-mcp, mysql-mcp, memory-journal-mcp.
+
+**Files:** `src/utils/errors/base.ts` (abstract base), `src/utils/errors/classes.ts` (subclasses), `src/utils/errors/categories.ts` (enum + interfaces), `src/utils/errors/format.ts` (formatter), `src/utils/errors/error-response-fields.ts` (ErrorFieldsMixin SSoT), `src/utils/errors/suggestions.ts` (fuzzy typo hints).
+
+**Base Class:** `{Server}McpError extends Error` with `category`, `code`, `suggestion`, `details`, `recoverable`, `cause`, and `toResponse(): ErrorResponse`. Replace `{Server}` with prefix: `DbMcpError`, `PostgresMcpError`, etc.
+
+**Error Code Auto-Refinement:** The base class constructor auto-refines generic codes to specific ones. When a `QueryError` (code: `DB_QUERY_FAILED`) has an error message matching a known pattern (like "no such table"), the constructor auto-refines the code to `TABLE_NOT_FOUND`. This ensures consistent, machine-readable codes across all tools without manual mapping in each handler.
+
+The auto-refinement mechanism:
+
+- `ERROR_SUGGESTIONS` entries include an optional `code` field
+- Constructor checks if the current code is generic (from a whitelist: `DB_QUERY_FAILED`, `DB_WRITE_FAILED`, `QUERY_ERROR`, `RESOURCE_ERROR`, `UNKNOWN_ERROR`)
+- If generic AND a matched suggestion has a specific `code`, the specific code replaces the generic one
+- Supported refinements: `TABLE_NOT_FOUND`, `COLUMN_NOT_FOUND`, `VIEW_NOT_FOUND`, `FILE_NOT_FOUND`, `MALFORMED_JSON`, `TRANSACTION_CONFLICT`, `DIMENSION_MISMATCH`, `VECTOR_NOT_FOUND`, `DUPLICATE_MIGRATION`, `DUPLICATE_VERSION`, `ALREADY_ROLLED_BACK`, etc.
+
+**Standard Subclasses:**
+
+| Subclass                     | Code                  | Category       | Recoverable |
+| ---------------------------- | --------------------- | -------------- | ----------- |
+| `ConnectionError`            | `CONNECTION_FAILED`   | connection     | false       |
+| `QueryError`                 | `QUERY_FAILED`        | query          | true        |
+| `ValidationError`            | `VALIDATION_FAILED`   | validation     | true        |
+| `ResourceNotFoundError`      | `RESOURCE_NOT_FOUND`  | resource       | true        |
+| `ConfigurationError`         | `CONFIGURATION_ERROR` | configuration  | false       |
+| `PermissionError`            | `PERMISSION_DENIED`   | permission     | true        |
+| `TransactionError`           | `TRANSACTION_FAILED`  | query          | true        |
+| `InternalError`              | `INTERNAL_ERROR`      | internal       | false       |
+| `AuthenticationError`        | `AUTH_FAILED`         | authentication | false       |
+| `AuthorizationError`         | `AUTH_SCOPE_DENIED`   | authorization  | true        |
+| `ExtensionNotAvailableError` | `EXTENSION_MISSING`   | configuration  | false       |
+
+`TransactionError` accepts optional `ErrorContext` (`tool`, `table`, `sql`) for diagnostic context. `ExtensionNotAvailableError` auto-generates a `suggestion` field containing the extension name (e.g., `"Install the SpatiaLite extension: --spatialite"`).
+
+DB servers also add `PoolError` (code: `POOL_ERROR`, category: connection, recoverable: false).
+
+**Single Formatter:** `formatHandlerError(err, context?)` — handles `{Server}McpError` (`.toResponse()`), `ZodError` (extracts field paths, e.g., `table: Required`), and raw `Error` (matches `ERROR_SUGGESTIONS`). Use in every handler's `catch` block.
+
+**Context-Aware Variant (DB Servers):** For database-backed servers, pass an `ErrorContext` parameter (`{tool, sql?, table?, schema?, target?, objectType?}`) to enable engine-specific error code mapping. The context flows into the engine's error parser for actionable diagnostics.
+
+```typescript
+// Context-aware formatter:
+return formatHandlerError(error, { tool: 'pg_create_index', table: 'users' })
+```
+
+**Engine-Specific Error Parsers:** For DB servers, implement a dedicated `error-parser.ts` in the engine's `tools/core/` directory. This parser maps database-native error codes (e.g., PostgreSQL `42P01` → `TABLE_NOT_FOUND`, MySQL `1146` → `TABLE_NOT_FOUND`) to structured error subclasses. Complementary to `ERROR_SUGGESTIONS` auto-refinement — the parser handles raw database exceptions, while auto-refinement handles error message pattern matching in the base class constructor.
+
+> [!IMPORTANT]
+> **Use ONE formatter, not two.** All handler catch blocks must use `return formatHandlerError(error)` or `return formatHandlerError(error, context)` — never re-wrap the result.
+
+**`structuredContent` on Error Responses:** When a tool has an `outputSchema`, the `registerTool()` wrapper must include `structuredContent` on error responses so clients receive machine-readable error payloads:
+
+```typescript
+// In registerTool() catch block:
+if (toolDef.outputSchema) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(errorResult) }],
+    structuredContent: errorResult,
+    isError: true,
+  }
+}
+```
+
+**ErrorFieldsMixin** — merge into every `outputSchema`:
+
+```typescript
+export const ErrorFieldsMixin = z.object({
+  error: z.string().optional(),
+  code: z.string().optional(),
+  category: z.string().optional(),
+  suggestion: z.string().optional(),
+  recoverable: z.boolean().optional(),
+  details: z.unknown().optional(),
+})
+
+// Usage: z.object({ success: z.boolean(), result: z.string().optional() }).extend(ErrorFieldsMixin.shape);
+```
+
+> [!CAUTION]
+> **`outputSchema` + `structuredContent` pitfall:** If `formatHandlerError()` returns error fields but the schema has required success-path fields (e.g., `result: z.string()`), Zod validation fails. **All success-path fields must be `.optional()`.**
+
+**Integration:** `OAuthError` and `SecurityError` (with `InvalidDateFormatError`, `PathTraversalError`) both extend the server's base class, inheriting `toResponse()` and structured error semantics.
+
+> [!IMPORTANT]
+> **Error classification:** Input validation errors → Tool Execution Errors (`isError: true`), not Protocol Errors. Tool errors enable model self-correction; protocol errors don't.
+
+---
+
+## Input Coercion & Refinement Leak Prevention
+
+The MCP SDK wraps `inputSchema` with `.partial()` before validation. This means Zod refinements (`.min()`, `.max()`, `.regex()`, `z.enum()`) can leak raw `-32602` protocol errors before handler code can intercept them. This is the #1 source of "conversation-killer" errors in agent orchestration.
+
+**Required patterns:**
+
+| Input Type    | Registration Schema                                                                                   | Handler Validation                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Required enum | `z.string().describe("One of: a, b, c")`                                                              | Validate against exported `const VALID_VALUES = ['a', 'b', 'c'] as const` in handler |
+| Optional enum | `z.preprocess(coerceEnumValues(VALID_VALUES, 'default'), z.enum(VALID_VALUES))`                       | Or use `z.string().optional()` + handler validation                                  |
+| Numeric param | `z.preprocess(coerceNumber, z.number().optional())` **or** `z.coerce.number().optional()` + NaN guard | See tradeoffs below                                                                  |
+| Boolean param | `z.preprocess(coerceBoolean, z.boolean().optional())`                                                 | Handle `"true"`, `"false"` string inputs                                             |
+| Array param   | `z.preprocess(v => Array.isArray(v) ? v : [], z.array(...))`                                          | Coerce non-arrays to empty arrays for `.partial()` compatibility                     |
+| Refinements   | Move `.min()`, `.max()`, `.regex()` to handler-level validation                                       | Never put these on the registration schema                                           |
+
+**Numeric coercion — two acceptable approaches:**
+
+| Approach                          | Pros                                            | Cons                                                  | Used By                                     |
+| --------------------------------- | ----------------------------------------------- | ----------------------------------------------------- | ------------------------------------------- |
+| `z.preprocess(coerceNumber, ...)` | Returns `undefined` on bad input (safe default) | More verbose, requires custom helper                  | db-mcp, mysql-mcp, postgres-mcp (migrating) |
+| `z.coerce.number().optional()`    | Idiomatic Zod, less boilerplate                 | Produces `NaN` on `"abc"` — **must guard in handler** | postgres-mcp (legacy, being replaced)       |
+
+When using `z.coerce.number()`, always guard against NaN in the handler — ideally via `coerceLimit()` (see below) or an explicit `isNaN()` check before using the value.
+
+**Coercion factories (for `z.preprocess` approach):**
+
+```typescript
+export function coerceNumber(val: unknown): unknown {
+  if (typeof val === 'number') return val
+  if (typeof val === 'string') {
+    const n = Number(val)
+    return Number.isNaN(n) ? undefined : n
+  }
+  return undefined
+}
+
+export function coerceBoolean(val: unknown): unknown {
+  if (typeof val === 'boolean') return val
+  if (val === 'true') return true
+  if (val === 'false') return false
+  return undefined
+}
+```
+
+**Limit Coercion (Standard):** For `limit` parameters (ubiquitous across DB tools), use shared helpers in `utils/query-helpers.ts`:
+
+```typescript
+export const DEFAULT_QUERY_LIMIT = 100
+
+/** Coerce raw limit → usable value. 0 = unlimited (null), NaN/undefined → default. */
+export function coerceLimit(raw: unknown, defaultLimit = DEFAULT_QUERY_LIMIT): number | null {
+  if (raw === undefined) return defaultLimit
+  const num = Number(raw)
+  if (isNaN(num)) return defaultLimit
+  if (num === 0) return null
+  return num > 0 ? num : defaultLimit
+}
+
+/** Build SQL LIMIT clause from coerced value. null = no limit. */
+export function buildLimitClause(limitVal: number | null): string {
+  return limitVal !== null ? ` LIMIT ${String(limitVal)}` : ''
+}
+```
+
+> [!TIP]
+> `coerceLimit()` safely handles both `z.preprocess` and `z.coerce.number()` outputs — it guards NaN, undefined, and zero semantics in one place.
+
+---
+
+## Input Schema Boundary Handling
+
+The SDK wraps `inputSchema` with `.partial()` before validation. Two approaches exist for handling this safely:
+
+**Approach A — Dual-Schema Pattern (Preferred):** Define two schemas per tool — a strict `XxxSchema` for handler-level validation and a relaxed `XxxSchemaMcp` for SDK registration. The `SchemaMcp` variants use coercion factories (e.g., `relaxedNumber()`, `relaxedArray()`) to handle type mismatches from agent inputs.
+
+```typescript
+// Strict schema (handler-level validation):
+const SearchEntriesSchema = z.object({
+  query: z.string().min(1),
+  limit: z.number().optional(),
+  tags: z.array(z.string()).optional(),
+});
+
+// Relaxed schema (SDK registration — coercion, no refinements):
+const SearchEntriesSchemaMcp = z.object({
+  query: z.string().describe('Search query'),
+  limit: relaxedNumber().describe('Max results'),
+  tags: relaxedArray(z.string()).describe('Filter by tags'),
+});
+
+// Registration uses relaxed schema:
+{ name: 'search_entries', inputSchema: SearchEntriesSchemaMcp, ... }
+
+// Handler uses strict schema:
+try {
+  const parsed = SearchEntriesSchema.parse(params);
+  // ... business logic
+} catch (error) {
+  return formatHandlerError(error);
+}
+```
+
+**Why this is preferred:** Explicit schema separation prevents `.partial()` from masking required field validation. Coercion is handled at the schema level rather than requiring post-parse handling. The SDK's internal wrapping behavior has changed between versions, making explicit schema separation more robust.
+
+**Coercion factories** (used in `SchemaMcp` variants):
+
+```typescript
+/** Relaxed number that accepts string/number/undefined without crashing SDK */
+export function relaxedNumber() {
+  return z.preprocess(coerceNumber, z.number().optional())
+}
+
+/** Relaxed array that accepts non-arrays gracefully */
+export function relaxedArray<T extends z.ZodTypeAny>(item: T) {
+  return z.preprocess((v) => (Array.isArray(v) ? v : []), z.array(item).optional())
+}
+```
+
+**Approach B — `.partial().passthrough()` Wrapping:** For adapter-based servers (db-mcp, postgres-mcp) where schemas are generated or engine-specific, wrap `inputSchema` directly.
+
+```typescript
+// In registerTool():
+const sdkSchema = toolDef.inputSchema.partial().passthrough()
+
+// In handler:
+try {
+  const resolved = resolveAliases(params) // tableName → table, sql → query
+  const parsed = StrictSchema.parse(resolved)
+  // ... business logic
+} catch (error) {
+  return formatHandlerError(error)
+}
+```
+
+**Two boundaries (both approaches):**
+
+- **SDK boundary:** relaxed schema or `.partial().passthrough()` — accepts any parameter subset
+- **Handler boundary:** strict `Schema.parse(params)` inside try/catch → `formatHandlerError()`
+
+**Backward-compatible aliases:** Use `resolveAliases()` preprocess before Zod parsing. Canonical names take precedence when both alias and canonical are supplied.
+
+---
+
+## Proactive Existence Validation
+
+All database tools must validate object existence before executing DML. This prevents raw SQL errors from leaking to the client and ensures consistent, machine-readable error codes across the fleet.
+
+**Validation hierarchy:** TABLE_NOT_FOUND → COLUMN_NOT_FOUND → domain-specific validation.
+
+**Standard validators** (in shared `tools/column-validation.ts`):
+
+- `validateTableExists(adapter, table)` — checks system catalog before proceeding
+- `validateColumnExists(adapter, table, column)` — checks table existence _first_, then column via metadata query
+- `validateColumnsExist(adapter, table, columns)` — batch version, single metadata query + in-memory membership check (N+1 elimination)
+- All return structured `{success: false, code: "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND"}` errors
+
+**Usage:** Imported by geo, stats, text, FTS, vector, window tool groups.
+
+---
+
+## WHERE Clause Validation (SQL Injection Prevention)
+
+Every tool that interpolates a user-provided `whereClause` into SQL must call `validateWhereClause()` before SQL construction. This is non-negotiable for multi-agent orchestration where WHERE clauses may originate from untrusted agent chains.
+
+**Blocked patterns:**
+
+- Semicolon-chained keywords: `; SELECT`, `; DROP`, `; INSERT`, `; UPDATE`, `; DELETE`, `; ALTER`, `; CREATE`
+- Comment injection: `--`, `/* */`
+- String-literal stripping: test blocked patterns against SQL with string literals removed (prevents false positives on quoted values)
+- Semicolon-chained blocking requires the semicolon prefix (allows legitimate `IN (SELECT ...)`)
+
+**Implementation:** `src/utils/where-clause.ts` — shared utility imported by all tools with `whereClause` parameters.
+
+**FTS Configuration Validation (DB Servers):** For servers with full-text search, validate FTS configuration names (e.g., `'english'`, `'my_custom_config'`) against database identifier rules via `validateFtsConfig()` in `utils/fts-config.ts`. This prevents SQL injection through the FTS config parameter — a vector that `validateWhereClause()` doesn't cover since config names are interpolated outside WHERE clauses.
+
+---
+
+## Idempotent Operation Reporting
+
+Tools that create or drop objects must distinguish between "action taken" and "no-op" responses. This is critical for idempotent workflow design in agent orchestration.
+
+**Pattern:**
+
+- Pre-check existence before `CREATE ... IF NOT EXISTS` or `DROP ... IF EXISTS`
+- Return `alreadyExists: true` or `alreadyDropped: true` flag in response
+- Return descriptive message: `"Index 'idx_name' already exists (no changes made)"`
+- Prevents misleading success messages that don't reflect actual state changes
+
+```typescript
+// Before CREATE INDEX IF NOT EXISTS:
+const exists = await checkIndexExists(adapter, indexName)
+if (exists) {
+  return {
+    success: true,
+    alreadyExists: true,
+    message: `Index '${indexName}' already exists (no changes made)`,
+  }
+}
+await adapter.execute(`CREATE INDEX ${indexName} ...`)
+return { success: true, alreadyExists: false, message: `Index '${indexName}' created` }
+```
+
+---
+
+## Output Schema Architecture
+
+Output schemas must **never be inline** in handler files. Two organizational patterns exist depending on server type:
+
+**Pattern A — Co-located `schemas.ts` (Non-adapter servers):** Output schemas live in `schemas.ts` files alongside their handler groups. Input schemas may be co-located in handler files when using the dual-schema pattern.
+
+```
+handlers/tools/
+  schemas.ts              — Shared output schemas (core, search, admin, etc.)
+  error-fields-mixin.ts   — Re-export stub → utils/errors/error-response-fields.ts
+  github/
+    schemas.ts            — GitHub-specific output schemas (16 tools)
+  team/
+    schemas.ts            — Team-specific output schemas (20 tools)
+```
+
+This pattern works well when schemas are tightly coupled to their handler groups and the server uses the dual-schema input pattern. Output schemas are centralized per group; input schemas stay with handlers for locality.
+
+**Pattern B — Top-level `schemas/` directory (Adapter-based servers):** For servers with engine-specific schemas (db-mcp, postgres-mcp, mysql-mcp), output schemas live in a centralized directory.
+
+```
+schemas/                         # (or output-schemas/)
+  error-response-fields.ts — ErrorFieldsMixin (6 optional error fields, SSoT)
+  core-exports.ts          — Core schema barrel exports
+  extension-exports.ts     — Extension schema barrel exports
+  core/                    — Core group schemas (input + output per file)
+  jsonb/                   — JSONB group schemas
+  stats/                   — Stats group schemas (base, input, output, preprocessing)
+  vector/                  — Vector group schemas (input, output)
+  postgis/                 — PostGIS group schemas
+  extensions/              — Extension schemas (citext, ltree, pgcrypto, kcache, shared)
+  {group}/                 — One subdirectory per additional tool group
+  index.ts                 — Barrel re-export
+```
+
+**Rules (both patterns):**
+
+- Zero inline output schema `z.object()` definitions in handler files — import from dedicated `schemas.ts` or `schemas/` directory
+- All output schemas extend `ErrorFieldsMixin.shape` — domain fields are `.optional()` so error responses pass validation
+- Every group gets its own file (no stuffing unrelated schemas into `common.ts`)
+- Bespoke schemas over generic: `ListViewsOutputSchema` not reusing `ListTablesOutputSchema` ("Shared Template Fatigue" prevention)
+- Orphan schema detection: no schemas should exist without corresponding tools

package/skills/agents-sdk/references/mcp/references/http-security.md

@@ -0,0 +1,164 @@
+# HTTP Transport & Security Reference
+
+Detailed patterns for OAuth 2.1 authentication, HTTP transport hardening, security headers, rate limiting, CORS, and dual-protocol support.
+
+> Read this reference when implementing HTTP/SSE transport or OAuth authentication for an MCP server.
+
+---
+
+## OAuth 2.1 Authentication (Required for production HTTP servers)
+
+All production HTTP servers must implement OAuth 2.1 as opt-in. Fallback chain: OAuth → simple token (`MCP_AUTH_TOKEN`) → no auth. `jose` is a transitive dependency of `@modelcontextprotocol/sdk`.
+
+**Module:** `src/auth/` — 11 files. `OAuthError` extends server's base error class with `httpStatus` + `wwwAuthenticate`. Category auto-inferred (401 → AUTHENTICATION, 403 → AUTHORIZATION). 5 CLI flags with env var fallbacks. `/.well-known/oauth-protected-resource` always registered.
+
+> [!TIP]
+> The `src/auth/` module is copy-pasteable between servers. Only `scopes.ts`, `scope-map.ts`, and the `extends` declaration need customization.
+
+> See [`oauth-reference.md`](../oauth-reference.md) for module structure, RFC compliance, scope model, error hierarchy, token validation, middleware patterns, CLI flags, testing (8 test files), and integration checklist.
+
+---
+
+## HTTP Transport Hardening (Required for HTTP/SSE servers)
+
+**Modular Architecture:**
+
+```
+src/transports/http/
+  server.ts       — HTTP/SSE transport orchestrator (route registration, server lifecycle)
+  streamable.ts   — Streamable HTTP transport handler (POST/GET/DELETE /mcp)
+  stateless.ts    — Stateless HTTP transport handler (serverless mode)
+  legacy-sse.ts   — Legacy SSE transport handler (GET /sse, POST /messages)
+  handlers.ts     — Route handlers (health, 404, shared utilities)
+  security.ts     — Security headers, rate limiting, CORS, DNS rebinding, body parsing
+  types.ts        — Config interfaces, constants, JSON-RPC codes, timeout constants
+  index.ts        — Barrel re-export
+```
+
+**7 Security Headers** (every response):
+
+| Header                      | Value                                        | Purpose                      |
+| --------------------------- | -------------------------------------------- | ---------------------------- |
+| `X-Content-Type-Options`    | `nosniff`                                    | Prevent MIME sniffing        |
+| `X-Frame-Options`           | `DENY`                                       | Prevent clickjacking         |
+| `Content-Security-Policy`   | `default-src 'none'; frame-ancestors 'none'` | Strict CSP                   |
+| `Cache-Control`             | `no-store, no-cache, must-revalidate`        | Prevent data caching         |
+| `Referrer-Policy`           | `no-referrer`                                | Prevent referrer leakage     |
+| `Permissions-Policy`        | `camera=(), microphone=(), geolocation=()`   | Restrict browser APIs        |
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains`        | HSTS (**opt-in** via config) |
+
+> [!IMPORTANT]
+> HSTS must be **opt-in** (e.g., `--enable-hsts`), not auto-detected from `X-Forwarded-Proto`.
+
+**Built-in Rate Limiting** (zero dependencies): Sliding window `Map<string, {count, resetTime}>`, 100 req/min per IP (configurable). `429` + `Retry-After`. Health endpoint exempt. `setInterval().unref()` cleanup.
+
+**Server Timeouts:** Request 120s, keep-alive 65s, headers 66s.
+
+**CORS:** Default `[]` (deny-all), multi-origin via `--cors-origin`, wildcard subdomain support, `Access-Control-Max-Age: 86400`, `Vary: Origin`. Startup warning on wildcard `*`. Explicit configuration required for cross-origin access.
+
+**Additional Hardening:**
+
+- **Body size limit:** 1 MB default, `413` on excess
+- **Trust proxy:** Opt-in for `X-Forwarded-For` extraction
+- **Cross-protocol guard:** SSE IDs rejected on `/mcp` and vice versa
+- **404 handler:** `{ error: "Not found" }` — never expose stack traces
+- **Health endpoint:** `GET /health` always responds regardless of auth/rate limit
+- **DNS rebinding:** SDK ≥1.24.0 provides `localhostHostValidation()` middleware. Implementations may use the SDK utility directly or a custom `validateHostHeader()` function in `security.ts` — both are valid. Apply to all custom Express configs
+- **Constant-time token comparison:** Use `crypto.timingSafeEqual` for simple bearer token validation — never raw `===`. Both values must be `Buffer.from()`-wrapped with length pre-check (short-circuit on different lengths is acceptable since length is not the secret)
+- **JWT claims sanitization:** Filter prototype-polluting keys (`__proto__`, `constructor`, `prototype`) from JWT payload before spreading into `TokenClaims`. Prevents prototype pollution via crafted tokens
+- **Bearer auth scope limitation:** Simple bearer auth (`--auth-token`) authenticates but does NOT enforce per-tool scopes. Emit a startup warning when bearer auth is configured: `"Simple token auth does not enforce per-tool scopes. Use OAuth 2.1 for granular access control."`
+- **Fail-closed scope default:** `getRequiredScope()` returns `'admin'` for unmapped tools (`toolScopeMap.get(toolName) ?? 'admin'`), not `'read'`. Unknown tools require maximum privilege
+- **Path traversal validation:** `validateSameDirPath()` or `assertNoPathTraversal()` in `utils/validate-path.ts` for tools that write files (backup, dump, restore, attach). Resolves canonical path and rejects `..` traversal
+
+> [!CAUTION]
+> **CVE-2026-25536 — Cross-client data leakage (SDK 1.10.0–1.25.3):** Reusing a single `McpServer` instance across multiple transports can route responses to wrong clients. **Fix:** upgrade to SDK ≥1.26.0, or create separate instances per connection.
+
+---
+
+## Tool Poisoning Defense (MCP-Specific)
+
+Tool poisoning is a form of indirect prompt injection where malicious instructions are hidden in tool descriptions, annotations, or schema metadata. These instructions are invisible to human users but interpreted by AI models. OWASP Top 10 for LLM Applications 2025 ranks Prompt Injection #1 and Supply Chain #3 — tool description injection is the MCP-specific variant of both threats combined.
+
+### Attack Vectors
+
+| Vector                        | Description                                                                                  |
+| ----------------------------- | -------------------------------------------------------------------------------------------- |
+| **Description injection**     | Malicious prompts embedded in tool `description` fields — agent follows them as instructions |
+| **Schema metadata injection** | Hidden instructions in parameter `description` fields within `inputSchema` or `outputSchema` |
+| **Rug pull**                  | Tool definitions are legitimate initially, then silently modified after installation         |
+| **Cross-tool poisoning**      | One poisoned tool's output influences how the agent uses other tools                         |
+
+### Mitigation
+
+- **Tool pinning:** Pin MCP server versions (npm lockfile, Docker image digest). Never float on `latest` in production
+- **Schema integrity:** Consider digitally signing tool schemas. Verify signatures before accepting tool definitions from third-party servers
+- **Description review:** Treat tool descriptions as code — review changes in PRs. Automated scanners can flag linguistic patterns common in prompt injection
+- **Minimal privilege:** Each tool must have accurate `annotations`. Don't mark tools as `readOnlyHint: true` when they perform writes
+- **HITL for sensitive ops:** Tools that access secrets, modify auth, or perform destructive operations should prompt for user confirmation
+- **Audit logging:** Log all tool invocations with parameters for forensic analysis
+
+---
+
+## Code Mode Security Hardening
+
+Additional security requirements for servers implementing Code Mode (`{prefix}_execute_code`):
+
+**Frozen Built-In Prototypes:** Inside the `vm` context, freeze all built-in prototypes to prevent constructor chain escapes (e.g., `'con'+'structor'` string concatenation bypasses static blocked pattern scanning):
+
+```typescript
+// In sandbox.ts / worker-script.ts — before executing user code:
+const FROZEN_BUILTINS = [
+  Object,
+  Function,
+  Error,
+  Array,
+  Promise,
+  String,
+  Number,
+  Boolean,
+  RegExp,
+  Map,
+  Set,
+  WeakMap,
+  WeakSet,
+  ArrayBuffer,
+  SharedArrayBuffer,
+  DataView,
+  Int8Array,
+  Uint8Array,
+  Float64Array /* ... all typed arrays */,
+]
+for (const builtin of FROZEN_BUILTINS) {
+  Object.freeze(builtin.prototype)
+}
+```
+
+**Additional Blocked Patterns** (in `security.ts`):
+
+| Pattern     | Why Blocked                                                                                              |
+| ----------- | -------------------------------------------------------------------------------------------------------- |
+| `Reflect.`  | Reflection API enables prototype traversal                                                               |
+| `Symbol.`   | Symbol access can bypass property enumeration guards                                                     |
+| `new Proxy` | Proxy traps can intercept and redirect any operation                                                     |
+| `(SELECT`   | WHERE clause subquery injection (blind data exfiltration via `CASE WHEN (SELECT ...) THEN ... ELSE ...`) |
+
+**Filesystem Boundary Enforcement:** For servers with file I/O tools (backup, restore, import, export), implement `ALLOWED_IO_ROOTS` — a fail-closed allowlist of directories. Validate every file path argument against these roots before execution:
+
+```typescript
+const ALLOWED_IO_ROOTS = [config.dataDir, config.backupDir].filter(Boolean)
+
+function assertWithinBoundary(filePath: string): void {
+  const resolved = path.resolve(filePath)
+  if (!ALLOWED_IO_ROOTS.some((root) => resolved.startsWith(root))) {
+    throw new SecurityError(`Path '${filePath}' is outside allowed directories`)
+  }
+}
+```
+
+---
+
+## Key Security Resources
+
+- **OWASP Top 10 for LLM Applications 2025:** https://owasp.org/www-project-top-10-for-large-language-model-applications/
+- **MCP Security Best Practices:** https://modelcontextprotocol.io/specification/draft/best-practices.md
+- **RFC 9700 — OAuth 2.0 Security BCP (Jan 2025):** https://datatracker.ietf.org/doc/rfc9700/