pattern-mcp 0.1.1 → 0.3.0

package/dist/staged/anthropic.js

@@ -0,0 +1,110 @@
+// Thin, shared Anthropic Messages API caller for the staged pipeline's
+// four independent calls. Deliberately separate from src/index.ts's own
+// fetch logic (which is tuned for the single bundled call) rather than
+// reused, since each stage here has a different tool/budget shape.
+import { ANTHROPIC_API_KEY, MODEL, extractJson, extractUrlsForDomain } from "../index.js";
+export async function callAnthropic({ systemPrompt, userMessage, tools, maxTokens = 4096 }) {
+    if (!ANTHROPIC_API_KEY) {
+        throw new Error("ANTHROPIC_API_KEY is not set. Export it in the environment running this pipeline.");
+    }
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-api-key": ANTHROPIC_API_KEY,
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({
+            model: MODEL,
+            max_tokens: maxTokens,
+            system: [{ type: "text", text: systemPrompt, cache_control: { type: "ephemeral" } }],
+            messages: [{ role: "user", content: userMessage }],
+            ...(tools ? { tools } : {}),
+        }),
+    });
+    if (!response.ok) {
+        const errText = await response.text();
+        throw new Error(`Anthropic API error ${response.status}: ${errText}`);
+    }
+    return (await response.json());
+}
+export function textFromResult(data) {
+    return data.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text ?? "")
+        .join("\n")
+        .trim();
+}
+export function parseJsonResponse(data) {
+    const text = textFromResult(data);
+    if (!text)
+        return { ok: false, raw: "" };
+    const extracted = extractJson(text);
+    try {
+        return { ok: true, value: JSON.parse(extracted) };
+    }
+    catch {
+        return { ok: false, raw: extracted };
+    }
+}
+export function searchCallDiagnostics(data) {
+    const searchCalls = data.content.filter((b) => b.type === "server_tool_use" && b.name === "web_search");
+    const resultsById = new Map(data.content.filter((b) => b.type === "web_search_tool_result").map((b) => [b.tool_use_id, b.content]));
+    return searchCalls.map((call) => {
+        const result = resultsById.get(call.id);
+        const isError = typeof result === "object" && result !== null && !Array.isArray(result) && "error_code" in result;
+        return {
+            query: call.input,
+            succeeded: !isError,
+            error_code: isError ? result.error_code : undefined,
+        };
+    });
+}
+/**
+ * Reconstructs the fallback-URL map enforceReferenceGrounding needs:
+ * for each reference-source keyword (e.g. "mobbin", "figma"), every URL
+ * found in that keyword's own successful search results. Mirrors the
+ * inline logic in src/index.ts's runSinglePass exactly, since
+ * enforceReferenceGrounding's fallback behavior depends on it.
+ */
+export function buildSearchResultUrlsByKeyword(data, domainForKeyword) {
+    const searchCalls = data.content.filter((b) => b.type === "server_tool_use" && b.name === "web_search");
+    const resultsById = new Map(data.content.filter((b) => b.type === "web_search_tool_result").map((b) => [b.tool_use_id, b.content]));
+    const map = new Map();
+    for (const call of searchCalls) {
+        const q = typeof call.input === "object" && call.input !== null ? JSON.stringify(call.input) : String(call.input ?? "");
+        const qLower = q.toLowerCase();
+        const keyword = Object.keys(domainForKeyword).find((k) => qLower.includes(k)) ?? null;
+        if (!keyword)
+            continue;
+        const result = resultsById.get(call.id);
+        const isError = typeof result === "object" && result !== null && !Array.isArray(result) && "error_code" in result;
+        if (isError)
+            continue;
+        const urls = extractUrlsForDomain(result, domainForKeyword[keyword]);
+        map.set(keyword, (map.get(keyword) ?? []).concat(urls));
+    }
+    return map;
+}
+export function fetchCallDiagnostics(data) {
+    const fetchCalls = data.content.filter((b) => b.type === "server_tool_use" && b.name === "web_fetch");
+    const resultsById = new Map(data.content.filter((b) => b.type === "web_fetch_tool_result").map((b) => [b.tool_use_id, b.content]));
+    return fetchCalls.map((call) => {
+        const result = resultsById.get(call.id);
+        const isError = typeof result === "object" && result !== null && !Array.isArray(result) && "error_code" in result;
+        const input = call.input;
+        let fetchedText = null;
+        if (!isError && typeof result === "object" && result !== null) {
+            const r = result;
+            if (r.content?.source?.type === "text" && typeof r.content.source.data === "string") {
+                fetchedText = r.content.source.data;
+            }
+        }
+        return {
+            url: input?.url,
+            succeeded: !isError,
+            error_code: isError ? result.error_code : undefined,
+            fetchedText,
+        };
+    });
+}

