@a11y-context/mcp-server 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.1
+
+Quality and robustness polish. No breaking changes to the published stdio tool contract; the three tools (`list_patterns`, `get_pattern`, `get_foundations`) and their success responses are byte-identical to 0.1.0.
+
+### Tools
+
+- **Structured, path-safe errors.** Tools now return `{ error_code, message }` with `isError: true` instead of throwing raw `Error`s. Stable codes: `PATTERN_NOT_FOUND`, `STACK_INVALID`, `CORPUS_UNAVAILABLE`, `INTERNAL_ERROR`. Absolute host filesystem paths are stripped from every client-reachable message.
+- **`get_foundations` `scope` filter.** The `scope` argument is now declared on the tool and wired through, so `get_foundations({ scope: ["component"] })` returns only rules matching those scope buckets (it was previously accepted internally but never exposed).
+
+### Server
+
+- **Index built once per process.** The per-stack index is now a lazy, process-lifetime singleton (shared across the stdio server and per-request HTTP servers) instead of being rebuilt on a 1-hour TTL. `cache_ttl_seconds` remains a client-facing cache hint only.
+- **HTTP transport hardening.** Runs stateless (no in-memory session map to leak), adds an in-memory per-IP rate limiter, and replaces the hand-rolled origin guard with the SDK's DNS-rebinding protection (`ALLOWED_HOSTS` / `ALLOWED_ORIGINS`) for Host/Origin validation.
+
+### Tooling
+
+- **`npm run sync-corpus`.** Refreshes the bundled `corpus/<stack>/` read-slice from a corpus-repo checkout, copying only published components (driven by `patterns.json` membership; `draft`/`deprecated` excluded).
+- **Regression suite + CI.** Regenerated snapshot fixtures against the 0.5.2 corpus; the runner now validates the compiled `dist/` output. Added a GitHub Actions workflow running build + regression + a stdio handshake smoke as a pre-publish gate.
+- Removed unused imports (`node:path` in `http.ts`, `sha256` in `repo/index.ts`).

package/README.md

@@ -44,7 +44,16 @@ The server ships a bundled snapshot of the corpus at `corpus/<stack>/`, refreshe
 ## Transports
 
 - **stdio** (default, via `npx`) — runs locally in your MCP client.
-- **HTTP** — `npm run start` serves the same tools over HTTP for clients that connect by URL.
+- **HTTP** — `npm run start` serves the same tools over HTTP for clients that connect by URL. The HTTP endpoint is stateless (no session state to leak) and rate-limited. For any publicly reachable deployment, set `ALLOWED_HOSTS` and/or `ALLOWED_ORIGINS` (comma-separated) to enable Host/Origin validation (DNS-rebinding protection); it stays off with a warning until configured.
+
+  | Env var | Default | Purpose |
+  |---|---|---|
+  | `PORT` | `3000` | HTTP listen port. |
+  | `ALLOWED_HOSTS` | *(unset)* | Comma-separated allowlist of `Host` header values. |
+  | `ALLOWED_ORIGINS` | *(unset)* | Comma-separated allowlist of `Origin` header values. |
+  | `TRUST_PROXY` | `false` | Express `trust proxy`. Set to `1` (hop count) behind a single reverse proxy (e.g. Railway) so per-IP rate limiting uses the real client IP. Leave off when directly exposed; never `true`. |
+  | `RATE_LIMIT_MAX` | `120` | Max requests per IP per window. |
+  | `RATE_LIMIT_WINDOW_MS` | `60000` | Rate-limit window in ms. |
 
 ## Development
 
@@ -57,6 +66,18 @@ npm run inspector    # MCP Inspector
 
 Override the corpus location with `PATTERN_REPO_PATH` (absolute, or relative to the package root) to develop against a live corpus checkout.
 
+### Refreshing the bundled corpus
+
+The package ships a snapshot of the corpus under `corpus/<stack>/`. Refresh it from a checkout of the corpus repo with:
+
+```bash
+npm run sync-corpus -- --source /path/to/accessibility-pattern-api
+# options: --stack web/react (default), --dry-run
+# or set A11Y_CORPUS_SOURCE instead of --source
+```
+
+It copies only the published read-slice — `patterns.json`, `global/global_rules.md`, and the components listed in `patterns.json` — into `corpus/<stack>/`. Membership is driven by `patterns.json`, so `status: draft` and `status: deprecated` components are excluded (a draft/deprecated member aborts the sync). The copied `patterns.json` records the source `catalog_revision`. Commit the resulting `corpus/` changes as part of the release.
+
 ## License
 
 [Apache-2.0](./LICENSE). The bundled corpus content is also Apache-2.0.

