@expressivecss/mcp-server 0.2.1 → 0.3.0

package/server.js

@@ -7,8 +7,9 @@ import { createHash, randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { JSDOM } from 'jsdom';
 import * as z from 'zod/v4';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { resolveExpressiveVersion } from './scripts/resolve-version.mjs';
 
 const SERVER_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -18,12 +19,23 @@ const SERVER_VERSION = JSON.parse(readFileSync(path.join(SERVER_DIR, 'package.js
 const CAPABILITIES_BY_SLUG = new Map(CAPABILITY_ROADMAP.entries.map((entry) => [entry.slug, entry]));
 const COMPONENT_DECISIONS_BY_SLUG = new Map(COMPONENT_DECISIONS.components.map((entry) => [entry.slug, entry]));
 const DEFAULT_MAX_COMPONENT_RESPONSE_CHARS = 24_000;
+const GUIDANCE_TOOLS = new Set(['setup_expert', 'creative_director', 'page_architect', 'page_arcjitect', 'component_syntax_expert', 'component_catalog']);
+const RESPONSE_BUDGET_SETTING = 'EXPRESSIVECSS_MCP_MAX_RESPONSE_BYTES';
+function configuredResponseBudget(value = '65536') {
+  if (!/^\d+$/u.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1) {
+    throw new Error(`${RESPONSE_BUDGET_SETTING} must be a positive safe integer in decimal bytes.`);
+  }
+  return Number(value);
+}
 const DEFAULT_QA_MAX_FILES = 300;
 const DEFAULT_QA_MAX_MB = 2;
 const DEFAULT_QA_MAX_TOTAL_MB = 16;
 const MAX_STATIC_ISSUES = 200;
 const MAX_STATIC_ISSUES_PER_REQUEST = 1_000;
 const MAX_STATIC_MARKUP_DELIMITERS = 4_000;
+// Source locations make parse5 copy a parent's children for each text run, so the cost grows with
+// characters times tags. Past this product, semantics findings report 1:1 to stay within the budget.
+const MAX_LOCATED_MARKUP_WORK = 100_000_000;
 const STATIC_INSPECTION_TIMEOUT_MS = 5_000;
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_PROJECT_ROOT_CHARS = 4_096;
@@ -61,6 +73,7 @@ function configuredScripts(value) {
 }
 
 const SETTINGS = {
+  maxResponseBytes: configuredResponseBudget(process.env[RESPONSE_BUDGET_SETTING]),
   maxComponentResponseChars: Number(process.env.EXPRESSIVECSS_MCP_MAX_COMPONENT_RESPONSE_CHARS || DEFAULT_MAX_COMPONENT_RESPONSE_CHARS),
   maxComponentSkips: Number(process.env.EXPRESSIVECSS_MCP_MAX_COMPONENT_SKIPS || 7),
   qaMaxFiles: Number(process.env.EXPRESSIVECSS_MCP_QA_MAX_FILES || DEFAULT_QA_MAX_FILES),
@@ -96,19 +109,19 @@ const LegacyPatternList = [
   {
     id: 'legacy-nav-wrapper',
     severity: 'high',
-    description: '`.nav-wrapper` is legacy Materialize structure; use ExpressiveCSS nav components directly.',
+    description: '`.nav-wrapper` is retired markup structure; use ExpressiveCSS nav components directly.',
     pattern: /\bnav-wrapper\b/g,
   },
   {
     id: 'legacy-brand-logo',
     severity: 'medium',
-    description: '`.brand-logo` is Materialize-era naming; prefer native layout semantics in ExpressiveCSS pages.',
+    description: '`.brand-logo` is retired naming; prefer native layout semantics in ExpressiveCSS pages.',
     pattern: /\bbrand-logo\b/g,
   },
   {
     id: 'legacy-lever',
     severity: 'medium',
-    description: '`.lever` is a Materialize switch token, replace with Expressive switches per component guide.',
+    description: '`.lever` is a retired switch token, replace with Expressive switches per component guide.',
     pattern: /\blever\b/g,
   },
   {
@@ -167,7 +180,11 @@ const TOOL_DESCRIPTIONS = {
   },
   component_syntax_expert: {
     stage: 'Component Syntax Expert',
-    description: 'Return component syntax and constraints, plus scoped Material capability evidence. Request typography, shape, or motion through foundations.',
+    description: 'Return complete component rules with detailed syntax by default. Select compact detail to omit prose/examples, includeCapabilities to override component capability detail, sections for documented options/methods, or foundations for typography, shape, or motion. Intentional omissions are disclosed.',
+  },
+  component_catalog: {
+    stage: 'Component Catalogue',
+    description: 'List or search bundled components by name, alias or compact description. Search returns bounded, labelled matches; results identify the bundled snapshot and optionally check target-project compatibility.',
   },
   quality_inspector: {
     stage: 'Quality Inspector',
@@ -209,9 +226,19 @@ const pageArchitectSchema = {
 
 const syntaxSchema = {
   projectRoot: z.string().max(MAX_PROJECT_ROOT_CHARS).optional(),
+  detail: z.enum(['compact', 'detailed']).default('detailed'),
+  includeCapabilities: z.boolean().optional(),
   components: z.array(z.string().max(MAX_COMPONENT_NAME_CHARS)).max(12).default([]),
   foundations: z.array(z.enum(['typography', 'shape', 'motion'])).max(3).default([]),
+  sections: z.array(z.enum(['options', 'methods'])).max(2).refine((sections) => new Set(sections).size === sections.length, 'Request each section at most once').default([]),
+  workflowId: z.string().max(MAX_WORKFLOW_ID_CHARS).optional(),
+};
+
+const catalogSchema = {
+  projectRoot: z.string().max(MAX_PROJECT_ROOT_CHARS).optional(),
   workflowId: z.string().max(MAX_WORKFLOW_ID_CHARS).optional(),
+  query: z.string().max(256).trim().min(1).optional(),
+  limit: z.number().int().min(1).max(50).optional(),
 };
 
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
@@ -234,6 +261,40 @@ const qualityOutputSchema = stageOutputSchema.extend({
   status: z.enum(['pass', 'warn', 'blocked', 'needs_fix']),
   inspectionEvidence: inspectionEvidenceSchema.optional(), // Disabled tools return the shared blocked envelope.
 });
+const retryRequestSchema = z.discriminatedUnion('name', [
+  ['setup_expert', setupSchema], ['creative_director', creativeSchema],
+  ['page_architect', pageArchitectSchema], ['page_arcjitect', pageArchitectSchema],
+  ['component_syntax_expert', syntaxSchema], ['component_catalog', catalogSchema],
+].map(([name, schema]) => z.object({ name: z.literal(name), arguments: z.object(schema).strict() })));
+const responseBudgetSchema = z.object({
+  maxBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  delivery: z.enum(['complete', 'partial', 'error']),
+  omissions: z.array(z.object({
+    unit: z.enum(['field', 'component', 'foundation', 'entry', 'suggestion', 'architecture', 'request']),
+    index: z.number().int().nonnegative().optional(),
+    requested: z.string().optional(), slug: z.string().optional(),
+    field: z.enum(['contract', 'syntax', 'capability', 'options', 'methods']).optional(),
+    reason: z.literal('byte-budget'),
+    recovery: z.number().int().nonnegative(),
+  })),
+  recoveries: z.array(z.discriminatedUnion('action', [
+    z.object({ action: z.literal('retry'), request: retryRequestSchema }),
+    z.object({ action: z.literal('increase-budget'), configuration: z.literal(RESPONSE_BUDGET_SETTING) }),
+  ])),
+});
+const guidanceOutputSchema = stageOutputSchema.extend({ responseBudget: responseBudgetSchema });
+const syntaxOutputSchema = guidanceOutputSchema.extend({
+  // Disabled tools return only the shared blocked envelope.
+  detail: z.enum(['compact', 'detailed']).optional(),
+  includeCapabilities: z.boolean().optional(),
+  found: z.array(z.looseObject({
+    requestIndex: z.number().int().nonnegative(),
+    omittedFields: z.array(z.object({
+      field: z.enum(['contract', 'syntax', 'options', 'methods', 'capability']),
+      reason: z.enum(['compact-detail', 'not-requested', 'length-limit', 'byte-budget']),
+    })),
+  })).optional(),
+});
 const readAnnotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 
 const inspectSchema = {
@@ -285,13 +346,27 @@ function normalizeForMatch(value) {
 
 function extractSection(text, heading) {
   const marker = `#### ${heading}`;
-  const start = text.indexOf(marker);
-  if (start === -1) {
-    return '';
+  const lines = text.split('\n');
+  let start = -1;
+  let fence = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const delimiter = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/u);
+    if (fence) {
+      if (delimiter && delimiter[1][0] === fence[0] && delimiter[1].length >= fence.length && !delimiter[2].trim()) fence = null;
+      continue;
+    }
+    if (delimiter) {
+      fence = delimiter[1];
+      continue;
+    }
+    if (start === -1) {
+      if (line.trim() === marker) start = index + 1;
+    } else if (/^ {0,3}#{1,4}(?:\s|$)/u.test(line)) {
+      return lines.slice(start, index).join('\n').trim();
+    }
   }
-  const body = text.slice(start + marker.length);
-  const next = body.indexOf('\n#### ');
-  return (next === -1 ? body : body.slice(0, next)).trim();
+  return start === -1 ? '' : lines.slice(start).join('\n').trim();
 }
 
 function extractTitle(text) {
@@ -328,16 +403,116 @@ function clampText(input, maxChars) {
   return `${text.slice(0, Math.max(0, maxChars - 40))}…(truncated)`;
 }
 
-function toToolResult(payload) {
+function serializeToolResult(payload) {
   return {
     content: [{
       type: 'text',
-      text: JSON.stringify(payload, null, 2),
+      text: JSON.stringify(payload, null, GUIDANCE_TOOLS.has(payload.stage) ? undefined : 2),
     }],
     structuredContent: payload,
+    ...(payload.responseBudget?.delivery === 'error' ? { isError: true } : {}),
   };
 }
 
+function toToolResult(payload, args = {}, guidanceContext) {
+  const result = () => serializeToolResult(payload);
+  if (!GUIDANCE_TOOLS.has(payload.stage)) return result();
+  payload.responseBudget = { maxBytes: SETTINGS.maxResponseBytes, delivery: 'complete', omissions: [], recoveries: [] };
+  const fits = () => Buffer.byteLength(JSON.stringify(result()), 'utf8') <= SETTINGS.maxResponseBytes;
+  if (fits()) return result();
+
+  const original = structuredClone(payload);
+  const context = { workflowId: payload.workflowId, ...(args.projectRoot === undefined ? {} : { projectRoot: args.projectRoot }) };
+  const increase = { action: 'increase-budget', configuration: RESPONSE_BUDGET_SETTING };
+  const omit = (identity, recovery) => {
+    const budget = payload.responseBudget;
+    // Share recovery records, especially operator-increase advice, to bound their overhead.
+    const key = JSON.stringify(recovery);
+    let index = budget.recoveries.findIndex((entry) => JSON.stringify(entry) === key);
+    if (index < 0) index = budget.recoveries.push(recovery) - 1;
+    budget.omissions.push({ ...identity, reason: 'byte-budget', recovery: index });
+    budget.delivery = recovery.action === 'increase-budget' ? 'error' : budget.delivery === 'error' ? 'error' : 'partial';
+    payload.status = original.status === 'blocked' || budget.delivery === 'error' ? 'blocked' : 'partial';
+    payload.coverageStatus = budget.delivery === 'error' ? 'response-budget-error' : 'partial-response-budget';
+  };
+  const retry = (arguments_) => ({ action: 'retry', request: retryRequestSchema.parse({ name: payload.stage, arguments: {
+    // Catalogue retrieval has no workflow state. Preserve its explicit target without
+    // repeating an optional correlation ID for every individually recoverable entry.
+    ...(payload.stage === 'component_catalog' ? args.projectRoot === undefined ? {} : { projectRoot: args.projectRoot } : context),
+    ...arguments_,
+  } }) });
+  const recoveryResultFits = (candidate) => {
+    candidate.responseBudget = { maxBytes: SETTINGS.maxResponseBytes, delivery: 'complete', omissions: [], recoveries: [] };
+    return Buffer.byteLength(JSON.stringify(serializeToolResult(candidate)), 'utf8') <= SETTINGS.maxResponseBytes;
+  };
+
+  if (payload.stage === 'component_syntax_expert' && payload.found) {
+    const components = payload.found.map((entry, index) => ({ entry, index: entry.requestIndex ?? index }));
+    const syntaxRecovery = (entry, field) => {
+      const arguments_ = { components: [entry.slug], detail: field === 'contract' || field === 'syntax' ? 'detailed' : 'compact', includeCapabilities: field === 'capability', sections: ['options', 'methods'].includes(field) ? [field] : [] };
+      const recovery = retry(arguments_);
+      const candidate = buildSyntaxPayload(guidanceContext.catalog, guidanceContext.version, recovery.request.arguments);
+      return recoveryResultFits(candidate) ? recovery : increase;
+    };
+    for (const field of ['capability', 'contract', 'syntax', 'options', 'methods']) {
+      for (const { entry, index } of [...components].reverse()) {
+        if (!Object.hasOwn(entry, field)) continue;
+        const recovery = syntaxRecovery(original.found.find((row) => row.requestIndex === index) ?? entry, field);
+        delete entry[field];
+        entry.omittedFields = entry.omittedFields.filter((row) => row.field !== field);
+        entry.omittedFields.push({ field, reason: 'byte-budget' });
+        entry.omittedFields.sort((a, b) => ['contract', 'syntax', 'options', 'methods', 'capability'].indexOf(a.field) - ['contract', 'syntax', 'options', 'methods', 'capability'].indexOf(b.field));
+        omit({ unit: 'field', index, requested: args.components?.[index] ?? entry.slug, slug: entry.slug, field }, recovery);
+        if (fits()) return result();
+      }
+    }
+    while (payload.found.length) {
+      const entry = payload.found.pop();
+      const index = entry.requestIndex;
+      omit({ unit: 'component', index, requested: args.components?.[index] ?? entry.slug, slug: entry.slug }, syntaxRecovery(original.found.find((row) => row.requestIndex === index), undefined));
+      payload.foundCount = payload.found.length;
+      if (fits()) return result();
+    }
+    while (payload.foundations.length) {
+      const index = payload.foundations.length - 1;
+      const entry = payload.foundations.pop();
+      let recovery = retry({ components: [], foundations: [args.foundations[index]], detail: 'compact', includeCapabilities: false });
+      const candidate = buildSyntaxPayload(guidanceContext.catalog, guidanceContext.version, recovery.request.arguments);
+      if (!recoveryResultFits(candidate)) recovery = increase;
+      omit({ unit: 'foundation', index, requested: args.foundations[index], slug: entry.slug }, recovery);
+      if (fits()) return result();
+    }
+  } else if (payload.stage === 'component_catalog' || payload.stage === 'creative_director') {
+    const field = payload.stage === 'component_catalog' ? 'entries' : 'suggestions';
+    while (payload[field].length) {
+      const index = payload[field].length - 1;
+      const entry = payload[field].pop();
+      const goal = entry.selectionSource === 'native-pattern' ? 'Choose persistent nonblocking inline feedback.' : `Choose ${entry.slug} for this interface.`;
+      let recovery = field === 'entries' ? retry({ query: entry.slug, limit: 1 }) : retry({ goal, maxSuggestions: 1 });
+      const candidate = (field === 'entries' ? buildCatalogPayload : buildCreativePayload)(guidanceContext.catalog, guidanceContext.version, recovery.request.arguments);
+      if (candidate[field][0]?.slug !== entry.slug || !recoveryResultFits(candidate)) recovery = increase;
+      omit({ unit: field === 'entries' ? 'entry' : 'suggestion', ...(field === 'entries' ? {} : { index }), slug: entry.slug }, recovery);
+      payload.count = payload[field].length;
+      if (field === 'suggestions') { payload.omittedCount += 1; payload.truncated = true; }
+      if (fits()) return result();
+    }
+  } else if (payload.architecture) {
+    payload.architecture = null;
+    omit({ unit: 'architecture' }, increase);
+    if (fits()) return result();
+  }
+
+  // No guidance is delivered by this error. Preserve actual checks and compatibility evidence.
+  const essential = ['workflowId', 'stage', 'checksPerformed', 'evidenceSources', 'uncheckedAreas', 'blockedChecks', 'contractCompatibility', 'contractProvenance', 'contractProvenanceDetails', 'contractVersion', 'sourceHash', 'guideSource', 'capabilityEvidence', 'skipped'];
+  payload = Object.fromEntries(essential.filter((key) => Object.hasOwn(original, key)).map((key) => [key, original[key]]));
+  payload.status = 'blocked';
+  payload.coverageStatus = 'response-budget-error';
+  payload.message = 'No requested guidance was delivered. Increase the operator response budget and repeat the request.';
+  payload.responseBudget = { maxBytes: SETTINGS.maxResponseBytes, delivery: 'error', omissions: [{ unit: 'request', reason: 'byte-budget', recovery: 0 }], recoveries: [increase] };
+  // The final transport check converts this into a protocol error if even evidence cannot fit.
+  return result();
+}
+
 function buildStagePayload(tool, result, workflowId) {
   return {
     workflowId: workflowId || randomUUID().slice(0, 12),
@@ -400,6 +575,8 @@ function parseGuide(file, content) {
   const contract = extractSection(content, 'Contract');
   const syntax = extractSection(content, 'Syntax');
   const rules = extractRules(extractSection(content, 'Rules'));
+  const options = extractSection(content, 'Options');
+  const methods = extractSection(content, 'Methods');
   const syntaxCode = extractFirstCodeBlock(syntax);
   const syntaxLangMatch = syntax.match(/```\s*([a-z0-9+.-]+)/i);
   const syntaxLanguage = syntaxLangMatch ? syntaxLangMatch[1].toLowerCase() : 'html';
@@ -410,15 +587,17 @@ function parseGuide(file, content) {
     file,
     slug,
     title,
-    contract: clampText(contract, 1_000),
+    contract,
     syntax: {
       language: syntaxLanguage,
-      code: clampText(syntaxCode, Math.max(1_200, Math.floor(SETTINGS.maxComponentResponseChars / 2))),
+      code: syntaxCode,
     },
     rules: rules.length ? rules : [
       'Follow the component contract in the full documentation before adding optional attributes.',
       'Keep runtime-owned state in framework initialization, not in static markup values.',
     ],
+    options: options || null,
+    methods: methods || null,
     sourceUrl: docsMatch ? docsMatch[1] : null,
     astroSource: repoMatch ? `https://github.com/BaezFJ/ExpressiveCSS/blob/master/docs/src/pages/${repoMatch[1]}.astro` : null,
     text: `${title}\n${contract}\n${rules.join('\n')}`.toLowerCase(),
@@ -594,13 +773,13 @@ async function loadGuideCatalog(projectRoot) {
 
   let provenance;
 
-  const guideDir = await resolveGuideDirectory(projectRoot);
+  const guideDir = projectRoot === undefined ? null : await resolveGuideDirectory(projectRoot);
   const dirStat = guideDir ? await stat(guideDir).catch(() => null) : null;
-  const projectResolution = await resolveExpressiveVersion({
+  const projectResolution = projectRoot === undefined ? null : await resolveExpressiveVersion({
     projectRoot,
     contractVersion: bundledGuideCache.frameworkVersion,
   });
-  const isFrameworkSource = projectResolution.resolutionSource === 'framework-source';
+  const isFrameworkSource = projectResolution?.resolutionSource === 'framework-source';
   if (dirStat?.isDirectory()) {
     const localContractPath = path.join(projectRoot, 'skills', 'expressivecss', 'references', 'contract.json');
     const localContractRead = await readInspectionFile(
@@ -647,7 +826,7 @@ async function loadGuideCatalog(projectRoot) {
 
   return {
     generatedAt: new Date().toISOString(),
-    projectRoot: path.resolve(projectRoot),
+    projectRoot: projectRoot === undefined ? null : path.resolve(projectRoot),
     frameworkVersion: bundledGuideCache.frameworkVersion,
     sourceHash: bundledGuideCache.sourceHash,
     provenance,
@@ -879,7 +1058,15 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
   const { semantics, frameworkVersion } = loadSemanticsContract();
   if (maxIssues <= 0) return markInspectionTruncated([], 'issue limit reached');
   if (markupStructureExceedsLimit(snippet)) return markInspectionTruncated([], 'markup structure limit reached');
-  const { document } = new JSDOM(`<!doctype html><body>${snippet}</body>`).window;
+  const prefix = '<!doctype html><body>';
+  const includeNodeLocations = snippet.length * (snippet.split('<').length - 1) <= MAX_LOCATED_MARKUP_WORK;
+  const dom = new JSDOM(`${prefix}${snippet}</body>`, { includeNodeLocations });
+  const { document } = dom.window;
+  // Elements the parser creates without a start tag have no source offset, so they report the start.
+  const locate = (element) => {
+    const offset = includeNodeLocations ? dom.nodeLocation(element)?.startOffset ?? -1 : -1;
+    return offset >= prefix.length ? lineForMatch(snippet, offset - prefix.length) : { line: 1, column: 1 };
+  };
   const issues = [];
 
   for (const rule of enforcedSemanticRules(semantics)) {
@@ -890,7 +1077,7 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
       for (const element of hits) {
         const stop = inspectionStopReason(issues, maxIssues, deadline);
         if (stop) return markInspectionTruncated(issues, stop);
-        issues.push(semanticIssue(rule, element, frameworkVersion));
+        issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
       }
     } else if (rule.kind === 'require-attr') {
       for (const element of hits) {
@@ -899,7 +1086,7 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
         const value = element.getAttribute(rule.attr);
         const valid = rule.equals ? value === rule.equals : value !== null && value !== '';
         if (!valid) {
-          issues.push(semanticIssue(rule, element, frameworkVersion));
+          issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
         }
       }
     } else if (rule.kind === 'require-accessible-name') {
@@ -907,7 +1094,7 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
         const stop = inspectionStopReason(issues, maxIssues, deadline);
         if (stop) return markInspectionTruncated(issues, stop);
         if (!accessibleName(element, document)) {
-          issues.push(semanticIssue(rule, element, frameworkVersion));
+          issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
         }
       }
     }
@@ -928,7 +1115,7 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
         component: 'landmarks',
         frameworkVersion,
         rule: `Navigation landmarks on one page need distinct names; "${name}" is repeated.`,
-        location: { line: 1, column: 1 },
+        location: locate(nav),
         snippet: nav.outerHTML.slice(0, 140),
       });
     }
@@ -938,14 +1125,14 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
   return issues;
 }
 
-function semanticIssue(rule, element, frameworkVersion) {
+function semanticIssue(rule, element, frameworkVersion, location) {
   return {
     id: rule.id,
     severity: 'high',
     component: rule.component,
     frameworkVersion,
     rule: rule.message,
-    location: { line: 1, column: 1 },
+    location,
     snippet: element.outerHTML.slice(0, 140),
   };
 }
@@ -1267,19 +1454,29 @@ function buildPageArchitecture(catalog, pageGoal, components = [], viewportTarge
   };
 }
 
-function summarizeGuide(guide) {
+function summarizeGuide(guide, { sections, detail, includeCapabilities }) {
   return {
     file: guide.file,
     slug: guide.slug,
     title: guide.title,
     source: guide.sourceUrl,
     docs: guide.astroSource,
-    contract: clampText(guide.contract, 900),
-    syntax: {
-      language: guide.syntax.language,
-      example: clampText(guide.syntax.code, 3_000),
-    },
-    rules: guide.rules.slice(0, 8),
+    ...(detail === 'detailed' ? {
+      contract: clampText(guide.contract, 900),
+      syntax: {
+        language: guide.syntax.language,
+        example: guide.syntax.code,
+      },
+    } : {}),
+    rules: guide.rules,
+    ...(sections.includes('options') ? { options: { status: guide.options ? 'documented' : 'absent', markdown: guide.options } } : {}),
+    ...(sections.includes('methods') ? { methods: { status: guide.methods ? 'documented' : 'absent', markdown: guide.methods } } : {}),
+    omittedFields: [
+      ...(detail === 'compact' ? [{ field: 'contract', reason: 'compact-detail' }, { field: 'syntax', reason: 'compact-detail' }] : []),
+      ...['options', 'methods'].filter((field) => !sections.includes(field)).map((field) => ({ field, reason: 'not-requested' })),
+      ...(!includeCapabilities ? [{ field: 'capability', reason: 'not-requested' }] : []),
+      ...(detail === 'detailed' && guide.contract.length > 900 ? [{ field: 'contract', reason: 'length-limit' }] : []),
+    ].sort((a, b) => ['contract', 'syntax', 'options', 'methods', 'capability'].indexOf(a.field) - ['contract', 'syntax', 'options', 'methods', 'capability'].indexOf(b.field)),
   };
 }
 
@@ -1684,6 +1881,7 @@ const rulesSchemaParsed = z.object(rulesSchema);
 const creativeSchemaParsed = z.object(creativeSchema);
 const architectSchemaParsed = z.object(pageArchitectSchema);
 const syntaxSchemaParsed = z.object(syntaxSchema).refine((value) => value.components.length + value.foundations.length > 0, 'Request at least one component or foundation');
+const catalogSchemaParsed = z.object(catalogSchema);
 const qualitySchemaParsed = z.object(inspectSchema);
 
 async function setupExpertHandler(args) {
@@ -1803,7 +2001,7 @@ async function setupExpertHandler(args) {
     workflowId,
   );
 
-  return toToolResult(payload);
+  return toToolResult(payload, { ...parsed, projectRoot });
 }
 
 async function rulesEnforcerHandler(args) {
@@ -1920,7 +2118,7 @@ async function rulesEnforcerHandler(args) {
       ],
       guidance: {
         alwaysPrefer: 'Read component guides before adding structure.',
-        compatibility: 'Avoid Materialize-era selectors and prefer source-of-truth component contracts.',
+        compatibility: 'Avoid retired selectors and prefer source-of-truth component contracts.',
       },
     },
     workflowId,
@@ -1935,10 +2133,14 @@ async function creativeDirectorHandler(args) {
   }
 
   const parsed = creativeSchemaParsed.parse(args);
-  const workflowId = parsed.workflowId || randomUUID();
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
   const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  return toToolResult(buildCreativePayload(catalog, version, parsed), { ...parsed, projectRoot }, { catalog, version });
+}
+
+function buildCreativePayload(catalog, version, parsed) {
+  const workflowId = parsed.workflowId || randomUUID();
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
   const contractSafe = version.status === 'match' && !provenanceBlock;
 
@@ -1948,7 +2150,7 @@ async function creativeDirectorHandler(args) {
     : { suggestions: [], truncated: false, omittedCount: 0 };
   const { suggestions, truncated, omittedCount } = candidateResult;
 
-  const payload = buildStagePayload(
+  return buildStagePayload(
     'creative_director',
     {
       goal: parsed.goal,
@@ -1986,8 +2188,6 @@ async function creativeDirectorHandler(args) {
     },
     workflowId,
   );
-
-  return toToolResult(payload);
 }
 
 async function pageArchitectHandler(args, stage = 'page_architect') {
@@ -2061,7 +2261,7 @@ async function pageArchitectHandler(args, stage = 'page_architect') {
     workflowId,
   );
 
-  return toToolResult(payload);
+  return toToolResult(payload, { ...parsed, projectRoot });
 }
 
 async function componentSyntaxExpertHandler(args) {
@@ -2070,10 +2270,15 @@ async function componentSyntaxExpertHandler(args) {
   }
 
   const parsed = syntaxSchemaParsed.parse(args);
-  const workflowId = parsed.workflowId || randomUUID();
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
   const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  return toToolResult(buildSyntaxPayload(catalog, version, parsed), { ...parsed, projectRoot }, { catalog, version });
+}
+
+function buildSyntaxPayload(catalog, version, parsed) {
+  const includeCapabilities = parsed.includeCapabilities ?? parsed.detail === 'detailed';
+  const workflowId = parsed.workflowId || randomUUID();
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
 
   const capabilitySafe = version.status === 'match' && !provenanceBlock && CAPABILITY_ROADMAP.frameworkVersion === catalog.frameworkVersion;
@@ -2081,7 +2286,7 @@ async function componentSyntaxExpertHandler(args) {
   const found = [];
   const missing = [];
 
-  for (const component of requested) {
+  for (const [requestIndex, component] of requested.entries()) {
     const guide = findGuideByName(catalog, component, false);
     if (!guide) {
       const skipLimit = Math.min(Math.max(SETTINGS.maxComponentSkips, 1), 20);
@@ -2090,13 +2295,19 @@ async function componentSyntaxExpertHandler(args) {
         nearest: nearestMatches(catalog, component, skipLimit).map((row) => row.slug),
       });
     } else {
-      found.push({ ...summarizeGuide(guide), capability: capabilitySafe ? CAPABILITIES_BY_SLUG.get(guide.slug) ?? null : null });
+      found.push({
+        requestIndex,
+        ...summarizeGuide(guide, { ...parsed, includeCapabilities }),
+        ...(includeCapabilities ? { capability: capabilitySafe ? CAPABILITIES_BY_SLUG.get(guide.slug) ?? null : null } : {}),
+      });
     }
   }
 
-  const payload = buildStagePayload(
+  return buildStagePayload(
     'component_syntax_expert',
     {
+      detail: parsed.detail,
+      includeCapabilities,
       foundCount: found.length,
       foundations: capabilitySafe ? parsed.foundations.map((slug) => CAPABILITIES_BY_SLUG.get(slug)) : [],
       capabilityEvidence: { status: capabilitySafe ? 'bundled-review-snapshot' : 'blocked', basis: CAPABILITY_ROADMAP.basis, browserRun: capabilitySafe ? CAPABILITY_ROADMAP.browserRun : null },
@@ -2131,8 +2342,74 @@ async function componentSyntaxExpertHandler(args) {
     },
     workflowId,
   );
+}
 
-  return toToolResult(payload);
+async function componentCatalogHandler(args) {
+  const parsed = catalogSchemaParsed.parse(args);
+  const projectRoot = parsed.projectRoot === undefined ? undefined : path.resolve(parsed.projectRoot);
+  const catalog = await loadGuideCatalog(projectRoot);
+  const version = projectRoot === undefined ? null : await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  return toToolResult(buildCatalogPayload(catalog, version, parsed), parsed, { catalog, version });
+}
+
+function buildCatalogPayload(catalog, version, parsed) {
+  const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
+  let entries = [...catalog.components.values()].map((guide) => {
+    const decision = COMPONENT_DECISIONS_BY_SLUG.get(guide.slug);
+    return {
+      slug: guide.slug,
+      title: guide.title,
+      description: [...(decision?.useWhen ?? []), ...(decision?.jobs ?? [])].find((value) => typeof value === 'string' && value.trim()) ?? null,
+      aliases: decision?.aliases ?? [],
+      runtime: decision?.runtime ?? null,
+      docs: guide.sourceUrl,
+    };
+  }).sort((a, b) => a.slug.localeCompare(b.slug));
+
+  let search = {};
+  if (parsed.query !== undefined) {
+    const query = normalizeForMatch(parsed.query);
+    const tokens = query.split('-').filter(Boolean);
+    const matchOrder = ['exact-name', 'exact-alias', 'heuristic'];
+    entries = entries.flatMap((entry) => {
+      const names = [entry.slug, entry.title].map(normalizeForMatch);
+      const aliases = entry.aliases.map(normalizeForMatch);
+      const fields = [...names, ...aliases, normalizeForMatch(entry.description)];
+      const matchType = query && names.includes(query) ? 'exact-name'
+        : query && aliases.includes(query) ? 'exact-alias'
+          : tokens.length && tokens.every((token) => fields.some((field) => field.includes(token))) ? 'heuristic' : null;
+      return matchType ? [{ ...entry, matchType }] : [];
+    }).sort((a, b) => matchOrder.indexOf(a.matchType) - matchOrder.indexOf(b.matchType) || a.slug.localeCompare(b.slug));
+    const totalMatches = entries.length;
+    const limit = parsed.limit ?? 10;
+    entries = entries.slice(0, limit);
+    const omittedCount = totalMatches - entries.length;
+    search = { query: parsed.query, limit, totalMatches, omittedCount, truncated: omittedCount > 0 };
+  }
+
+  return buildStagePayload('component_catalog', {
+    entries,
+    count: entries.length,
+    ...search,
+    contractVersion: catalog.frameworkVersion,
+    sourceHash: catalog.sourceHash,
+    guideSource: catalog.guideSource,
+    status: (!version || version.status === 'match') && !provenanceBlock ? 'available' : 'blocked',
+    checksPerformed: [parsed.query === undefined ? 'bundled component catalogue listing' : 'bundled component catalogue search', ...(version ? ['target contract resolution', 'contract provenance validation'] : [])],
+    evidenceSources: ['bundled:component-guides.json', 'bundled:component-decisions.json', 'bundled:contract.json', ...(version ? [version.resolutionSource] : [])],
+    uncheckedAreas: [
+      ...(!version ? ['target-project compatibility', 'target-project provenance'] : []),
+      'rendered component behavior', 'visual hierarchy', 'responsive composition', 'keyboard and assistive-technology behavior',
+    ],
+    contractCompatibility: version?.status ?? 'unknown',
+    contractProvenance: catalog.provenance.status,
+    contractProvenanceDetails: catalog.provenance,
+    coverageStatus: parsed.query === undefined ? 'complete-bundled-catalogue' : search.truncated ? 'partial-search-results' : 'complete-search-results',
+    blockedChecks: [
+      ...(version && version.status !== 'match' ? ['target-version contract checks'] : []),
+      ...(provenanceBlock ? [provenanceBlock] : []),
+    ],
+  }, parsed.workflowId);
 }
 
 async function qualityInspectorHandler(args) {
@@ -2304,6 +2581,105 @@ async function qualityInspectorHandler(args) {
   return toToolResult(payload);
 }
 
+const COMPONENT_SECTIONS = ['contract', 'syntax', 'rules', 'options', 'methods'];
+
+function resourceRequiredBytes(result) {
+  // A retry's budget field can need more decimal digits. Include those bytes too.
+  const retry = structuredClone(result);
+  const payload = JSON.parse(retry.contents[0].text);
+  let requiredBytes = Buffer.byteLength(JSON.stringify(retry), 'utf8');
+  for (;;) {
+    payload.responseBudget.maxBytes = requiredBytes;
+    retry.contents[0].text = JSON.stringify(payload);
+    const measured = Buffer.byteLength(JSON.stringify(retry), 'utf8');
+    if (measured <= requiredBytes) return requiredBytes;
+    requiredBytes = measured;
+  }
+}
+
+function resourceBudgetError(uri, result, resources) {
+  const requiredBytes = resourceRequiredBytes(result);
+  const data = { uri, maxBytes: SETTINGS.maxResponseBytes, requiredBytes, setting: RESPONSE_BUDGET_SETTING };
+  if (!resources.sections.has(uri)) {
+    return {
+      code: -32001,
+      message: `Response budget cannot fit the complete catalogue resource. Increase ${RESPONSE_BUDGET_SETTING} to at least ${requiredBytes} and restart.`,
+      data,
+    };
+  }
+  // Recover a whole guide through the section URIs whose complete reads fit this budget.
+  const fits = (sectionUri) => Buffer.byteLength(JSON.stringify(resources.readers.get(sectionUri)()), 'utf8') <= SETTINGS.maxResponseBytes;
+  const sections = resources.sections.get(uri);
+  const recoveries = sections.length > 1 ? sections.filter(fits) : [];
+  return {
+    code: -32001,
+    message: `Response budget cannot fit the complete component resource. Read the listed section URIs or increase ${RESPONSE_BUDGET_SETTING} to at least ${requiredBytes} and restart.`,
+    data: {
+      ...data,
+      recoveries,
+      unrecoverableSections: sections.filter((sectionUri) => !recoveries.includes(sectionUri)).map((sectionUri) => sectionUri.slice(sectionUri.lastIndexOf('/') + 1)),
+    },
+  };
+}
+
+function bundledResources(catalog, catalogUri, catalogSnapshot) {
+  const base = catalogUri.replace('expressivecss://catalogue/', 'expressivecss://components/');
+  const jsonResource = (uri, payload) => () => ({
+    contents: [{
+      uri,
+      mimeType: 'application/json',
+      text: JSON.stringify({
+        ...payload,
+        responseBudget: { maxBytes: SETTINGS.maxResponseBytes, delivery: 'complete', omissions: [], recoveries: [] },
+      }),
+    }],
+  });
+  const readers = new Map([[catalogUri, jsonResource(catalogUri, { schemaVersion: 1, ...catalogSnapshot })]]);
+  // Whole-guide and section URIs map to the section URIs that can recover them.
+  const sections = new Map();
+  const guides = [];
+  const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
+  for (const guide of [...catalog.components.values()].sort((a, b) => a.slug.localeCompare(b.slug))) {
+    const uri = `${base}/${guide.slug}`;
+    const identity = {
+      schemaVersion: 1,
+      slug: guide.slug,
+      title: guide.title,
+      docs: guide.sourceUrl,
+      repositorySource: guide.astroSource,
+      contractVersion: catalog.frameworkVersion,
+      sourceHash: catalog.sourceHash,
+      guideSource: catalog.guideSource,
+    };
+    const fields = {
+      contract: guide.contract,
+      syntax: { language: guide.syntax.language, example: guide.syntax.code },
+      rules: guide.rules,
+      options: { status: guide.options ? 'documented' : 'absent', markdown: guide.options },
+      methods: { status: guide.methods ? 'documented' : 'absent', markdown: guide.methods },
+    };
+    const evidence = (coverageStatus) => ({
+      status: provenanceBlock ? 'blocked' : 'available',
+      checksPerformed: ['bundled component guide lookup'],
+      evidenceSources: [`${catalog.guideSource}:${guide.file}`, 'bundled:contract.json'],
+      uncheckedAreas: catalogSnapshot.uncheckedAreas,
+      contractCompatibility: 'unknown',
+      contractProvenance: catalog.provenance.status,
+      contractProvenanceDetails: catalog.provenance,
+      coverageStatus,
+      blockedChecks: provenanceBlock ? [provenanceBlock] : [],
+    });
+    readers.set(uri, jsonResource(uri, { ...identity, ...fields, ...evidence('complete-bundled-guide') }));
+    guides.push(guide);
+    sections.set(uri, COMPONENT_SECTIONS.map((name) => `${uri}/${name}`));
+    for (const name of COMPONENT_SECTIONS) {
+      readers.set(`${uri}/${name}`, jsonResource(`${uri}/${name}`, { ...identity, section: name, [name]: fields[name], ...evidence('complete-bundled-guide-section') }));
+      sections.set(`${uri}/${name}`, [`${uri}/${name}`]);
+    }
+  }
+  return { base, readers, sections, guides };
+}
+
 async function startServer() {
   const server = new McpServer(
     {
@@ -2318,9 +2694,9 @@ async function startServer() {
   );
 
   server.registerTool('setup_expert', {
-    description: TOOL_DESCRIPTIONS.setup_expert.description,
+    description: TOOL_DESCRIPTIONS.setup_expert.description + " Responses share the operator byte budget with explicit whole-unit omissions and recovery.",
     inputSchema: setupSchema,
-    outputSchema: stageOutputSchema,
+    outputSchema: guidanceOutputSchema,
     annotations: readAnnotations,
   }, setupExpertHandler);
 
@@ -2332,33 +2708,40 @@ async function startServer() {
   }, rulesEnforcerHandler);
 
   server.registerTool('creative_director', {
-    description: TOOL_DESCRIPTIONS.creative_director.description,
+    description: TOOL_DESCRIPTIONS.creative_director.description + " Responses share the operator byte budget with explicit whole-unit omissions and recovery.",
     inputSchema: creativeSchema,
-    outputSchema: stageOutputSchema,
+    outputSchema: guidanceOutputSchema,
     annotations: readAnnotations,
   }, creativeDirectorHandler);
 
   server.registerTool('page_architect', {
-    description: TOOL_DESCRIPTIONS.page_architect.description,
+    description: TOOL_DESCRIPTIONS.page_architect.description + " Responses share the operator byte budget with explicit whole-unit omissions and recovery.",
     inputSchema: pageArchitectSchema,
-    outputSchema: stageOutputSchema,
+    outputSchema: guidanceOutputSchema,
     annotations: readAnnotations,
   }, (args) => pageArchitectHandler(args, 'page_architect'));
 
   server.registerTool('page_arcjitect', {
-    description: TOOL_DESCRIPTIONS.page_arcjitect.description,
+    description: TOOL_DESCRIPTIONS.page_arcjitect.description + " Responses share the operator byte budget with explicit whole-unit omissions and recovery.",
     inputSchema: pageArchitectSchema,
-    outputSchema: stageOutputSchema,
+    outputSchema: guidanceOutputSchema,
     annotations: readAnnotations,
   }, (args) => pageArchitectHandler(args, 'page_arcjitect'));
 
   server.registerTool('component_syntax_expert', {
-    description: TOOL_DESCRIPTIONS.component_syntax_expert.description,
+    description: TOOL_DESCRIPTIONS.component_syntax_expert.description + " Responses share the operator byte budget with explicit whole-unit omissions and recovery.",
     inputSchema: syntaxSchema,
-    outputSchema: stageOutputSchema,
+    outputSchema: syntaxOutputSchema,
     annotations: readAnnotations,
   }, componentSyntaxExpertHandler);
 
+  server.registerTool('component_catalog', {
+    description: TOOL_DESCRIPTIONS.component_catalog.description + " Responses share the operator byte budget with explicit whole-unit omissions and recovery.",
+    inputSchema: catalogSchema,
+    outputSchema: guidanceOutputSchema,
+    annotations: readAnnotations,
+  }, componentCatalogHandler);
+
   server.registerTool('quality_inspector', {
     description: TOOL_DESCRIPTIONS.quality_inspector.description,
     inputSchema: inspectSchema,
@@ -2366,7 +2749,75 @@ async function startServer() {
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
   }, qualityInspectorHandler);
 
+  const catalog = await loadGuideCatalog(undefined);
+  const catalogUri = `expressivecss://catalogue/${encodeURIComponent(catalog.frameworkVersion)}/${catalog.sourceHash}`;
+  const { stage, workflowId, ...snapshot } = buildCatalogPayload(catalog, null, { workflowId: 'catalogue-resource' });
+  const resources = bundledResources(catalog, catalogUri, snapshot);
+  const readResource = async (uri) => {
+    const reader = resources.readers.get(uri);
+    if (!reader) throw new McpError(-32002, 'Resource not found. Use resources/list or resources/templates/list to discover the current bundled snapshot.');
+    return reader();
+  };
+  server.registerResource('component_catalog', catalogUri, {
+    title: 'ExpressiveCSS component catalogue',
+    description: 'Compact component metadata for the current bundled snapshot only. Consumer compatibility remains unchecked.',
+    mimeType: 'application/json',
+  }, () => readResource(catalogUri));
+  // Case-insensitive prefix completion over canonical names only; the SDK caps values at 100.
+  const startingWith = (names) => (value) => names.filter((name) => name.startsWith(value.toLowerCase()));
+  const slug = startingWith(resources.guides.map((guide) => guide.slug));
+  server.registerResource('component_guide', new ResourceTemplate(`${resources.base}/{slug}`, {
+    list: async () => ({
+      resources: resources.guides.map((guide) => ({ uri: `${resources.base}/${guide.slug}`, name: guide.slug, title: `ExpressiveCSS ${guide.title} guide` })),
+    }),
+    complete: { slug },
+  }), {
+    title: 'ExpressiveCSS component guide',
+    description: 'Complete contract, syntax, rules, Options and Methods for one component in the current bundled snapshot only. Use a canonical slug; consumer compatibility remains unchecked.',
+    mimeType: 'application/json',
+  }, (uri) => readResource(uri.href));
+  server.registerResource('component_guide_section', new ResourceTemplate(`${resources.base}/{slug}/{section}`, {
+    list: undefined,
+    complete: { slug, section: startingWith(COMPONENT_SECTIONS) },
+  }), {
+    title: 'ExpressiveCSS component guide section',
+    description: `One complete section of a component guide in the current bundled snapshot only. Sections: ${COMPONENT_SECTIONS.join(', ')}. Use a canonical slug; consumer compatibility remains unchecked.`,
+    mimeType: 'application/json',
+  }, (uri) => readResource(uri.href));
+  // SDK v1 normalizes URLs and uses -32602 for missing resources. Require an
+  // advertised identity verbatim and return the resource-not-found protocol code.
+  server.server.setRequestHandler(ReadResourceRequestSchema, async (request) => readResource(request.params.uri));
+
   const transport = new StdioServerTransport();
+  // Check the wire result after SDK error handling too. SDK exceptions otherwise become
+  // unbounded isError results, including validation errors before our handlers run.
+  const scopedRequests = new Map();
+  const start = transport.start.bind(transport);
+  const send = transport.send.bind(transport);
+  transport.start = async () => {
+    const receive = transport.onmessage;
+    transport.onmessage = (message, extra) => {
+      if (Object.hasOwn(message, 'id')) {
+        if (message.method === 'tools/call' && GUIDANCE_TOOLS.has(message.params?.name)) scopedRequests.set(message.id, 'tool');
+        if (message.method === 'resources/read') scopedRequests.set(message.id, { uri: message.params?.uri });
+      }
+      receive(message, extra);
+    };
+    await start();
+  };
+  transport.send = async (message, options) => {
+    const kind = scopedRequests.get(message.id);
+    scopedRequests.delete(message.id);
+    if (kind && Object.hasOwn(message, 'result')
+      && Buffer.byteLength(JSON.stringify(message.result), 'utf8') > SETTINGS.maxResponseBytes) {
+      const error = kind.uri ? resourceBudgetError(kind.uri, message.result, resources)
+        : { code: -32001, message: `Response budget cannot fit a truthful tool result. Increase ${RESPONSE_BUDGET_SETTING}.` };
+      message = { jsonrpc: '2.0', id: message.id, error };
+    }
+    await send(message, options);
+  };
+  const close = transport.close.bind(transport);
+  transport.close = async () => { try { await close(); } finally { scopedRequests.clear(); } };
   await server.connect(transport);
   console.error('ExpressiveCSS MCP server running on stdio transport.');
 }