@expressivecss/mcp-server 0.3.0 → 0.4.0

package/server.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { JSDOM } from 'jsdom';
+import { createRequire } from 'node:module';
 import * as z from 'zod/v4';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -62,6 +62,7 @@ function configuredCommandRoots(value) {
   return trimmed.split(path.delimiter).map((entry) => entry.trim()).filter(Boolean);
 }
 
+const PROJECT_ROOTS_SETTING = 'EXPRESSIVECSS_MCP_ALLOWED_PROJECT_ROOTS';
 const QUALITY_SCRIPTS = ['typecheck', 'test', 'verify:expressivecss'];
 // Trusted server configuration can only narrow the built-in list. Invalid input denies all.
 function configuredScripts(value) {
@@ -82,6 +83,8 @@ const SETTINGS = {
   commandTimeoutMs: Number(process.env.EXPRESSIVECSS_MCP_COMMAND_TIMEOUT_MS || DEFAULT_COMMAND_TIMEOUT_MS),
   allowedScripts: configuredScripts(process.env.EXPRESSIVECSS_MCP_ALLOWED_SCRIPTS),
   allowedCommandRoots: configuredCommandRoots(process.env.EXPRESSIVECSS_MCP_ALLOWED_COMMAND_ROOTS),
+  // Unset keeps every root open. A set but empty or invalid list denies every client-supplied root.
+  allowedProjectRoots: process.env[PROJECT_ROOTS_SETTING] === undefined ? null : configuredCommandRoots(process.env[PROJECT_ROOTS_SETTING]),
 };
 
 const SKIP_FLAGS = {
@@ -104,7 +107,7 @@ const LegacyPatternList = [
     id: 'legacy-card-content',
     severity: 'high',
     description: '`.card-content` was removed; use the component’s documented child structure.',
-    pattern: /\bcard-content\b/g,
+    pattern: /(?<![-\w])card-content(?![-\w])/g,
   },
   {
     id: 'legacy-nav-wrapper',
@@ -316,7 +319,29 @@ function parseCliProjectRoot() {
 }
 
 function resolveProjectRoot(projectRoot) {
-  return projectRoot ? path.resolve(projectRoot) : parseCliProjectRoot();
+  return projectRoot ? authorizedProjectRoot(projectRoot) : parseCliProjectRoot();
+}
+
+// The operator's default root is trusted. When configured, a client-supplied root must sit inside an allowed root.
+function authorizedProjectRoot(projectRoot) {
+  const resolved = path.resolve(projectRoot);
+  if (!SETTINGS.allowedProjectRoots) return resolved;
+  let canonical = null;
+  try { canonical = realpathSync(resolved); } catch {}
+  if (!canonical || !matchingRoot(SETTINGS.allowedProjectRoots, canonical)) {
+    throw new Error(`projectRoot is not inside a root allowed by ${PROJECT_ROOTS_SETTING}.`);
+  }
+  return resolved;
+}
+
+function matchingRoot(configuredRoots, candidate) {
+  return configuredRoots.flatMap((configuredRoot) => {
+    try {
+      return [realpathSync(path.resolve(configuredRoot))];
+    } catch {
+      return [];
+    }
+  }).find((allowedRoot) => isPathInside(allowedRoot, candidate)) ?? null;
 }
 
 function resolveRepoRoot(startDir) {
@@ -407,7 +432,7 @@ function serializeToolResult(payload) {
   return {
     content: [{
       type: 'text',
-      text: JSON.stringify(payload, null, GUIDANCE_TOOLS.has(payload.stage) ? undefined : 2),
+      text: JSON.stringify(payload),
     }],
     structuredContent: payload,
     ...(payload.responseBudget?.delivery === 'error' ? { isError: true } : {}),
@@ -833,6 +858,8 @@ async function loadGuideCatalog(projectRoot) {
     guideSource: 'bundled',
     count: bundledGuideCache.count,
     components: bundledGuideCache.components,
+    // Handlers reuse this resolution instead of reading the lockfiles again.
+    version: projectResolution,
   };
 }
 
@@ -965,9 +992,9 @@ async function projectSummary(projectRoot) {
   return summary;
 }
 
-async function resolveAgainstContract(projectRoot, contractVersion) {
-  const version = await resolveExpressiveVersion({ projectRoot, contractVersion });
-  if (contractVersion) return version;
+function resolveAgainstContract(catalog) {
+  const version = catalog.version;
+  if (catalog.frameworkVersion) return version;
   return {
     ...version,
     status: 'unresolved',
@@ -1060,6 +1087,8 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
   if (markupStructureExceedsLimit(snippet)) return markInspectionTruncated([], 'markup structure limit reached');
   const prefix = '<!doctype html><body>';
   const includeNodeLocations = snippet.length * (snippet.split('<').length - 1) <= MAX_LOCATED_MARKUP_WORK;
+  // Loaded on first use: jsdom takes ~0.3 s to load, and most server starts never inspect markup.
+  const { JSDOM } = createRequire(import.meta.url)('jsdom');
   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.
@@ -1532,14 +1561,7 @@ function isPathInside(root, candidate) {
 
 function commandExecutionPolicy(projectRoot) {
   const resolvedProjectRoot = realpathSync(path.resolve(projectRoot));
-  const allowedRoots = SETTINGS.allowedCommandRoots.flatMap((configuredRoot) => {
-    try {
-      return [realpathSync(path.resolve(configuredRoot))];
-    } catch {
-      return [];
-    }
-  });
-  const matchedRoot = allowedRoots.find((allowedRoot) => isPathInside(allowedRoot, resolvedProjectRoot)) ?? null;
+  const matchedRoot = matchingRoot(SETTINGS.allowedCommandRoots, resolvedProjectRoot);
   return {
     configured: SETTINGS.allowedCommandRoots.length > 0,
     allowed: Boolean(matchedRoot),
@@ -1589,7 +1611,7 @@ function stopProcessTree(proc, signal) {
   }
 }
 
-function redactSensitiveText(value) {
+export function redactSensitiveText(value) {
   return String(value)
     .replace(/(Authorization\s*:\s*Bearer\s+)[^\s,;]+/giu, '$1[REDACTED]')
     .replace(/\b(Bearer\s+)[A-Za-z0-9._~+\/-]{16,}/giu, '$1[REDACTED]')
@@ -1600,11 +1622,12 @@ function redactSensitiveText(value) {
     .replace(/\bxox[baprs]-[A-Za-z0-9-]{20,}\b/gu, '[REDACTED]')
     .replace(/\bsk-[A-Za-z0-9_-]{20,}\b/gu, '[REDACTED]')
     .replace(/\bAKIA[0-9A-Z]{16}\b/gu, '[REDACTED]')
-    .replace(/\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gu, '[REDACTED]')
+    // Start only where a token run starts; a bare `\b` retries inside `a-b-c` runs in quadratic time.
+    .replace(/(?<![A-Za-z0-9_-])[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gu, '[REDACTED]')
     .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu, '[REDACTED]')
     .replace(/(["'])(API[_-]?KEY|TOKEN|PASSWORD|PASSWD|SECRET|CLIENT[_-]?SECRET|CLIENTSECRET|CONNECTION[_-]?STRING|ACCESS_TOKEN|REFRESH_TOKEN|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY)\1\s*:\s*(["'])[^"'\r\n]*\3/giu, '$1$2$1:$3[REDACTED]$3')
     .replace(/\b(API[_-]?KEY|TOKEN|PASSWORD|PASSWD|SECRET|CLIENT[_-]?SECRET|CLIENTSECRET|CONNECTION[_-]?STRING|ACCESS_TOKEN|REFRESH_TOKEN|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY)\s*[:=]\s*[^\s,;]+/giu, '$1=[REDACTED]')
-    .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/giu, '$1[REDACTED]@')
+    .replace(/([a-z][a-z0-9+.-]{0,31}:\/\/)[^\s/@:]+:[^\s/@]+@/giu, '$1[REDACTED]@') // Bounded scheme keeps long runs linear.
     .replace(/\/(?:home|Users)\/[^/\s"'<>]+(?:\/[^\s"'<>),;\]}]*)?/gu, '[LOCAL_PATH]')
     .replace(/\/(?:private\/)?tmp\/[^\s"'<>),;\]}]+/gu, '[LOCAL_PATH]')
     .replace(/[A-Z]:\\+Users\\+[^\\\s]+(?:\\+[^\s]*)?/giu, '[LOCAL_PATH]');
@@ -1628,18 +1651,17 @@ export async function readInspectionFile(filePath, projectRoot, byteLimit) {
       throw error;
     }
 
-    const bytes = Buffer.allocUnsafe(byteLimit + 1);
+    // Size the buffer to the file, not the limit. The spare byte exposes growth
+    // and files such as /proc entries that report a smaller size than they hold.
+    const capacity = Number(before.size) + 1;
+    const bytes = Buffer.allocUnsafe(capacity);
     let total = 0;
-    while (total <= byteLimit) {
-      const chunk = await handle.read(bytes, total, byteLimit + 1 - total, total);
+    while (total < capacity) {
+      const chunk = await handle.read(bytes, total, capacity - total, total);
       if (chunk.bytesRead === 0) break;
       total += chunk.bytesRead;
     }
-    if (total > byteLimit) {
-      const error = new Error(`file exceeds ${byteLimit} byte read limit`);
-      error.code = 'INSPECTION_FILE_TOO_LARGE';
-      throw error;
-    }
+    if (total > before.size) throw new Error('file changed while reading');
 
     const after = await handle.stat({ bigint: true });
     const pathAfter = await lstat(filePath, { bigint: true });
@@ -1895,7 +1917,7 @@ async function setupExpertHandler(args) {
   const snapshot = await projectSummary(projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
   const contractVersion = catalog.frameworkVersion;
-  const version = await resolveExpressiveVersion({ projectRoot, contractVersion });
+  const version = catalog.version;
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
   const checks = [
     {
@@ -2013,7 +2035,7 @@ async function rulesEnforcerHandler(args) {
   const workflowId = parsed.workflowId || randomUUID();
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = resolveAgainstContract(catalog);
   const hasSnippet = parsed.snippet.trim().length > 0;
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
 
@@ -2135,7 +2157,7 @@ async function creativeDirectorHandler(args) {
   const parsed = creativeSchemaParsed.parse(args);
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = resolveAgainstContract(catalog);
   return toToolResult(buildCreativePayload(catalog, version, parsed), { ...parsed, projectRoot }, { catalog, version });
 }
 
@@ -2199,7 +2221,7 @@ async function pageArchitectHandler(args, stage = 'page_architect') {
   const workflowId = parsed.workflowId || randomUUID();
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = resolveAgainstContract(catalog);
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
   const contractSafe = version.status === 'match' && !provenanceBlock;
 
@@ -2272,7 +2294,7 @@ async function componentSyntaxExpertHandler(args) {
   const parsed = syntaxSchemaParsed.parse(args);
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = resolveAgainstContract(catalog);
   return toToolResult(buildSyntaxPayload(catalog, version, parsed), { ...parsed, projectRoot }, { catalog, version });
 }
 
@@ -2346,9 +2368,9 @@ function buildSyntaxPayload(catalog, version, parsed) {
 
 async function componentCatalogHandler(args) {
   const parsed = catalogSchemaParsed.parse(args);
-  const projectRoot = parsed.projectRoot === undefined ? undefined : path.resolve(parsed.projectRoot);
+  const projectRoot = parsed.projectRoot === undefined ? undefined : authorizedProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = projectRoot === undefined ? null : await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = projectRoot === undefined ? null : resolveAgainstContract(catalog);
   return toToolResult(buildCatalogPayload(catalog, version, parsed), parsed, { catalog, version });
 }
 
@@ -2422,8 +2444,7 @@ async function qualityInspectorHandler(args) {
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const fileSummary = summarizeProjectFiles(parsed.files, projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const contractVersion = catalog.frameworkVersion;
-  const version = await resolveExpressiveVersion({ projectRoot, contractVersion });
+  const version = catalog.version;
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
 
   const fileInspection = await findFileViolations(fileSummary.existing, projectRoot);

package/smoke.mjs

@@ -220,9 +220,18 @@ async function verifyResponseBudgets(matchingDir, versionedDir) {
     const result = await call(catalogRequest);
     assert.notEqual(result.structuredContent.responseBudget.delivery, 'complete');
   });
-  await withServer(20_000, async ({ call }) => {
+  // A partial listing needs room for one recovery record per omitted entry, and
+  // that accounting grows with the catalogue. Derive the budget from the
+  // complete listing so it stays below it while the accounting still fits; a
+  // fixed figure turns into the documented error once enough components exist.
+  let listingBytes;
+  await withServer(1_048_576, async ({ call }) => {
+    listingBytes = bytes(await call(request('component_catalog')));
+  });
+  await withServer(listingBytes - 3_000, async ({ call }) => {
     const listing = await call(request('component_catalog'));
     assert.equal(listing.structuredContent.responseBudget.delivery, 'partial');
+    assert.ok(listing.structuredContent.responseBudget.omissions.length > 1, 'the listing omits several entries');
     assert.equal(listing.structuredContent.count + listing.structuredContent.responseBudget.omissions.length, guideData.guides.length);
     for (const recovery of listing.structuredContent.responseBudget.recoveries) {
       assert.equal(recovery.action, 'retry');
@@ -230,6 +239,8 @@ async function verifyResponseBudgets(matchingDir, versionedDir) {
       assert.equal(recovered.structuredContent.entries[0].slug, recovery.request.arguments.query);
       assert.equal(recovered.structuredContent.responseBudget.delivery, 'complete');
     }
+  });
+  await withServer(20_000, async ({ call }) => {
     const duplicate = await call(request('component_syntax_expert', { projectRoot: matchingDir, components: ['cards', 'cards', 'unknown-name', 'autocomplete'], sections: ['options', 'methods'] }));
     assert.equal(duplicate.structuredContent.missing[0].requested, 'unknown-name');
     for (const omitted of duplicate.structuredContent.responseBudget.omissions.filter((row) => row.slug === 'cards')) assert.ok([0, 1].includes(omitted.index));
@@ -958,6 +969,12 @@ const transport = new StdioClientTransport({
   assert.match(long.stdout, /long\.html:1:1 nav-needs-label/u);
   assert.doesNotMatch(long.stdout, /inspection-truncated/u);
   assert.equal(lint([outsideFile]).status, 0);
+  // The retired class name matches only as a whole class, not inside documented names that contain it.
+  const cardContentMarkup = path.join(outsideDir, 'card-content.html');
+  await writeFile(cardContentMarkup, '<style>article { --md-comp-card-content-padding: 24px; }</style>\n<div class="expanding-card-content">Details</div>\n<div class="card-content">Old</div>\n');
+  const cardContent = lint([cardContentMarkup]);
+  assert.equal(cardContent.stdout.match(/legacy-card-content/gu)?.length, 1, cardContent.stdout);
+  assert.match(cardContent.stdout, /card-content\.html:3:\d+ legacy-card-content/u);
   // Files the bounded reader refuses, and inspections that stop early, fail instead of passing silently.
   const linkedMarkup = path.join(outsideDir, 'linked.html');
   const crowdedMarkup = path.join(outsideDir, 'crowded.html');
@@ -979,6 +996,21 @@ const transport = new StdioClientTransport({
   assert.equal(execFileSync(process.execPath, ['--input-type=module', '-e', "import('./server.js').then(() => console.log('imported'))"], { cwd: packageDir, encoding: 'utf8', timeout: 30_000 }).trim(), 'imported');
 }
 
+{
+  const { redactSensitiveText, readInspectionFile } = await import('./server.js');
+  // Command output is captured up to 160K characters. Redaction must stay linear on long token runs.
+  const startedAt = Date.now();
+  for (const output of ['ab12'.repeat(40_000), 'a-'.repeat(80_000), 'a'.repeat(160_000)]) redactSensitiveText(output);
+  assert.ok(Date.now() - startedAt < 2_000, `redaction took ${Date.now() - startedAt} ms`);
+  const redacted = redactSensitiveText('token eyJhbGciOiJIUzI1.eyJzdWIiOiIxMjM0.SflKxwRJSMeKKF2QT git+https://user:pass@example.com/x');
+  assert.doesNotMatch(redacted, /eyJhbGci|user:pass/u);
+  assert.match(redacted, /git\+https:\/\/\[REDACTED\]@example\.com/u);
+  if (process.platform === 'linux') {
+    // procfs reports size 0 for files with content. A size-bound read must fail, not return a truncated file.
+    await assert.rejects(readInspectionFile('/proc/self/status', '/proc', 1024 * 1024), /changed while reading/u);
+  }
+}
+
 const client = new Client({ name: 'expressivecss-mcp-smoke', version: '0.1.0' });
 
 try {
@@ -1287,6 +1319,7 @@ try {
     },
   });
   assert.ok(boundedRules.structuredContent.issueCount <= 200);
+  assert.equal(boundedRules.content[0].text.includes('\n  '), false, 'tool results are compact JSON');
   assert.ok(boundedRules.structuredContent.blockedChecks.includes('static inspection limit reached'));
 
   const nestedMarkupStartedAt = Date.now();
@@ -2273,6 +2306,52 @@ try {
     await timeoutClient.close();
   }
 
+  const rootsClient = new Client({ name: 'expressivecss-mcp-project-roots-smoke', version: '0.1.0' });
+  try {
+    await rootsClient.connect(new StdioClientTransport({
+      command: process.execPath,
+      args: [path.join(packageDir, 'server.js')],
+      cwd: packageDir,
+      stderr: 'pipe',
+      env: { ...process.env, EXPRESSIVECSS_MCP_ALLOWED_PROJECT_ROOTS: outsideDir },
+    }));
+    // A root outside the allowlist must not become a file-existence or hash oracle.
+    for (const [name, args] of [
+      ['quality_inspector', { projectRoot: os.tmpdir(), files: [outsideFile] }],
+      ['component_catalog', { projectRoot: os.tmpdir() }],
+      ['setup_expert', { projectRoot: path.join(outsideDir, 'missing') }],
+    ]) {
+      const denied = await rootsClient.callTool({ name, arguments: args });
+      assert.equal(denied.isError, true, `${name} accepted a root outside the allowlist`);
+      assert.match(denied.content[0].text, /EXPRESSIVECSS_MCP_ALLOWED_PROJECT_ROOTS/u);
+    }
+    const allowed = await rootsClient.callTool({ name: 'quality_inspector', arguments: { projectRoot: outsideDir, files: [] } });
+    assert.notEqual(allowed.isError, true, allowed.content[0].text);
+    const defaultRoot = await rootsClient.callTool({ name: 'component_catalog', arguments: {} });
+    assert.notEqual(defaultRoot.isError, true, 'the operator default root needs no allowlist entry');
+  } finally {
+    await rootsClient.close();
+  }
+
+  // Set but empty or invalid allowlists fail closed instead of allowing every root.
+  for (const setting of ['', '[]', '[broken', '[42]']) {
+    const closedClient = new Client({ name: 'expressivecss-mcp-closed-roots-smoke', version: '0.1.0' });
+    try {
+      await closedClient.connect(new StdioClientTransport({
+        command: process.execPath,
+        args: [path.join(packageDir, 'server.js')],
+        cwd: packageDir,
+        stderr: 'pipe',
+        env: { ...process.env, EXPRESSIVECSS_MCP_ALLOWED_PROJECT_ROOTS: setting },
+      }));
+      const denied = await closedClient.callTool({ name: 'quality_inspector', arguments: { projectRoot: outsideDir, files: [outsideFile] } });
+      assert.equal(denied.isError, true, `allowlist ${JSON.stringify(setting)} allowed a client root`);
+      assert.equal(JSON.stringify(denied).includes('sha256'), false);
+    } finally {
+      await closedClient.close();
+    }
+  }
+
   const trapTransport = new StdioClientTransport({
     command: process.execPath,
     args: [path.join(packageDir, 'server.js')],