package/dist/config.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 // This file compiles to dist/config.js, so its dir is dist/ and the package
 // root is one level up; in dev (ts-node on src/config.ts) it resolves the same.
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
-const PACKAGE_ROOT = path.resolve(MODULE_DIR, "..");
+export const PACKAGE_ROOT = path.resolve(MODULE_DIR, "..");
 // Canonical server identity, read once from package.json so both transports
 // (stdio and HTTP) advertise the same name and version in the MCP handshake.
 const pkg = JSON.parse(readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
@@ -23,6 +23,8 @@ export function getConfig() {
     const patternRepoPath = path.isAbsolute(repoPathFromEnv)
         ? repoPathFromEnv
         : path.resolve(PACKAGE_ROOT, repoPathFromEnv);
+    // Advertised to clients as `cache_ttl_seconds`; does not drive any server-side
+    // rebuild (the index is a process-lifetime singleton).
     const cacheTtlSeconds = process.env.CACHE_TTL_SECONDS
         ? Number(process.env.CACHE_TTL_SECONDS)
         : 60 * 60; // 1 hour default

package/dist/http.js

@@ -1,14 +1,15 @@
 // src/http.ts
 import "dotenv/config";
 import express from "express";
-import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createMcpServer as createSharedMcpServer } from "./mcp/createServer.js";
 import { getConfig, SERVER_NAME, SERVER_VERSION } from "./config.js";
 function createHttpMcpServer() {
     // Use the same corpus resolution and identity as the stdio transport, so both
     // read the bundled package corpus and advertise the same server name/version.
+    // The index itself is a process-level singleton (see repo/cache.ts), so making
+    // a fresh server per request only re-registers tools — it does not re-read the
+    // corpus.
     const config = getConfig();
     return createSharedMcpServer({
         name: SERVER_NAME,
@@ -17,81 +18,145 @@ function createHttpMcpServer() {
         cacheTtlSeconds: config.cacheTtlSeconds,
     });
 }
-function originGuard() {
-    // MCP spec warns about Origin validation for HTTP transports. In practice,
-    // Cursor/Claude Code are not browsers and often send no Origin header.
-    // So: only enforce when Origin is present.
-    const allowed = (process.env.ALLOWED_ORIGINS ?? "")
+function parseList(value) {
+    return (value ?? "")
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean);
+}
+/**
+ * Express `trust proxy` setting. Default OFF (false) so `req.ip` is the
+ * unspoofable socket address. Behind a single reverse proxy (e.g. Railway) set
+ * TRUST_PROXY=1 to derive the real client IP from the proxy-appended
+ * X-Forwarded-For; a hop count / subnet list is also accepted. Never `true`:
+ * that trusts the entire client-supplied XFF chain, letting any client forge
+ * `req.ip` and bypass the rate limiter.
+ */
+function parseTrustProxy(value) {
+    const v = (value ?? "").trim();
+    if (v === "" || v === "false")
+        return false;
+    if (v === "true")
+        return true; // discouraged; documented footgun
+    const n = Number(v);
+    if (Number.isInteger(n) && String(n) === v)
+        return n;
+    return v; // e.g. "loopback" or a comma-separated subnet list
+}
+/**
+ * Minimal in-memory fixed-window rate limiter, keyed by client IP. The open
+ * 0.0.0.0 endpoint would otherwise be unbounded. A periodic sweep (unref'd, so
+ * it never keeps the process alive) evicts expired windows so the map can't grow
+ * without bound.
+ */
+function rateLimiter(opts) {
+    const hits = new Map();
+    const maxKeys = opts.maxKeys ?? 100_000;
+    function sweepExpired(now) {
+        for (const [key, entry] of hits) {
+            if (now >= entry.resetAt)
+                hits.delete(key);
+        }
+    }
+    const sweep = setInterval(() => sweepExpired(Date.now()), opts.windowMs);
+    sweep.unref();
     return (req, res, next) => {
-        const origin = req.headers.origin;
-        if (!origin)
-            return next();
-        if (allowed.length === 0)
-            return res.status(403).send("Origin not allowed");
-        if (!allowed.includes(origin))
-            return res.status(403).send("Origin not allowed");
+        const now = Date.now();
+        const key = req.ip || req.socket.remoteAddress || "unknown";
+        let entry = hits.get(key);
+        if (!entry || now >= entry.resetAt) {
+            // Hard cap on distinct keys as defense-in-depth against a map-growth DoS
+            // (also mitigated by trust-proxy defaulting off). Reclaim expired entries
+            // before admitting a new key.
+            if (!hits.has(key) && hits.size >= maxKeys)
+                sweepExpired(now);
+            entry = { count: 0, resetAt: now + opts.windowMs };
+            hits.set(key, entry);
+        }
+        entry.count += 1;
+        if (entry.count > opts.max) {
+            res.setHeader("Retry-After", String(Math.ceil((entry.resetAt - now) / 1000)));
+            res.status(429).json({
+                jsonrpc: "2.0",
+                error: { code: -32029, message: "Too Many Requests" },
+                id: null,
+            });
+            return;
+        }
         next();
     };
 }
 async function main() {
     const app = express();
+    app.set("trust proxy", parseTrustProxy(process.env.TRUST_PROXY));
     app.use(express.json({ limit: "2mb" }));
-    app.use(originGuard());
-    // Health endpoint for Railway and humans
+    const windowMs = Number(process.env.RATE_LIMIT_WINDOW_MS) || 60_000;
+    const maxPerWindow = Number(process.env.RATE_LIMIT_MAX) || 120;
+    app.use(rateLimiter({ windowMs, max: maxPerWindow }));
+    // Health endpoint for Railway and humans.
     app.get("/health", (_req, res) => {
         res.status(200).json({
             ok: true,
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
             contract_version: process.env.CONTRACT_VERSION ?? "v1",
-            patterns_dir: process.env.PATTERNS_DIR ?? "patterns",
         });
     });
-    // Map transports by session ID (official SDK approach).
-    const transports = {};
+    // Host + Origin validation via the SDK's DNS-rebinding protection. Configure
+    // ALLOWED_HOSTS / ALLOWED_ORIGINS (comma-separated) for the deployed endpoint;
+    // Host validation is what SF17 asks for and it also blocks DNS-rebinding.
+    // NOTE: these transport options are marked @deprecated in @modelcontextprotocol/sdk
+    // 1.26 in favor of external middleware; a future round may migrate. They remain
+    // fully functional today.
+    const allowedHosts = parseList(process.env.ALLOWED_HOSTS);
+    const allowedOrigins = parseList(process.env.ALLOWED_ORIGINS);
+    const enableDnsRebindingProtection = allowedHosts.length > 0 || allowedOrigins.length > 0;
+    if (!enableDnsRebindingProtection) {
+        console.warn("[http] ALLOWED_HOSTS/ALLOWED_ORIGINS unset — Host/Origin validation is OFF. " +
+            "Set them for any publicly reachable deployment.");
+    }
+    // Stateless transport: a fresh server + transport per request, so there is no
+    // in-memory session map to leak on abrupt client disconnects and no sticky
+    // routing requirement. The corpus index is shared across requests via the
+    // process-level cache, so per-request cost is just tool registration.
     app.post("/mcp", async (req, res) => {
-        const sessionId = req.headers["mcp-session-id"];
-        let transport;
-        if (sessionId && transports[sessionId]) {
-            transport = transports[sessionId];
-        }
-        else if (!sessionId && isInitializeRequest(req.body)) {
-            transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: () => randomUUID(),
-                onsessioninitialized: (id) => {
-                    transports[id] = transport;
-                },
-            });
-            transport.onclose = () => {
-                if (transport?.sessionId)
-                    delete transports[transport.sessionId];
-            };
-            const server = createHttpMcpServer();
+        const server = createHttpMcpServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableDnsRebindingProtection,
+            allowedHosts,
+            allowedOrigins,
+        });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        try {
             await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
         }
-        else {
-            res.status(400).json({
-                jsonrpc: "2.0",
-                error: { code: -32000, message: "Bad Request: No valid session ID provided" },
-                id: null,
-            });
-            return;
+        catch (err) {
+            console.error("[http] request handling failed:", err);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
         }
-        await transport.handleRequest(req, res, req.body);
     });
-    const handleSessionRequest = async (req, res) => {
-        const sessionId = req.headers["mcp-session-id"];
-        if (!sessionId || !transports[sessionId]) {
-            res.status(400).send("Invalid or missing session ID");
-            return;
-        }
-        await transports[sessionId].handleRequest(req, res);
+    // Stateless mode has no sessions, so the SSE GET stream and session DELETE are
+    // not supported.
+    const methodNotAllowed = (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Method not allowed (stateless server)" },
+            id: null,
+        });
     };
