@a11y-context/mcp-server 0.1.0

package/dist/repo/index.js

@@ -0,0 +1,178 @@
+import fg from "fast-glob";
+import matter from "gray-matter";
+import path from "node:path";
+import { getRepoPaths } from "./paths.js";
+import { readTextFile, fileExists, toPosixPath } from "../utils/fs.js";
+function normalizeBullet(s, maxLen) {
+    if (typeof s !== "string")
+        return null;
+    const cleaned = s.replace(/\s+/g, " ").trim();
+    if (!cleaned)
+        return null;
+    return cleaned.length > maxLen ? cleaned.slice(0, maxLen).trimEnd() : cleaned;
+}
+function normalizeBulletList(value, maxItems, maxLen) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        const b = normalizeBullet(item, maxLen);
+        if (b)
+            out.push(b);
+        if (out.length >= maxItems)
+            break;
+    }
+    return out;
+}
+function parseSelectionExcerpt(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const v = value;
+    const use_when = normalizeBulletList(v.use_when, 3, 140);
+    const do_not_use_when = normalizeBulletList(v.do_not_use_when, 3, 140);
+    if (use_when.length === 0 && do_not_use_when.length === 0)
+        return undefined;
+    return { use_when, do_not_use_when };
+}
+function uniqSorted(values) {
+    const cleaned = values.map((s) => String(s).trim()).filter(Boolean);
+    return Array.from(new Set(cleaned)).sort((a, b) => a.localeCompare(b));
+}
+/**
+ * patterns.json supported shapes:
+ *  - { patterns: [...] }
+ *  - { items: [...] }
+ *  - [...] (array)
+ */
+function buildCatalogSelectionMap(catalogText) {
+    const map = new Map();
+    let parsed;
+    try {
+        parsed = JSON.parse(catalogText);
+    }
+    catch {
+        throw new Error("patterns.json is not valid JSON.");
+    }
+    const parsedObj = parsed;
+    const arr = Array.isArray(parsed)
+        ? parsed
+        : Array.isArray(parsedObj?.patterns)
+            ? parsedObj.patterns
+            : Array.isArray(parsedObj?.items)
+                ? parsedObj.items
+                : null;
+    if (!arr)
+        return map;
+    for (const entry of arr) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const entryObj = entry;
+        const id = typeof entryObj.id === "string" ? entryObj.id.trim() : "";
+        if (!id)
+            continue;
+        const excerpt = parseSelectionExcerpt(entryObj.selection_excerpt);
+        if (excerpt)
+            map.set(id, excerpt);
+    }
+    return map;
+}
+/**
+ * Reads + indexes the content repo once.
+ * After this, list_patterns is very fast.
+ */
+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}`);
+    }
+    if (!(await fileExists(catalogPath))) {
+        throw new Error(`Missing catalog file: ${catalogPath}`);
+    }
+    // Deterministic ordering: sort file paths before reading/hashing/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
+    const fileTextByPath = new Map();
+    for (const p of componentPaths) {
+        // NOTE: componentPaths are POSIX normalized; ensure readTextFile can handle them on Windows.
+        // If not, store original paths separately. (If you're not targeting Windows right now, you're fine.)
+        fileTextByPath.set(p, await readTextFile(p));
+    }
+    // The corpus's own semantic version (from patterns.json), surfaced to clients
+    // so they see e.g. "0.5.2" rather than an opaque content hash.
+    let catalog_revision = "unknown";
+    try {
+        const parsedCatalog = JSON.parse(catalogText);
+        if (typeof parsedCatalog.catalog_revision === "string") {
+            catalog_revision = parsedCatalog.catalog_revision;
+        }
+    }
+    catch {
+        // leave as "unknown" if the catalog isn't valid JSON
+    }
+    const byId = new Map();
+    const idToPath = new Map();
+    const all = [];
+    for (const filePath of componentPaths) {
+        const raw = fileTextByPath.get(filePath);
+        if (raw == null)
+            throw new Error(`Internal error: missing cached text for ${filePath}`);
+        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}`);
+        }
+        const declaredStack = String(data.stack ?? "").trim();
+        const status = String(data.status ?? "").trim();
+        const summary = String(data.summary ?? "").trim();
+        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}`);
+        }
+        if (!summary) {
+            throw new Error(`Pattern missing 'summary' in frontmatter: ${filePath}`);
+        }
+        const allowed = ["alpha", "beta", "stable", "deprecated"];
+        if (!allowed.includes(status)) {
+            throw new Error(`Invalid status '${status}' in ${filePath}. Allowed: ${allowed.join(", ")}`);
+        }
+        const selection_excerpt = selectionById.get(id);
+        const pattern = {
+            id,
+            stack,
+            status,
+            summary,
+            tags: uniqSorted(tags),
+            aliases: uniqSorted(aliases),
+            ...(selection_excerpt ? { selection_excerpt } : {}),
+        };
+        if (byId.has(id)) {
+            throw new Error(`Duplicate pattern id '${id}' found. Second copy: ${filePath}`);
+        }
+        byId.set(id, pattern);
+        idToPath.set(id, filePath);
+        all.push(pattern);
+    }
+    // Already stable by filePath sort, but keep this as a last-line guarantee
+    all.sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        stack,
+        cache: { catalog_revision, cache_ttl_seconds: cacheTtlSeconds },
+        byId,
+        idToPath,
+        all,
+    };
+}
+/**
+ * Helper to make debug info safe and consistent for output.
+ */
+export function makeRelativePath(patternRepoPath, filePath) {
+    const rel = path.relative(patternRepoPath, filePath);
+    return toPosixPath(rel);
+}

package/dist/repo/paths.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+/**
+ * Maps a stack name to actual file locations in the content repo.
+ */
+export function getRepoPaths(patternRepoPath, stack) {
+    // Turns "web/react" into ["web", "react"], etc.
+    const parts = stack.split("/");
+    // Defensive check (helpful for beginners)
+    if (parts.length !== 2) {
+        throw new Error(`Invalid stack format: ${stack}. Expected "group/name" like "web/react".`);
+    }
+    // Corpus structure (bundled at <package>/corpus, or an override root):
+    //   <root>/web/react/global/global_rules.md
+    //   <root>/web/react/components/*.md
+    //   <root>/web/react/patterns.json
+    //   <root>/android/compose/...   (when populated)
+    const root = path.join(patternRepoPath, ...parts);
+    return {
+        baselinePath: path.join(root, "global", "global_rules.md"),
+        catalogPath: path.join(root, "patterns.json"),
+        // IMPORTANT: make it recursive so nested folders work
+        // and include mdx/markdown if you ever use them.
+        componentsGlob: path.join(root, "components", "**", "*.{md,mdx,markdown}"),
+    };
+}

package/dist/repo/sections.js

@@ -0,0 +1,166 @@
+// src/repo/sections.ts
+/**
+ * Goal:
+ * Turn a markdown body into deterministic sections for AI consumption.
+ *
+ * This is intentionally "good enough" for v1:
+ * - It relies on headings (## Heading)
+ * - It extracts bullet lists into string arrays
+ * - It preserves Golden Pattern as markdown (often contains code blocks)
+ */
+// Headings we recognize, mapped to keys in ParsedSections.
+// Add more later without changing the rest of the parser.
+const HEADING_TO_KEY = {
+    "use when": "use_when",
+    "do not use when": "do_not_use_when",
+    "must haves": "must_haves",
+    "customizable": "customizable",
+    "don'ts": "donts",
+    "don’ts": "donts",
+    "donts": "donts",
+    "golden pattern": "golden_pattern",
+    "acceptance checks": "acceptance_checks",
+};
+/**
+ * Extract sections from markdown (content without frontmatter).
+ */
+export function extractSections(markdownBody) {
+    const normalized = markdownBody
+        .replace(/\r\n/g, "\n")
+        // normalize non-breaking spaces to regular spaces
+        .replace(/\u00A0/g, " ")
+        // normalize curly apostrophes to ASCII apostrophe
+        .replace(/[’‘]/g, "'");
+    // We’ll build up sections as raw markdown chunks first.
+    const rawByKey = {};
+    // Default output
+    const out = {
+        use_when: [],
+        do_not_use_when: [],
+        must_haves: [],
+        customizable: [],
+        donts: [],
+        golden_pattern: null,
+        acceptance_checks: [],
+    };
+    // Split by headings like: ## Something
+    // We keep the heading text so we know where each chunk belongs.
+    const parts = splitByH2(normalized);
+    for (const part of parts) {
+        const heading = (part.heading ?? "")
+            .replace(/\u00A0/g, " ")
+            .replace(/[’‘]/g, "'")
+            .trim()
+            .toLowerCase()
+            .replace(/[:.]+$/, ""); // tolerate "Golden Pattern:" style
+        const key = HEADING_TO_KEY[heading];
+        if (!key)
+            continue;
+        rawByKey[key] = (part.body ?? "").trim();
+    }
+    // Convert list-like sections to arrays
+    out.use_when = toBulletArray(rawByKey.use_when);
+    out.do_not_use_when = toBulletArray(rawByKey.do_not_use_when);
+    out.must_haves = toBulletArray(rawByKey.must_haves);
+    out.customizable = toBulletArray(rawByKey.customizable);
+    out.donts = toBulletArray(rawByKey.donts);
+    out.acceptance_checks = toBulletArray(rawByKey.acceptance_checks);
+    // Golden Pattern is special: keep markdown as-is (often code fences)
+    const golden = (rawByKey.golden_pattern ?? "").trim();
+    out.golden_pattern = golden.length > 0 ? golden : null;
+    return out;
+}
+/**
+ * Splits markdown by "##" headings.
+ * Returns an array like:
+ * - { heading: "Use when", body: "..." }
+ * - { heading: "Must haves", body: "..." }
+ */
+function splitByH2(markdown) {
+    const lines = markdown.split("\n");
+    const result = [];
+    let currentHeading = null;
+    let currentBody = [];
+    function pushCurrent() {
+        // Don’t push empty preamble
+        if (currentHeading === null && currentBody.join("\n").trim() === "")
+            return;
+        result.push({ heading: currentHeading, body: currentBody.join("\n") });
+    }
+    for (const line of lines) {
+        const match = line.match(/^##[ \t\u00A0]+(.*)$/);
+        if (match) {
+            // New section begins
+            pushCurrent();
+            currentHeading = match[1].trim();
+            currentBody = [];
+        }
+        else {
+            currentBody.push(line);
+        }
+    }
+    pushCurrent();
+    return result;
+}
+/**
+ * Converts a markdown chunk into a list of bullet strings.
+ * Supports:
+ * - "- item"
+ * - "* item"
+ * - "1. item" (simple numbered lists)
+ *
+ * If the section isn't a list, we return [] (v1 simplicity).
+ */
+function toBulletArray(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;
+        // Markdown subheadings inside a section (e.g. the `### Roles & structure`
+        // concern groups within Must Haves) are structure, not bullets. Flush any
+        // active bullet and skip the heading so it isn't concatenated into text.
+        if (/^#{1,6}\s/.test(trimmed)) {
+            flushCurrent();
+            continue;
+        }
+        // One-level nested bullets must be handled before top-level matching.
+        const nestedMatch = line.match(/^\s{2,}[-*]\s+(.*)$/);
+        if (nestedMatch && current) {
+            nested.push(nestedMatch[1].trim());
+            continue;
+        }
+        // Top-level bullets start 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 the active top-level bullet.
+        if (current) {
+            current = `${current} ${trimmed}`.trim();
+        }
+    }
+    flushCurrent();
+    return items;
+}

package/dist/smoke/smoke-remote-mcp.js

@@ -0,0 +1,43 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+const url = process.argv[2];
+if (!url)
+    throw new Error("Usage: node dist/smoke-remote-mcp.js https://host/mcp");
+const client = new Client({ name: "smoke-test", version: "1.0.0" });
+const transport = new StreamableHTTPClientTransport(new URL(url));
+await client.connect(transport);
+function assertHasStructuredContent(result, toolName) {
+    if (!result ||
+        typeof result !== "object" ||
+        !("structuredContent" in result) ||
+        !result.structuredContent ||
+        typeof result.structuredContent !== "object") {
+        throw new Error(`${toolName} missing structuredContent in tool response.`);
+    }
+}
+// Just verifying the protocol handshake and tool listing works
+const tools = await client.listTools();
+console.log("Connected. Tool count:", tools.tools?.length ?? 0);
+console.log("Tool names:", (tools.tools ?? []).map((t) => t.name));
+const listPatternsResult = await client.callTool({
+    name: "list_patterns",
+    arguments: { stack: "web/react" },
+});
+assertHasStructuredContent(listPatternsResult, "list_patterns");
+const listPayload = listPatternsResult.structuredContent;
+const firstPatternId = listPayload.patterns?.[0]?.id;
+if (!firstPatternId) {
+    throw new Error("list_patterns returned no patterns; cannot run get_pattern smoke check.");
+}
+const getGlobalRulesResult = await client.callTool({
+    name: "get_global_rules",
+    arguments: { stack: "web/react" },
+});
+assertHasStructuredContent(getGlobalRulesResult, "get_global_rules");
+const getPatternResult = await client.callTool({
+    name: "get_pattern",
+    arguments: { stack: "web/react", id: firstPatternId },
+});
+assertHasStructuredContent(getPatternResult, "get_pattern");
+console.log(`structuredContent check passed (list_patterns, get_global_rules, get_pattern). sample_pattern_id=${firstPatternId}`);
+process.exit(0);

package/dist/telemetry.js

@@ -0,0 +1,15 @@
+import crypto from "node:crypto";
+export function newTraceId() {
+    return crypto.randomUUID();
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function estimateTokensFromChars(chars) {
+    // Crude but consistent estimate.
+    return Math.ceil(chars / 4);
+}
+export function logTelemetry(evt) {
+    // Keep MCP stdio output clean by writing telemetry to stderr.
+    console.error(JSON.stringify(evt));
+}

package/dist/telemetryWrap.js

@@ -0,0 +1,48 @@
+import { estimateTokensFromChars, logTelemetry, newTraceId, nowIso } from "./telemetry.js";
+export async function withTelemetry(params) {
+    const traceId = newTraceId();
+    const startMs = Date.now();
+    try {
+        const result = await params.handler();
+        const durationMs = Date.now() - startMs;
+        const argsJson = JSON.stringify(params.args ?? {});
+        const responseJson = JSON.stringify(result ?? {});
+        logTelemetry({
+            ts: nowIso(),
+            trace_id: traceId,
+            tool: params.tool,
+            stack: params.stack,
+            ok: true,
+            duration_ms: durationMs,
+            sizes: {
+                args_bytes: Buffer.byteLength(argsJson, "utf8"),
+                response_bytes: Buffer.byteLength(responseJson, "utf8"),
+                response_chars: responseJson.length,
+                est_tokens_chars_div4: estimateTokensFromChars(responseJson.length),
+            },
+            result: params.summarizeResult?.(result),
+        });
+        return result;
+    }
+    catch (error) {
+        const durationMs = Date.now() - startMs;
+        const argsJson = JSON.stringify(params.args ?? {});
+        const message = error instanceof Error ? error.message : String(error);
+        logTelemetry({
+            ts: nowIso(),
+            trace_id: traceId,
+            tool: params.tool,
+            stack: params.stack,
+            ok: false,
+            duration_ms: durationMs,
+            sizes: {
+                args_bytes: Buffer.byteLength(argsJson, "utf8"),
+                response_bytes: 0,
+                response_chars: 0,
+                est_tokens_chars_div4: 0,
+            },
+            error: { message },
+        });
+        throw error;
+    }
+}

package/dist/tools/getGlobalRules.js

@@ -0,0 +1,33 @@
+import { readTextFile } from "../utils/fs.js";
+import { getRepoPaths } from "../repo/paths.js";
+import { parseGlobalRulesMarkdown } from "../repo/globalRules.js";
+function normalizeScope(scope) {
+    if (!scope)
+        return null;
+    return Array.isArray(scope) ? scope : [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}`);
+    }
+    const scopeFilter = normalizeScope(args.scope);
+    const { baselinePath } = getRepoPaths(patternRepoPath, stack);
+    const fileText = await readTextFile(baselinePath);
+    const parsed = parseGlobalRulesMarkdown(fileText, stack);
+    const cache_ttl_seconds = parsed.meta.cache_ttl_seconds ?? index.cache.cache_ttl_seconds;
+    const items = scopeFilter
+        ? parsed.rules.filter((r) => r.scope.some((s) => scopeFilter.includes(s)))
+        : parsed.rules;
+    return {
+        contract_version: "1.0",
+        stack,
+        catalog_revision: index.cache.catalog_revision,
+        cache_ttl_seconds,
+        meta: parsed.meta,
+        rules: {
+            scope_filter: scopeFilter, // additive
+            items,
+        },
+    };
+}

package/dist/tools/getPattern.js

@@ -0,0 +1,54 @@
+// src/tools/getPattern.ts
+import matter from "gray-matter";
+import { readTextFile } from "../utils/fs.js";
+import { extractSections } from "../repo/sections.js";
+import { makeRelativePath } from "../repo/index.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}`);
+    }
+    const filePath = index.idToPath.get(id);
+    if (!filePath) {
+        throw new Error(`PATTERN_NOT_FOUND: No pattern with id '${id}' for stack '${stack}'`);
+    }
+    const raw = await readTextFile(filePath);
+    const parsed = matter(raw);
+    const data = parsed.data;
+    // Frontmatter fields (strict enough for v1)
+    const patternId = String(data.id ?? "").trim();
+    const status = String(data.status ?? "").trim();
+    const summary = String(data.summary ?? "").trim();
+    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}`);
+    if (patternId !== id) {
+        throw new Error(`Pattern id mismatch. Requested '${id}', file declares '${patternId}' (${filePath})`);
+    }
+    // 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}`);
+    }
+    if (!summary)
+        throw new Error(`Pattern missing 'summary' in frontmatter: ${filePath}`);
+    const sections = extractSections(parsed.content);
+    const detail = {
+        id,
+        stack,
+        status,
+        summary,
+        tags,
+        aliases,
+        sections,
+        source: {
+            relative_path: makeRelativePath(patternRepoPath, filePath),
+        },
+    };
+    return {
+        contract_version: "1.0",
+        ...index.cache,
+        pattern: detail,
+    };
+}