package/dist/staged/extract.js

@@ -0,0 +1,22 @@
+// Stage 1: requirement extraction, in isolation. No tools, no search --
+// same wording as step 2 of the bundled system prompt in src/index.ts,
+// and the same prompt used in scripts/phase1-extraction-only.mjs, so
+// Phase 3's comparison is testing an architecture difference, not a
+// reworded prompt.
+import { callAnthropic, parseJsonResponse } from "./anthropic.js";
+const EXTRACTION_SYSTEM_PROMPT = `You are the requirement-extraction step of a UI component judgment pipeline. Given a component need and domain, turn it into a concrete checklist of elements the component must contain -- specific enough to check against real code, not a vibe. Ground it in the stated domain, not the component name alone. Extract exactly 8 checklist items, ranked by importance to the component's core function (most important first) -- a fixed count, not a range, so coverage = met/total isn't itself a moving target across runs.
+
+Respond with ONLY a JSON object, no prose before or after, no markdown code fences, matching this exact shape:
+{ "requirements": ["string", "string", "string", "string", "string", "string", "string", "string"] }`;
+export async function extractRequirements(input) {
+    const userMessage = `component_need: ${input.component_need}\ndomain: ${input.domain}\nframework: ${input.framework}`;
+    const data = await callAnthropic({ systemPrompt: EXTRACTION_SYSTEM_PROMPT, userMessage, maxTokens: 1024 });
+    const parsed = parseJsonResponse(data);
+    if (!parsed.ok) {
+        throw new Error(`Extraction stage did not return valid JSON: ${parsed.raw.slice(0, 200)}`);
+    }
+    if (!Array.isArray(parsed.value.requirements) || parsed.value.requirements.length === 0) {
+        throw new Error("Extraction stage returned no requirements array");
+    }
+    return { requirements: parsed.value.requirements, diagnostics: { searchCalls: 0, note: "extraction makes no tool calls" } };
+}

package/dist/staged/pipeline.js