-    // GET for server-to-client notifications via SSE (part of Streamable HTTP behavior)
-    app.get("/mcp", handleSessionRequest);
-    // DELETE to end a session
-    app.delete("/mcp", handleSessionRequest);
+    app.get("/mcp", methodNotAllowed);
+    app.delete("/mcp", methodNotAllowed);
     const port = Number(process.env.PORT) || 3000;
     app.listen(port, "0.0.0.0", () => {
         console.log(`MCP HTTP server listening on :${port} at /mcp`);

package/dist/mcp/createServer.js

@@ -1,16 +1,23 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { createIndexCache } from "../repo/cache.js";
+import { PACKAGE_ROOT } from "../config.js";
+import { getIndexCache } from "../repo/cache.js";
 import { getGlobalRules } from "../tools/getGlobalRules.js";
 import { getPattern } from "../tools/getPattern.js";
 import { listPatterns } from "../tools/listPatterns.js";
 import { withTelemetry } from "../telemetryWrap.js";
 import { jsonResult } from "./response.js";
+import { toErrorResult } from "./errors.js";
 function registerTools(server, opts) {
-    const cache = createIndexCache({
+    const cache = getIndexCache({
         patternRepoPath: opts.patternsRoot,
         cacheTtlSeconds: opts.cacheTtlSeconds,
     });
+    // Absolute roots whose prefixes must never leak in a client-facing error.
+    // Any throw inside a handler is converted to a structured, client-safe error
+    // result ({ error_code, message }, isError: true) via toErrorResult(err, scrubRoots)
+    // instead of an SDK error carrying a raw message with absolute host paths.
+    const scrubRoots = [opts.patternsRoot, PACKAGE_ROOT];
     server.registerTool("list_patterns", {
         description: "List the accessible UI component patterns available for a stack. Call this FIRST whenever you are about to build or modify any UI, to choose which patterns apply. Each entry has an `id`, `summary`, `tags`, `aliases`, and a `selection_excerpt` (its `use_when` / `do_not_use_when` bullets) — use the selection_excerpt to decide which patterns match the components in your task, then call get_pattern for each. Optionally narrow with `tags` or a free-text `query`.",
         inputSchema: {
@@ -22,31 +29,36 @@ function registerTools(server, opts) {
             query: z.string().optional(),
         },
     }, async (args) => {
-        const stack = args.stack;
-        const toolArgs = {
-            stack,
-            tags: args.tags,
-            query: args.query,
-        };
-        const payload = await withTelemetry({
-            tool: "list_patterns",
-            stack,
-            args: toolArgs,
-            handler: async () => {
-                const index = await cache.getIndex(stack);
-                return listPatterns(index, {
-                    stack,
-                    tags: args.tags,
-                    query: args.query,
-                });
-            },
-            summarizeResult: (result) => ({
-                count: result.count,
-                cache_ttl_seconds: result.cache_ttl_seconds,
-                catalog_revision: result.catalog_revision,
-            }),
-        });
-        return jsonResult(payload);
+        try {
+            const stack = args.stack;
+            const toolArgs = {
+                stack,
+                tags: args.tags,
+                query: args.query,
+            };
+            const payload = await withTelemetry({
+                tool: "list_patterns",
+                stack,
+                args: toolArgs,
+                handler: async () => {
+                    const index = await cache.getIndex(stack);
+                    return listPatterns(index, {
+                        stack,
+                        tags: args.tags,
+                        query: args.query,
+                    });
+                },
+                summarizeResult: (result) => ({
+                    count: result.count,
+                    cache_ttl_seconds: result.cache_ttl_seconds,
+                    catalog_revision: result.catalog_revision,
+                }),
+            });
+            return jsonResult(payload);
+        }
+        catch (err) {
+            return toErrorResult(err, scrubRoots);
+        }
     });
     server.registerTool("get_pattern", {
         description: "Get the full accessibility specification for one pattern by `id` (ids come from list_patterns). Returns the pattern's sections: `must_haves` (non-negotiable WCAG 2.2 AA requirements — implement all of them), `donts` (anti-patterns — never produce), `golden_pattern` (a reference implementation to model), `customizable` (allowed variations), and `acceptance_checks` (observable pass/fail behaviors). Call this for each pattern you selected before writing UI code.",
@@ -58,58 +70,74 @@ function registerTools(server, opts) {
             id: z.string(),
         },
     }, async (args) => {
-        const stack = args.stack;
-        const toolArgs = {
-            stack,
-            id: String(args.id),
-        };
-        const payload = await withTelemetry({
-            tool: "get_pattern",
-            stack,
-            args: toolArgs,
-            handler: async () => {
-                const index = await cache.getIndex(stack);
-                return getPattern(index, opts.patternsRoot, {
-                    stack,
-                    id: String(args.id),
-                });
-            },
-            summarizeResult: (result) => ({
-                pattern_id: result.pattern.id,
-                cache_ttl_seconds: result.cache_ttl_seconds,
-                catalog_revision: result.catalog_revision,
-            }),
-        });
-        return jsonResult(payload);
+        try {
+            const stack = args.stack;
+            const toolArgs = {
+                stack,
+                id: String(args.id),
+            };
+            const payload = await withTelemetry({
+                tool: "get_pattern",
+                stack,
+                args: toolArgs,
+                handler: async () => {
+                    const index = await cache.getIndex(stack);
+                    return getPattern(index, opts.patternsRoot, {
+                        stack,
+                        id: String(args.id),
+                    });
+                },
+                summarizeResult: (result) => ({
+                    pattern_id: result.pattern.id,
+                    cache_ttl_seconds: result.cache_ttl_seconds,
+                    catalog_revision: result.catalog_revision,
+                }),
+            });
+            return jsonResult(payload);
+        }
+        catch (err) {
+            return toErrorResult(err, scrubRoots);
+        }
     });
     server.registerTool("get_foundations", {
-        description: "Get the cross-cutting Foundations rules for a stack — accessibility requirements not tied to a single component: focus states, landmarks, headings, contrast, page structure, use of color. Retrieve these on every UI task, not just page-level work: each rule carries a `scope` (utility, style, component, layout, page) that determines whether it applies to the current change.",
+        description: "Get the cross-cutting Foundations rules for a stack — accessibility requirements not tied to a single component: focus states, landmarks, headings, contrast, page structure, use of color. Retrieve these on every UI task, not just page-level work: each rule carries a `scope` (utility, style, component, layout, page) that determines whether it applies to the current change. Optionally pass `scope` to return only rules matching one or more of those buckets.",
         inputSchema: {
             stack: z
                 .enum(["web/react", "android/compose"])
                 .default("web/react")
                 .describe("Target platform and framework. Currently only 'web/react' is populated; defaults to 'web/react'."),
+            scope: z
+                .array(z.enum(["utility", "style", "component", "layout", "page"]))
+                .optional()
+                .describe("Optional. Return only rules whose `scope` includes at least one of these buckets. Omit to get all rules."),
         },
     }, async (args) => {
-        const stack = args.stack;
-        const toolArgs = {
-            stack,
-        };
-        const payload = await withTelemetry({
-            tool: "get_foundations",
-            stack,
-            args: toolArgs,
-            handler: async () => {
-                const index = await cache.getIndex(stack);
-                return getGlobalRules(index, opts.patternsRoot, { stack });
-            },
-            summarizeResult: (result) => ({
-                rules_count: Array.isArray(result.rules.items) ? result.rules.items.length : 0,
-                cache_ttl_seconds: result.cache_ttl_seconds,
-                catalog_revision: result.catalog_revision,
-            }),
-        });
-        return jsonResult(payload);
+        try {
+            const stack = args.stack;
+            const scope = args.scope;
+            const toolArgs = {
+                stack,
+                scope,
+            };
+            const payload = await withTelemetry({
+                tool: "get_foundations",
+                stack,
+                args: toolArgs,
+                handler: async () => {
+                    const index = await cache.getIndex(stack);
+                    return getGlobalRules(index, opts.patternsRoot, { stack, scope });
+                },
+                summarizeResult: (result) => ({
+                    rules_count: Array.isArray(result.rules.items) ? result.rules.items.length : 0,
+                    cache_ttl_seconds: result.cache_ttl_seconds,
+                    catalog_revision: result.catalog_revision,
+                }),
+            });
+            return jsonResult(payload);
+        }
+        catch (err) {
+            return toErrorResult(err, scrubRoots);
+        }
     });
 }
 export function createMcpServer(opts) {

package/dist/mcp/errors.js

@@ -0,0 +1,87 @@
+// src/mcp/errors.ts
+//
+// Structured, client-safe tool errors.
+//
+// Tools throw `ToolFailure` with a stable `error_code` (never a raw path in the
+// message). At the MCP boundary, `toErrorResult` turns any throw into a
+// `jsonResult({ error_code, message }, { isError: true })` so clients get a
+// predictable shape and never see absolute host filesystem paths.
+import { jsonResult } from "./response.js";
+/**
+ * Stable, client-facing error codes. Clients can branch on these instead of
+ * string-matching messages. New codes are additive.
+ */
+export const ERROR_CODES = {
+    /** Requested pattern id is not in the catalog for the given stack. */
+    PATTERN_NOT_FOUND: "PATTERN_NOT_FOUND",
+    /** Requested stack is not usable (e.g. index built for a different stack). */
+    STACK_INVALID: "STACK_INVALID",
+    /** The corpus for the requested stack could not be loaded or parsed. */
+    CORPUS_UNAVAILABLE: "CORPUS_UNAVAILABLE",
+    /** Catch-all for unexpected failures (message is scrubbed of host paths). */
+    INTERNAL_ERROR: "INTERNAL_ERROR",
+};
+/**
+ * A tool failure whose message is already safe to return to a client.
+ * Throw this from tool/repo code for known, enumerated conditions.
+ */
+export class ToolFailure extends Error {
+    error_code;
+    details;
+    constructor(error_code, message, details) {
+        super(message);
+        this.name = "ToolFailure";
+        this.error_code = error_code;
+        this.details = details;
+    }
+}
+function escapeForRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Remove absolute host paths from a message so nothing client-reachable leaks
+ * the server's filesystem layout. Known corpus/package roots are turned into
+ * their relative tail; any remaining home-dir absolute prefix is collapsed.
+ *
+ * Throw sites already compose messages with relative paths — this is a
+ * defense-in-depth backstop for unexpected errors.
+ */
+export function scrubPaths(message, roots = []) {
+    // Work on a slash-normalized copy so a native (backslash) root reliably
+    // matches a message whose paths may be POSIX-normalized (fast-glob / toPosix
+    // store forward slashes even on Windows) or native. These error messages are
+    // path/id-centric, so normalizing stray backslashes is harmless.
+    let out = message.replace(/\\/g, "/");
+    for (const root of roots) {
+        if (!root)
+            continue;
+        const normalized = root.replace(/\\/g, "/").replace(/\/+$/, "");
+        if (!normalized)
+            continue;
+        // "<root>/a/b" -> "a/b", bare "<root>" -> ""
+        out = out.replace(new RegExp(escapeForRegex(normalized) + "/?", "g"), "");
+    }
+    // Backstop: collapse any lingering absolute home path not under a known root.
+    // Covers posix (/Users, /home) and Windows drive paths, which are forward-slash
+    // after the normalization above (e.g. "C:/Users/john/").
+    out = out
+        .replace(/[A-Za-z]:\/Users\/[^/\s"']+\//g, "~/")
+        .replace(/\/Users\/[^/\s"']+\//g, "~/")
+        .replace(/\/home\/[^/\s"']+\//g, "~/");
+    return out;
+}
+/**
+ * Convert any thrown value into a structured, client-safe error result.
+ * Known `ToolFailure`s keep their code; anything else becomes INTERNAL_ERROR.
+ */
+export function toErrorResult(err, roots = []) {
+    if (err instanceof ToolFailure) {
+        return jsonResult({
+            error_code: err.error_code,
+            message: scrubPaths(err.message, roots),
+            ...(err.details ? { details: err.details } : {}),
+        }, { isError: true });
+    }
+    const rawMessage = err instanceof Error ? err.message : String(err);
+    return jsonResult({ error_code: ERROR_CODES.INTERNAL_ERROR, message: scrubPaths(rawMessage, roots) }, { isError: true });
+}

package/dist/repo/cache.js

@@ -1,21 +1,25 @@
 import { buildPatternIndex } from "./index.js";
+/**
+ * Lazy singleton index cache, keyed by stack.
+ *
+ * The bundled corpus is static for the life of the process, so once a stack's
+ * index is built we keep it — no TTL, no periodic re-glob/re-parse. We memoize
+ * the in-flight Promise (not just the resolved value) so concurrent first-hits
+ * dedupe onto a single build instead of racing several.
+ */
 export function createIndexCache(params) {
     const { patternRepoPath, cacheTtlSeconds } = params;
     const store = new Map();
-    async function getIndex(stack) {
-        const now = Date.now();
-        const cached = store.get(stack);
-        // If we have it and it's fresh enough, reuse it.
-        if (cached) {
-            const ageSeconds = (now - cached.builtAtMs) / 1000;
-            if (ageSeconds < cacheTtlSeconds) {
-                return cached.index;
-            }
+    function getIndex(stack) {
+        let inflight = store.get(stack);
+        if (!inflight) {
+            inflight = buildPatternIndex(patternRepoPath, stack, cacheTtlSeconds);
+            // If the build rejects (e.g. an unpopulated stack), evict so a later call
+            // can retry rather than caching the rejection for the whole process life.
+            inflight.catch(() => store.delete(stack));
+            store.set(stack, inflight);
         }
-        // Otherwise rebuild
-        const index = await buildPatternIndex(patternRepoPath, stack, cacheTtlSeconds);
-        store.set(stack, { index, builtAtMs: now });
-        return index;
+        return inflight;
     }
     function clear(stack) {
         if (stack)
@@ -25,3 +29,17 @@ export function createIndexCache(params) {
     }
     return { getIndex, clear };
 }
+// Process-level memoization keyed by corpus path, so every server instance
+// (the single stdio server, or a per-request HTTP server) shares one cache.
+// The index is built at most once per process per stack — not once per server
+// or per HTTP session.
+const sharedCaches = new Map();
+export function getIndexCache(params) {
+    const key = params.patternRepoPath;
+    let cache = sharedCaches.get(key);
+    if (!cache) {
+        cache = createIndexCache(params);
+        sharedCaches.set(key, cache);
+    }
+    return cache;
+}

package/dist/repo/index.js

@@ -3,6 +3,7 @@ import matter from "gray-matter";
 import path from "node:path";
 import { getRepoPaths } from "./paths.js";
 import { readTextFile, fileExists, toPosixPath } from "../utils/fs.js";
+import { ToolFailure, ERROR_CODES } from "../mcp/errors.js";
 function normalizeBullet(s, maxLen) {
     if (typeof s !== "string")
         return null;
@@ -51,7 +52,7 @@ function buildCatalogSelectionMap(catalogText) {
         parsed = JSON.parse(catalogText);
     }
     catch {
-        throw new Error("patterns.json is not valid JSON.");
+        throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, "patterns.json is not valid JSON.");
     }
     const parsedObj = parsed;
     const arr = Array.isArray(parsed)
@@ -83,19 +84,19 @@ function buildCatalogSelectionMap(catalogText) {
 export async function buildPatternIndex(patternRepoPath, stack, cacheTtlSeconds) {
     const { baselinePath, catalogPath, componentsGlob } = getRepoPaths(patternRepoPath, stack);
     if (!(await fileExists(baselinePath))) {
-        throw new Error(`Missing baseline file: ${baselinePath}`);
+        throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Missing baseline file for stack '${stack}': ${makeRelativePath(patternRepoPath, baselinePath)}`);
     }
     if (!(await fileExists(catalogPath))) {
-        throw new Error(`Missing catalog file: ${catalogPath}`);
+        throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Missing catalog file for stack '${stack}': ${makeRelativePath(patternRepoPath, catalogPath)}`);
     }
-    // Deterministic ordering: sort file paths before reading/hashing/parsing
+    // Deterministic ordering: sort file paths before reading/parsing
     const componentPaths = (await fg(componentsGlob, { onlyFiles: true, unique: true }))
         .map(toPosixPath)
         .sort((a, b) => a.localeCompare(b));
     const baselineText = await readTextFile(baselinePath);
     const catalogText = await readTextFile(catalogPath);
     const selectionById = buildCatalogSelectionMap(catalogText);
-    // Read each component once; reuse both for hashing and parsing
+    // Read each component once, then parse from the cached text.
     const fileTextByPath = new Map();
     for (const p of componentPaths) {
         // NOTE: componentPaths are POSIX normalized; ensure readTextFile can handle them on Windows.
@@ -118,14 +119,15 @@ export async function buildPatternIndex(patternRepoPath, stack, cacheTtlSeconds)
     const idToPath = new Map();
     const all = [];
     for (const filePath of componentPaths) {
+        const relPath = makeRelativePath(patternRepoPath, filePath);
         const raw = fileTextByPath.get(filePath);
         if (raw == null)
-            throw new Error(`Internal error: missing cached text for ${filePath}`);
+            throw new Error(`Internal error: missing cached text for ${relPath}`);
         const parsed = matter(raw);
         const data = parsed.data;
         const id = String(data.id ?? "").trim();
         if (!id) {
-            throw new Error(`Pattern missing 'id' in frontmatter: ${filePath}`);
+            throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Pattern missing 'id' in frontmatter: ${relPath}`);
         }
         const declaredStack = String(data.stack ?? "").trim();
         const status = String(data.status ?? "").trim();
@@ -133,14 +135,14 @@ export async function buildPatternIndex(patternRepoPath, stack, cacheTtlSeconds)
         const tags = Array.isArray(data.tags) ? data.tags.map(String) : [];
         const aliases = Array.isArray(data.aliases) ? data.aliases.map(String) : [];
         if (declaredStack && declaredStack !== stack) {
-            throw new Error(`Pattern ${id} declares stack=${declaredStack} but is located under stack=${stack}`);
+            throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Pattern '${id}' declares stack='${declaredStack}' but is located under stack='${stack}' (${relPath}).`);
         }
         if (!summary) {
-            throw new Error(`Pattern missing 'summary' in frontmatter: ${filePath}`);
+            throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Pattern missing 'summary' in frontmatter: ${relPath}`);
         }
         const allowed = ["alpha", "beta", "stable", "deprecated"];
         if (!allowed.includes(status)) {
-            throw new Error(`Invalid status '${status}' in ${filePath}. Allowed: ${allowed.join(", ")}`);
+            throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Invalid status '${status}' in ${relPath}. Allowed: ${allowed.join(", ")}`);
         }
         const selection_excerpt = selectionById.get(id);
         const pattern = {
@@ -153,7 +155,7 @@ export async function buildPatternIndex(patternRepoPath, stack, cacheTtlSeconds)
             ...(selection_excerpt ? { selection_excerpt } : {}),
         };
         if (byId.has(id)) {
-            throw new Error(`Duplicate pattern id '${id}' found. Second copy: ${filePath}`);
+            throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Duplicate pattern id '${id}' found. Second copy: ${relPath}`);
         }
         byId.set(id, pattern);
         idToPath.set(id, filePath);

package/dist/tools/getGlobalRules.js

@@ -1,5 +1,6 @@
 import { readTextFile } from "../utils/fs.js";
 import { getRepoPaths } from "../repo/paths.js";
+import { ToolFailure, ERROR_CODES } from "../mcp/errors.js";
 import { parseGlobalRulesMarkdown } from "../repo/globalRules.js";
 function normalizeScope(scope) {
     if (!scope)
@@ -9,7 +10,7 @@ function normalizeScope(scope) {
 export async function getGlobalRules(index, patternRepoPath, args) {
     const { stack } = args;
     if (stack !== index.stack) {
-        throw new Error(`Stack mismatch. Index=${index.stack}, requested=${stack}`);
+        throw new ToolFailure(ERROR_CODES.STACK_INVALID, `Stack mismatch. Index='${index.stack}', requested='${stack}'.`);
     }
     const scopeFilter = normalizeScope(args.scope);
     const { baselinePath } = getRepoPaths(patternRepoPath, stack);

package/dist/tools/getPattern.js

@@ -3,15 +3,17 @@ import matter from "gray-matter";
 import { readTextFile } from "../utils/fs.js";
 import { extractSections } from "../repo/sections.js";
 import { makeRelativePath } from "../repo/index.js";
+import { ToolFailure, ERROR_CODES } from "../mcp/errors.js";
 export async function getPattern(index, patternRepoPath, args) {
     const { stack, id } = args;
     if (stack !== index.stack) {
-        throw new Error(`Stack mismatch. Index=${index.stack}, requested=${stack}`);
+        throw new ToolFailure(ERROR_CODES.STACK_INVALID, `Stack mismatch. Index='${index.stack}', requested='${stack}'.`);
     }
     const filePath = index.idToPath.get(id);
     if (!filePath) {
-        throw new Error(`PATTERN_NOT_FOUND: No pattern with id '${id}' for stack '${stack}'`);
+        throw new ToolFailure(ERROR_CODES.PATTERN_NOT_FOUND, `No pattern with id '${id}' for stack '${stack}'.`);
     }
+    const relPath = makeRelativePath(patternRepoPath, filePath);
     const raw = await readTextFile(filePath);
     const parsed = matter(raw);
     const data = parsed.data;
@@ -22,17 +24,17 @@ export async function getPattern(index, patternRepoPath, args) {
     const tags = Array.isArray(data.tags) ? data.tags.map(String) : [];
     const aliases = Array.isArray(data.aliases) ? data.aliases.map(String) : [];
     if (!patternId)
-        throw new Error(`Pattern missing 'id' in frontmatter: ${filePath}`);
+        throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Pattern missing 'id' in frontmatter: ${relPath}`);
     if (patternId !== id) {
-        throw new Error(`Pattern id mismatch. Requested '${id}', file declares '${patternId}' (${filePath})`);
+        throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Pattern id mismatch. Requested '${id}', file declares '${patternId}' (${relPath}).`);
     }
     // Optional but strongly recommended: validate declared stack matches folder stack
     const declaredStack = String(data.stack ?? "").trim();
     if (declaredStack && declaredStack !== stack) {
-        throw new Error(`Pattern '${id}' declares stack='${declaredStack}' but is served under stack='${stack}'. File: ${filePath}`);
+        throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Pattern '${id}' declares stack='${declaredStack}' but is served under stack='${stack}' (${relPath}).`);
     }
     if (!summary)
-        throw new Error(`Pattern missing 'summary' in frontmatter: ${filePath}`);
+        throw new ToolFailure(ERROR_CODES.CORPUS_UNAVAILABLE, `Pattern missing 'summary' in frontmatter: ${relPath}`);
     const sections = extractSections(parsed.content);
     const detail = {
         id,
@@ -43,7 +45,7 @@ export async function getPattern(index, patternRepoPath, args) {
         aliases,
         sections,
         source: {
-            relative_path: makeRelativePath(patternRepoPath, filePath),
+            relative_path: relPath,
         },
     };
     return {

package/dist/tools/listPatterns.js

@@ -1,7 +1,8 @@
+import { ToolFailure, ERROR_CODES } from "../mcp/errors.js";
 export function listPatterns(index, args) {
     const { stack, tags, query } = args;
     if (stack !== index.stack) {
-        throw new Error(`Stack mismatch. Index=${index.stack}, requested=${stack}`);
+        throw new ToolFailure(ERROR_CODES.STACK_INVALID, `Stack mismatch. Index='${index.stack}', requested='${stack}'.`);
     }
     let results = index.all;
     // Filter by tags (OR logic): match if pattern has ANY of the requested tags.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11y-context/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Model Context Protocol server that serves the A11y Context accessibility-pattern corpus (WCAG 2.2 AA patterns, Foundations rules) to AI coding agents.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
     "dist/",
     "corpus/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -23,9 +24,11 @@
     "dev:http": "tsx watch src/http.ts",
     "inspector": "npm run build && mcp-inspector node dist/index.js",
     "smoke:remote": "npm run build && node dist/smoke/smoke-remote-mcp.js",
-    "test:regression": "ts-node scripts/regression-runner.ts",
-    "test:regression:update": "ts-node scripts/regression-runner.ts --update",
-    "test:regression:ignore-ttl": "ts-node scripts/regression-runner.ts --ignore-cache-ttl",
+    "smoke:stdio": "npm run build && node scripts/smoke-stdio.mjs",
+    "test:regression": "npm run build && node scripts/regression-runner.mjs",
+    "test:regression:update": "npm run build && node scripts/regression-runner.mjs --update",
+    "test:regression:ignore-ttl": "npm run build && node scripts/regression-runner.mjs --ignore-cache-ttl",
+    "sync-corpus": "node scripts/sync-corpus.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [