@a11y-context/mcp-server 0.1.0

package/dist/config.js

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// Resolve the package root regardless of how the server is launched.
+// ESM-safe (no `__dirname`, which is undefined under `type: module`).
+// 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, "..");
+// 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"));
+export const SERVER_NAME = pkg.name ?? "a11y-context-mcp";
+export const SERVER_VERSION = pkg.version ?? "0.0.0";
+/**
+ * Reads configuration from environment variables.
+ */
+export function getConfig() {
+    // The bundled corpus ships inside the package at <root>/corpus. Override with
+    // PATTERN_REPO_PATH (absolute, or relative to the package root) to point at a
+    // working corpus checkout during development.
+    const repoPathFromEnv = process.env.PATTERN_REPO_PATH ?? "corpus";
+    const patternRepoPath = path.isAbsolute(repoPathFromEnv)
+        ? repoPathFromEnv
+        : path.resolve(PACKAGE_ROOT, repoPathFromEnv);
+    const cacheTtlSeconds = process.env.CACHE_TTL_SECONDS
+        ? Number(process.env.CACHE_TTL_SECONDS)
+        : 60 * 60; // 1 hour default
+    // Startup debug is opt-in (goes to stderr, never stdout — safe for MCP).
+    if (process.env.A11Y_MCP_DEBUG) {
+        console.error("[config] patternRepoPath:", patternRepoPath);
+        console.error("[config] cacheTtlSeconds:", cacheTtlSeconds);
+    }
+    return { patternRepoPath, cacheTtlSeconds };
+}

package/dist/contracts/v1/types.js

@@ -0,0 +1,6 @@
+/**
+ * QUESTIONS
+ *
+ 
+ */
+export {};

package/dist/http.js

@@ -0,0 +1,103 @@
+// 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.
+    const config = getConfig();
+    return createSharedMcpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        patternsRoot: config.patternRepoPath,
+        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 ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    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");
+        next();
+    };
+}
+async function main() {
+    const app = express();
+    app.use(express.json({ limit: "2mb" }));
+    app.use(originGuard());
+    // Health endpoint for Railway and humans
+    app.get("/health", (_req, res) => {
+        res.status(200).json({
+            ok: true,
+            contract_version: process.env.CONTRACT_VERSION ?? "v1",
+            patterns_dir: process.env.PATTERNS_DIR ?? "patterns",
+        });
+    });
+    // Map transports by session ID (official SDK approach).
+    const transports = {};
+    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();
+            await server.connect(transport);
+        }
+        else {
+            res.status(400).json({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Bad Request: No valid session ID provided" },
+                id: null,
+            });
+            return;
+        }
+        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);
+    };
+    // 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);
+    const port = Number(process.env.PORT) || 3000;
+    app.listen(port, "0.0.0.0", () => {
+        console.log(`MCP HTTP server listening on :${port} at /mcp`);
+    });
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { startMcpServer } from "./mcp/server.js";
+startMcpServer().catch((err) => {
+    console.error("Startup failed ❌");
+    console.error(err);
+    process.exit(1);
+});

package/dist/mcp/createServer.js

@@ -0,0 +1,122 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createIndexCache } 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";
+function registerTools(server, opts) {
+    const cache = createIndexCache({
+        patternRepoPath: opts.patternsRoot,
+        cacheTtlSeconds: opts.cacheTtlSeconds,
+    });
+    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: {
+            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'."),
+            tags: z.array(z.string()).optional(),
+            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);
+    });
+    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.",
+        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'."),
+            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);
+    });
+    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.",
+        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'."),
+        },
+    }, 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);
+    });
+}
+export function createMcpServer(opts) {
+    const server = new McpServer({ name: opts.name, version: opts.version }, { capabilities: { tools: {} } });
+    registerTools(server, {
+        patternsRoot: opts.patternsRoot,
+        cacheTtlSeconds: opts.cacheTtlSeconds,
+    });
+    return server;
+}

package/dist/mcp/response.js

@@ -0,0 +1,7 @@
+export function jsonResult(payload, options) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+        ...(options?.isError !== undefined ? { isError: options.isError } : {}),
+    };
+}