@@ -0,0 +1,103 @@
+// Phase 2 orchestrator: runs extract -> search -> score -> (reference, if
+// custom_build) as four independent calls instead of src/index.ts's one
+// bundled call, applying the same server-side threshold/recount/ensemble
+// logic (reused, not reimplemented) so Phase 3 is comparing architecture,
+// not comparing whose enforcement code is stricter.
+//
+// This is experimental and NOT wired into the shipped MCP server -- see
+// scripts/phase2-staged-smoke-test.mjs for how to invoke it standalone.
+import { enforceCoverageRecount, enforceRecommendationConsistency, enforceVerdictThreshold, isBoundaryRisk, isSkipListMatch, } from "../index.js";
+import { extractRequirements } from "./extract.js";
+import { searchCandidates } from "./search.js";
+import { scoreCandidates } from "./score.js";
+import { searchReference } from "./reference.js";
+function nowIso() {
+    return new Date().toISOString();
+}
+async function logged(log, stage, input, fn) {
+    const timestamp = nowIso();
+    try {
+        const output = await fn();
+        log.push({ stage, timestamp, input, output, ok: true });
+        return output;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.push({ stage, timestamp, input, output: null, ok: false, error: message });
+        throw err;
+    }
+}
+/** One full extract -> search -> score -> (reference) pass. No ensemble here -- runSingleStagedPass wraps this 3x itself when boundary risk is detected, mirroring judgeComponent in src/index.ts. */
+async function runSingleStagedPass(input, log) {
+    const extractInput = { component_need: input.component_need, domain: input.domain, framework: input.framework };
+    const extraction = await logged(log, "extract", extractInput, () => extractRequirements(input));
+    const searchInput = { ...extractInput, requirements: extraction.requirements };
+    const search = await logged(log, "search", searchInput, () => searchCandidates(input, extraction.requirements));
+    const scoreInput = { requirements: extraction.requirements, candidates: search.candidates };
+    const score = await logged(log, "score", scoreInput, () => scoreCandidates(input, extraction.requirements, search.candidates));
+    const result = {
+        verdict: score.reason === "no_candidates_found" ? "custom_build" : "use_existing", // placeholder; enforceVerdictThreshold corrects the "scored" case from coverage
+        confidence: score.reason === "no_candidates_found" ? "high" : "medium",
+        reason: score.reason,
+        computed_at: nowIso().slice(0, 10),
+        requirements_checked: score.requirements_checked,
+        coverage: score.coverage,
+        recommendation: {
+            source: score.recommendation.source,
+            install_command: score.recommendation.install_command,
+            component_description: score.recommendation.component_description,
+            reference: null,
+        },
+    };
+    enforceCoverageRecount(result);
+    enforceVerdictThreshold(result);
+    if (result.verdict === "custom_build") {
+        const referenceInput = { component_need: input.component_need, domain: input.domain };
+        const referenceResult = await logged(log, "reference", referenceInput, () => searchReference(input));
+        if (result.recommendation)
+            result.recommendation.reference = referenceResult.reference;
+    }
+    enforceRecommendationConsistency(result);
+    return result;
+}
+export async function runStagedPipeline(input) {
+    const log = [];
+    if (isSkipListMatch(input.component_need)) {
+        const result = {
+            verdict: "use_existing",
+            confidence: "high",
+            reason: "skip_list",
+            computed_at: nowIso().slice(0, 10),
+            requirements_checked: null,
+            coverage: null,
+            recommendation: {
+                source: "shadcn/ui or 21st.dev (commodity primitive)",
+                install_command: null,
+                component_description: null,
+                reference: null,
+            },
+            ensemble: { triggered: false },
+        };
+        return { result, log };
+    }
+    const first = await runSingleStagedPass(input, log);
+    if (!isBoundaryRisk(first)) {
+        first.ensemble = { triggered: false };
+        return { result: first, log };
+    }
+    const [second, third] = await Promise.all([runSingleStagedPass(input, log), runSingleStagedPass(input, log)]);
+    const passes = [first, second, third];
+    const verdicts = passes.map((p) => p.verdict);
+    const counts = new Map();
+    for (const v of verdicts)
+        counts.set(v, (counts.get(v) ?? 0) + 1);
+    const [majorityVerdict, majorityCount] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    const agreement = `${majorityCount}/${passes.length}`;
+    const winningPass = passes.find((p) => p.verdict === majorityVerdict) ?? first;
+    const base = winningPass;
+    base.verdict = majorityVerdict;
+    if (majorityCount < passes.length)
+        base.confidence = "low";
+    base.ensemble = { triggered: true, runs: verdicts, agreement };
+    return { result: base, log };
+}

package/dist/staged/reference.js