package/dist/tools/listPatterns.js

@@ -0,0 +1,33 @@
+export function listPatterns(index, args) {
+    const { stack, tags, query } = args;
+    if (stack !== index.stack) {
+        throw new Error(`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.
+    if (tags && tags.length > 0) {
+        const wanted = new Set(tags.map((t) => t.toLowerCase()));
+        results = results.filter((p) => p.tags.some((t) => wanted.has(t.toLowerCase())));
+    }
+    // Simple query search across id, summary, aliases
+    if (query && query.trim()) {
+        const q = query.toLowerCase();
+        results = results.filter((p) => {
+            if (p.id.toLowerCase().includes(q))
+                return true;
+            if (p.summary.toLowerCase().includes(q))
+                return true;
+            if (p.aliases.some((a) => a.toLowerCase().includes(q)))
+                return true;
+            return false;
+        });
+    }
+    results = [...results].sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        contract_version: "1.0",
+        stack,
+        ...index.cache,
+        count: results.length,
+        patterns: results,
+    };
+}

package/dist/utils/fs.js

@@ -0,0 +1,18 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readTextFile(filePath) {
+    return fs.readFile(filePath, "utf8");
+}
+export function toPosixPath(p) {
+    // Normalizes Windows backslashes to forward slashes for consistent output.
+    return p.split(path.sep).join("/");
+}

package/dist/utils/hash.js

@@ -0,0 +1,4 @@
+import crypto from "node:crypto";
+export function sha256(text) {
+    return crypto.createHash("sha256").update(text).digest("hex");
+}