package/dist/mcp/server.js

@@ -0,0 +1,15 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { getConfig, SERVER_NAME, SERVER_VERSION } from "../config.js";
+import { createMcpServer } from "./createServer.js";
+export async function startMcpServer() {
+    const config = getConfig();
+    const server = createMcpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        patternsRoot: config.patternRepoPath,
+        cacheTtlSeconds: config.cacheTtlSeconds,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Keep process alive (stdio transport)
+}

package/dist/repo/cache.js

@@ -0,0 +1,27 @@
+import { buildPatternIndex } from "./index.js";
+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;
+            }
+        }
+        // Otherwise rebuild
+        const index = await buildPatternIndex(patternRepoPath, stack, cacheTtlSeconds);
+        store.set(stack, { index, builtAtMs: now });
+        return index;
+    }
+    function clear(stack) {
+        if (stack)
+            store.delete(stack);
+        else
+            store.clear();
+    }
+    return { getIndex, clear };
+}

package/dist/repo/globalRules.js

@@ -0,0 +1,304 @@
+import matter from "gray-matter";
+// Keep allowed values centralized and deterministic.
+const ALLOWED_SCOPES = ["utility", "style", "component", "layout", "page"];
+function normalizeScopeToken(raw) {
+    return raw.trim().toLowerCase();
+}
+function assertIsRuleScope(value, ctx) {
+    const v = normalizeScopeToken(value);
+    if (!ALLOWED_SCOPES.includes(v)) {
+        throw new Error(`${ctx}: invalid scope '${value}'. Allowed: ${ALLOWED_SCOPES.join(", ")}`);
+    }
+    return v;
+}
+function toRuleScopeArray(raw, ctx) {
+    const out = [];
+    for (const s of raw)
+        out.push(assertIsRuleScope(s, ctx));
+    // de-dupe + deterministic ordering
+    return Array.from(new Set(out)).sort((a, b) => a.localeCompare(b));
+}
+function parseStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const arr = value.map(String).map((s) => s.trim()).filter(Boolean);
+    return arr.length ? arr : undefined;
+}
+function parseApplyPolicy(value, ctx) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const v = value;
+    const instruction = typeof v.instruction === "string" ? v.instruction : undefined;
+    const rawScopes = parseStringArray(v.scopes_in_order);
+    const scopes_in_order = rawScopes
+        ? toRuleScopeArray(rawScopes, `${ctx}: apply_policy.scopes_in_order`)
+        : undefined;
+    const policy = {};
+    if (instruction)
+        policy.instruction = instruction;
+    if (scopes_in_order)
+        policy.scopes_in_order = scopes_in_order;
+    return Object.keys(policy).length ? policy : undefined;
+}
+export function parseGlobalRulesMarkdown(fileText, expectedStack) {
+    const parsed = matter(fileText);
+    const data = parsed.data;
+    const body = parsed.content.replace(/\r\n/g, "\n").trim();
+    // ---- Frontmatter -> meta (light validation) ----
+    const meta = {
+        id: String(data.id ?? "").trim(),
+        stack: String(data.stack ?? "").trim() || expectedStack,
+        rule_set: typeof data.rule_set === "string" ? data.rule_set : undefined,
+        status: typeof data.status === "string" ? data.status : undefined,
+        summary: typeof data.summary === "string" ? data.summary : undefined,
+        cache_ttl_seconds: typeof data.cache_ttl_seconds === "number" ? data.cache_ttl_seconds : undefined,
+        apply_policy: parseApplyPolicy(data.apply_policy, "global rules frontmatter"),
+    };
+    if (!meta.id) {
+        throw new Error("Global rules file missing frontmatter 'id'.");
+    }
+    if (meta.stack !== expectedStack) {
+        throw new Error(`Global rules frontmatter stack='${meta.stack}' does not match requested stack='${expectedStack}'.`);
+    }
+    // Optional: validate status if present (keeps v1 strict-ish)
+    if (meta.status) {
+        const allowed = ["alpha", "beta", "stable", "deprecated"];
+        if (!allowed.includes(meta.status)) {
+            throw new Error(`Global rules frontmatter has invalid status='${meta.status}'. Allowed: ${allowed.join(", ")}`);
+        }
+    }
+    // ---- Parse rules ----
+    const ruleBlocks = splitByH2Rule(body);
+    const rules = ruleBlocks.map((block) => parseOneRule(block));
+    // Deterministic ordering: by id
+    rules.sort((a, b) => a.id.localeCompare(b.id));
+    // Optional: enforce no duplicate rule ids
+    const seen = new Set();
+    for (const r of rules) {
+        if (seen.has(r.id)) {
+            throw new Error(`Duplicate global rule id '${r.id}' found.`);
+        }
+        seen.add(r.id);
+    }
+    return { meta, rules };
+}
+/**
+ * Splits the markdown content into rule blocks based on "## Rule: ..."
+ * Slightly forgiving: allows extra spaces and different casing.
+ */
+function splitByH2Rule(markdown) {
+    const lines = markdown.split("\n");
+    const blocks = [];
+    let currentTitle = null;
+    let currentBody = [];
+    function push() {
+        if (!currentTitle)
+            return;
+        blocks.push({ title: currentTitle, body: currentBody.join("\n").trim() });
+    }
+    for (const line of lines) {
+        const match = line.match(/^##\s+Rule:\s*(.*)\s*$/i);
+        if (match) {
+            push();
+            currentTitle = match[1].trim();
+            currentBody = [];
+        }
+        else {
+            if (currentTitle)
+                currentBody.push(line);
+        }
+    }
+    push();
+    return blocks;
+}
+/**
+ * Parse a single rule block into a deterministic GlobalRule object.
+ */
+function parseOneRule(block) {
+    const { title, body } = block;
+    // 1) Extract the first fenced yaml block: ```yaml ... ```
+    const yamlFence = firstFencedBlock(body, "yaml");
+    if (!yamlFence) {
+        throw new Error(`Rule '${title}' is missing a \`\`\`yaml fenced block with 'id' and 'scope'.`);
+    }
+    const { id, scope } = parseRuleYaml(yamlFence.code, `Rule '${title}'`);
+    if (!id)
+        throw new Error(`Rule '${title}' yaml block is missing 'id'.`);
+    if (!scope.length)
+        throw new Error(`Rule '${title}' yaml block is missing 'scope'.`);
+    // 2) Extract sections by "### Heading"
+    const sections = splitByH3(body);
+    const must_haves = toBullets(sections["must haves"]);
+    const donts = toBullets(sections["don'ts"] ?? sections["donts"]);
+    const acceptance_checks = toBullets(sections["acceptance checks"]);
+    // 3) Snippets: collect *all* fenced blocks under "### Snippets"
+    const snippetsMarkdown = sections["snippets"] ?? "";
+    const snippets = allFencedBlocks(snippetsMarkdown)
+        .map((b) => ({ language: b.language, code: b.code }))
+        // Deterministic ordering: language then code
+        .sort((a, b) => (a.language + "\n" + a.code).localeCompare(b.language + "\n" + b.code));
+    return {
+        id,
+        title,
+        scope,
+        must_haves,
+        donts,
+        acceptance_checks,
+        snippets,
+    };
+}
+/**
+ * Splits a markdown chunk into a map of H3 sections:
+ * "### Must Haves" -> "...", "### Don'ts" -> "..."
+ */
+function splitByH3(markdown) {
+    const lines = markdown.split("\n");
+    const out = {};
+    let currentKey = null;
+    let currentBody = [];
+    function push() {
+        if (!currentKey)
+            return;
+        out[currentKey] = currentBody.join("\n").trim();
+    }
+    for (const line of lines) {
+        const match = line.match(/^###\s+(.*)\s*$/);
+        if (match) {
+            push();
+            currentKey = match[1].trim().toLowerCase();
+            currentBody = [];
+        }
+        else {
+            if (currentKey)
+                currentBody.push(line);
+        }
+    }
+    push();
+    return out;
+}
+/**
+ * Convert a section's markdown to bullet array.
+ * Supports:
+ * - "- item"
+ * - "* item"
+ * - "1. item"
+ * Also supports basic one-level nesting.
+ */
+function toBullets(sectionMarkdown) {
+    if (!sectionMarkdown)
+        return [];
+    const lines = sectionMarkdown.replace(/\r\n/g, "\n").split("\n");
+    const items = [];
+    let current = null;
+    let nested = [];
+    function flushCurrent() {
+        if (!current)
+            return;
+        if (nested.length > 0) {
+            items.push(`${current}\n${nested.map((n) => `  - ${n}`).join("\n")}`);
+        }
+        else {
+            items.push(current);
+        }
+        current = null;
+        nested = [];
+    }
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/\t/g, "  ");
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // Nested bullet (2+ spaces then -/*)
+        const nestedMatch = line.match(/^\s{2,}[-*]\s+(.*)$/);
+        if (nestedMatch && current) {
+            nested.push(nestedMatch[1].trim());
+            continue;
+        }
+        // Top-level bullets at column 0
+        const topDash = line.match(/^[-*]\s+(.*)$/);
+        const topNum = line.match(/^\d+\.\s+(.*)$/);
+        if (topDash || topNum) {
+            flushCurrent();
+            current = (topDash?.[1] ?? topNum?.[1] ?? "").trim();
+            continue;
+        }
+        // Wrapped text continues current bullet
+        if (current) {
+            current = `${current} ${trimmed}`.trim();
+        }
+    }
+    flushCurrent();
+    return items;
+}
+/**
+ * Finds the first fenced block of a given language, e.g. ```yaml ... ```
+ * More forgiving: allows optional whitespace after language and tolerates missing trailing newline.
+ */
+function firstFencedBlock(markdown, language) {
+    const re = new RegExp("```" + language + "\\s*\\n([\\s\\S]*?)\\n?```", "i");
+    const m = markdown.match(re);
+    if (!m)
+        return null;
+    return { language: language.toLowerCase(), code: m[1].trim() };
+}
+/**
+ * Collect all fenced code blocks inside a chunk (any language).
+ */
+function allFencedBlocks(markdown) {
+    const re = /```([a-zA-Z0-9_-]+)?\s*\n([\s\S]*?)\n?```/g;
+    const blocks = [];
+    let m;
+    while ((m = re.exec(markdown)) !== null) {
+        const language = (m[1] ?? "").trim().toLowerCase() || "text";
+        const code = (m[2] ?? "").trim();
+        blocks.push({ language, code });
+    }
+    return blocks;
+}
+/**
+ * Minimal YAML parsing for the fields you use:
+ * - id: something
+ * - scope: [a, b]
+ * - OR scope:
+ *     - a
+ *     - b
+ *
+ * We keep MVP simple, but robust against common YAML patterns.
+ */
+function parseRuleYaml(yamlText, ctx) {
+    // id: value
+    const idMatch = yamlText.match(/^\s*id:\s*(.+)\s*$/m);
+    const id = idMatch ? idMatch[1].trim() : "";
+    // scope: [a, b]
+    const scopeInline = yamlText.match(/^\s*scope:\s*\[(.*)\]\s*$/m);
+    if (scopeInline) {
+        const raw = scopeInline[1]
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return { id, scope: toRuleScopeArray(raw, `${ctx}: scope`) };
+    }
+    // scope:
+    //   - a
+    //   - b
+    const scopeBlock = yamlText.match(/^\s*scope:\s*$(?:\r?\n([\s\S]*))?/m);
+    if (scopeBlock) {
+        const after = yamlText.split(/\r?\n/);
+        const startIndex = after.findIndex((l) => /^\s*scope:\s*$/.test(l));
+        const raw = [];
+        if (startIndex >= 0) {
+            for (let i = startIndex + 1; i < after.length; i++) {
+                const line = after[i];
+                // stop when a new top-level key begins (e.g. "title:" etc.)
+                if (/^\S+\s*:/.test(line))
+                    break;
+                const m = line.match(/^\s*-\s*(.+)\s*$/);
+                if (m)
+                    raw.push(m[1].trim());
+            }
+        }
+        return { id, scope: toRuleScopeArray(raw, `${ctx}: scope`) };
+    }
+    // No scope found
+    return { id, scope: [] };
+}