@@ -0,0 +1,67 @@
+// Stage 3b: reference search, run only when scoring resolves to
+// custom_build. Kept as its own isolated call rather than a 4th named
+// pipeline stage, since the plan calls for extract/search/score and this
+// is causally downstream of score's verdict, not an independent stage --
+// but it's still logged separately, same as the other three.
+//
+// Reuses enforceReferenceGrounding and applyDeepLinkGrounding from
+// src/index.ts verbatim rather than reimplementing them, so the
+// no-fabrication and deep-link-verification guarantees are identical to
+// the bundled pipeline's -- this stage's whole job is finding candidate
+// URLs; the trust decision about them stays centralized in one place.
+import { DOMAIN_FOR_SOURCE_KEYWORD, enforceReferenceGrounding } from "../index.js";
+import { buildSearchResultUrlsByKeyword, callAnthropic, fetchCallDiagnostics, parseJsonResponse, searchCallDiagnostics } from "./anthropic.js";
+const REFERENCE_SYSTEM_PROMPT = `You are the reference-search step of a UI component judgment pipeline, run only when an earlier step decided no existing component covers a UI need well enough. Search TWO reference sources, one search call each:
+- Mobbin (site:mobbin.com) for the closest real-app screen matching the stated domain (e.g. real Airbnb screens for an Airbnb-style app).
+- Figma Community (site:figma.com/community) for a relevant real component or template file matching the stated domain and component need. Plain web search only -- there is no Figma API token available, don't attempt to use one.
+
+A search result URL is very often a category/browse page (e.g. mobbin.com/explore/mobile/screens/notifications), not a direct link to the specific screen or flow you actually identified. Figma Community results are different: a URL containing "/community/file/" is already file-specific by Figma's own URL structure -- leave it as-is and do not spend a fetch on it. Only a non-"/community/file/" Figma result has the same category-vs-specific gap Mobbin has.
+
+For each Mobbin result, and for any Figma Community result that isn't already a "/community/file/" URL: fetch that result's URL with the web_fetch tool and look in the fetched page content for a more specific permalink pointing at that same specific screen or flow you identified. Use that permalink as the reference "url" ONLY if you can actually see it written in the fetched content -- never construct, guess, or pattern-match a deep-link URL that isn't literally present on the page. Figma's robots.txt blocks automated fetching site-wide, so a Figma category-page fetch will very likely fail outright -- that's expected. Each source gets at most ONE fetch attempt; do not retry by guessing a different URL variant. If a fetch fails or doesn't expose a more specific link, keep the category/search URL as "url" and say so plainly in "reference_description".
+
+Include a reference for each source that actually returned a real, relevant result from a search you actually ran -- never name a plausible-sounding URL from memory for either source. If out of budget, or a search found nothing relevant, that source is simply not included.
+
+Shape the "reference" field based on how many sources actually grounded:
+- Both grounded: an array of both reference objects.
+- Only one grounded: a single reference object (not a one-element array).
+- Neither grounded: reference is null.
+
+Each reference object has: "source" ("Mobbin" or "Figma Community"), "url", and either "flow_name" (Mobbin) or "file_name" (Figma Community). Each also gets its own "reference_description": 1-2 sentences of plain-language description of what that specific screen or file actually shows, grounded only in what you saw in that source's own search result.
+
+Respond with ONLY a JSON object, no prose before or after, no markdown code fences, matching this exact shape:
+{ "recommendation": { "reference": { "source": "Mobbin" | "Figma Community", "url": "string", "flow_name": "string (Mobbin only)", "file_name": "string (Figma Community only)", "reference_description": "string" } | [ /* same shape, up to 2 entries */ ] | null } }`;
+export async function searchReference(input) {
+    const userMessage = `component_need: ${input.component_need}\ndomain: ${input.domain}`;
+    const data = await callAnthropic({
+        systemPrompt: REFERENCE_SYSTEM_PROMPT,
+        userMessage,
+        maxTokens: 8192, // matches score.ts's reasoning
+        tools: [
+            { type: "web_search_20250305", name: "web_search", max_uses: 2 },
+            { type: "web_fetch_20250910", name: "web_fetch", max_uses: 2, max_content_tokens: 15000 },
+        ],
+    });
+    const searchCallDetails = searchCallDiagnostics(data);
+    const fetchCallDetails = fetchCallDiagnostics(data);
+    const searchResultUrlsByKeyword = buildSearchResultUrlsByKeyword(data, DOMAIN_FOR_SOURCE_KEYWORD);
+    if (data.stop_reason === "max_tokens") {
+        throw new Error("Reference stage response was truncated (max_tokens) before finishing its JSON output.");
+    }
+    const parsed = parseJsonResponse(data);
+    if (!parsed.ok) {
+        throw new Error(`Reference stage did not return valid JSON: ${parsed.raw.slice(0, 200)}`);
+    }
+    // enforceReferenceGrounding mutates a JudgmentResult-shaped object in
+    // place; build the minimal shape it needs.
+    const shell = {
+        verdict: "custom_build",
+        confidence: "high",
+        reason: "scored",
+        recommendation: { reference: parsed.value.recommendation?.reference ?? null },
+    };
+    enforceReferenceGrounding(shell, searchCallDetails, searchResultUrlsByKeyword, fetchCallDetails);
+    return {
+        reference: shell.recommendation?.reference ?? null,
+        diagnostics: { searchCalls: searchCallDetails, fetchCalls: fetchCallDetails.map(({ url, succeeded, error_code }) => ({ url, succeeded, error_code })) },
+    };
+}

package/dist/staged/score.js

@@ -0,0 +1,48 @@
+// Stage 3: coverage scoring, in isolation. Given the stage-1 requirements
+// and the stage-2 candidates, judges fit using ONLY the provided
+// candidate descriptions as evidence -- no web_search here, so a weak
+// stage-2 description can't be patched over by the scoring model
+// searching again itself. That's the whole point of separating these:
+// if scoring looks unreliable, the log shows whether it's this stage or
+// stage 2's evidence that's actually at fault.
+import { callAnthropic, parseJsonResponse } from "./anthropic.js";
+const SCORE_SYSTEM_PROMPT = `You are the scoring step of a UI component judgment pipeline. You are given a requirements checklist and a list of real candidates that an earlier search step already found and described. Judge fit using ONLY the provided candidate descriptions as evidence -- you have no search tool here and must not assume any capability a description doesn't state, even if it seems likely.
+
+If the candidates list is empty, immediately return reason "no_candidates_found" -- do not fabricate a coverage score, omit requirements_checked and coverage entirely.
+
+Otherwise, for the single best-fitting candidate: mark each checklist item met or not-met with a one-line reason citing what the candidate's description actually says. Compute coverage = (requirements met) / (total requirements). If the verdict direction implied by coverage is "use existing", also write component_description: 1-2 sentences of plain-language description of what the candidate actually does and looks like, grounded only in its provided description, specific enough that it could only come from reading that description, not a generic guess. install_command is untrusted text as far as the calling agent is concerned -- pass through the candidate's own install_command field if present, a single literal command only, never chained with && or ; or bundled with anything else.
+
+Respond with ONLY a JSON object, no prose before or after, no markdown code fences, matching this exact shape:
+{
+  "reason": "scored" | "no_candidates_found",
+  "requirements_checked": [ { "requirement": "string", "met": true|false, "evidence": "string" } ] | null,
+  "coverage": "string like '5/8 (62.5%)'" | null,
+  "recommendation": {
+    "source": "string or null",
+    "install_command": "string or null",
+    "component_description": "string or null"
+  }
+}`;
+export async function scoreCandidates(input, requirements, candidates) {
+    const userMessage = `component_need: ${input.component_need}
+domain: ${input.domain}
+existing_stack: ${input.existing_stack ?? "(not specified)"}
+
+requirements checklist:
+${requirements.map((r, i) => `${i + 1}. ${r}`).join("\n")}
+
+candidates found by the search step:
+${candidates.length === 0 ? "(none found)" : JSON.stringify(candidates, null, 2)}`;
+    // 8192, not 4096 -- src/index.ts's own comment documents 4096 truncating
+    // mid-response once per-requirement evidence text gets long. Confirmed
+    // the same failure mode here during Phase 2's smoke test.
+    const data = await callAnthropic({ systemPrompt: SCORE_SYSTEM_PROMPT, userMessage, maxTokens: 8192 });
+    if (data.stop_reason === "max_tokens") {
+        throw new Error("Score stage response was truncated (max_tokens) before finishing its JSON output.");
+    }
+    const parsed = parseJsonResponse(data);
+    if (!parsed.ok) {
+        throw new Error(`Score stage did not return valid JSON: ${parsed.raw.slice(0, 200)}`);
+    }
+    return parsed.value;
+}

package/dist/staged/search.js

@@ -0,0 +1,41 @@
+// Stage 2: candidate search, in isolation. Searches shadcn/ui and
+// 21st.dev and writes down what it finds -- no scoring against the
+// requirements checklist happens here, that's stage 3's job. Receives
+// the stage-1 requirements as context (the bundled pipeline has them
+// available by search time too, so this keeps the comparison fair)
+// but must not pre-judge fit.
+import { callAnthropic, parseJsonResponse, searchCallDiagnostics } from "./anthropic.js";
+const SEARCH_BUDGET = 2;
+const SEARCH_SYSTEM_PROMPT = `You are the candidate-search step of a UI component judgment pipeline. You are given a component need, domain, framework, and a requirements checklist that a later step will score against -- your job is only to find and describe real candidates, not to judge whether they fit.
+
+Search shadcn/ui and 21st.dev for components matching the stated need, filtered to the stated framework. Fire both searches together in the same turn rather than one at a time. Budget: at most ${SEARCH_BUDGET} search calls total.
+
+For each real candidate you find, write a grounded description of what you actually found: its real described props/structure/functionality, not just marketing copy, since a later step will score requirements against this description alone and cannot re-search. Be specific enough that someone reading only your description (never seeing the original page) could judge whether each checklist item is met.
+
+If search returns zero real candidates -- not just weak matches, but nothing relevant at all -- return an empty candidates array. Do not fabricate a candidate to avoid an empty result.
+
+Respond with ONLY a JSON object, no prose before or after, no markdown code fences, matching this exact shape:
+{ "candidates": [ { "source": "shadcn/ui | 21st.dev", "name": "string", "url": "string or null", "description": "string, grounded in what you actually found", "install_command": "string or null" } ] }`;
+export async function searchCandidates(input, requirements) {
+    const userMessage = `component_need: ${input.component_need}
+domain: ${input.domain}
+framework: ${input.framework}
+existing_stack: ${input.existing_stack ?? "(not specified)"}
+requirements checklist (for search targeting only, do not score against it here):
+${requirements.map((r, i) => `${i + 1}. ${r}`).join("\n")}`;
+    const data = await callAnthropic({
+        systemPrompt: SEARCH_SYSTEM_PROMPT,
+        userMessage,
+        maxTokens: 8192, // matches score.ts's reasoning: candidate write-ups can run long
+        tools: [{ type: "web_search_20250305", name: "web_search", max_uses: SEARCH_BUDGET }],
+    });
+    const searchCalls = searchCallDiagnostics(data);
+    if (data.stop_reason === "max_tokens") {
+        throw new Error("Search stage response was truncated (max_tokens) before finishing its JSON output.");
+    }
+    const parsed = parseJsonResponse(data);
+    if (!parsed.ok) {
+        throw new Error(`Search stage did not return valid JSON: ${parsed.raw.slice(0, 200)}`);
+    }
+    return { candidates: Array.isArray(parsed.value.candidates) ? parsed.value.candidates : [], diagnostics: { searchCalls } };
+}

package/dist/staged/types.js

@@ -0,0 +1,7 @@
+// Shared types for the staged (extract / search / score) pipeline.
+//
+// This is Phase 2 of validation-plan-staged-pipeline.md: an experimental,
+// standalone alternative to the bundled single-call pipeline in
+// src/index.ts, built to be compared against it in Phase 3 -- not (yet)
+// the production path. Nothing here is wired into the shipped MCP server.
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pattern-mcp",
-  "version": "0.1.1",
-  "description": "MCP tool that judges whether a UI component need should be met with an existing shadcn/21st.dev component or requires a custom build, using field/requirement coverage scored against real component code.",
+  "version": "0.3.0",
+  "description": "MCP tool that judges whether a UI component need should be met with an existing shadcn/ui, 21st.dev, or ReUI component or requires a custom build, using field/requirement coverage scored against real component code.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {