ShippedEpic

Add SynthMCP workspace package (packages/synthmcp): stdio MCP server over synthcss.ai.json with 7 tools

Proposed by Jonathan Miller 1 month agoFunding opened 1 month agoFunded 1 month agoShipped 1 month ago
Acceptance · round 1
Shipped
CINo checks
Automated reviewPass with concerns

This is a thorough, well-tested SynthMCP package: 7 read-only tools over the contract using the SDK and parse5, strong tests (in-memory and stdio, fidelity, drift, security scan, every issue type) and good docs. One acceptance criterion is deliberately unmet: "sidebar next to main content" resolves to `.sidebar` rather than `.split`, a defensible contract-based choice that the backers or maintainer still need to accept. No CI ran and the diff is truncated, so the contract JSON, showcase and dist byte-identity could not be verified directly. The release workflow is also broadened beyond a minimal edit.

Acceptance criteria · 14 of 19 met
  • YESpackages/synthmcp/package.json exists, declares @modelcontextprotocol/sdk and parse5, and defines the synthmcp binThe new `packages/synthmcp/package.json` lists both deps (plus `synthcss: file:../..`) and has `bin.synthmcp: src/server.js`.
  • YESRoot package.json declares workspaces and adds no new runtime dependencies`package.json` adds `"workspaces": ["packages/*"]` and only scripts, and the existing `build.test.mjs` check that it has no `dependencies` remains.
  • PARTIALnpm run mcp, the synthmcp bin and node packages/synthmcp/src/server.js all start a stdio MCP server`stdio.test.js` spawns all three and lists 7 tools, though `npm run mcp` is tested as `npm run --silent mcp` and the bin test is skipped if not linked.
  • YESA test using the SDK client over an in-memory or stdio transport lists exactly 7 tools`server.test.js` asserts `tools.length === 7` with exact names over `InMemoryTransport`, and `stdio.test.js` does the same over stdio.
  • YESget_component and get_layout output matches the contract for every entry`tools.test.js` iterates every component and primitive and deep-equals the variants, parts, accessibility, behaviors and example against the contract.
  • YESUnknown names and patterns return structured errors and never throw`server.test.js` covers not-found, unknown-tool, invalid-arguments, too-large and prototype-key names, and `callTool` wraps handlers in try/catch.
  • YESEvery intent-mapping target and every class used in examples is a public, non-internal contract class`tools.test.js` checks intent class/with and example classes against `publicClasses`, and the verifier's `checkMcpSections` enforces the same.
  • YESresolve_intent returns .cluster for 'a row of items/buttons that wraps'`intent.test.js` asserts `.cluster` for that exact input.
  • NOresolve_intent returns .split for 'sidebar next to main content'`intent.test.js` intentionally asserts `.sidebar` instead, with a comment citing the contract's intentMap.
  • YESresolve_intent returns no-match for nonsense input`intent.test.js` checks four nonsense inputs return `error: "no-match"`.
  • YESvalidate_markup tests cover all 7 issue types, valid/invalid data-synth-* usage, and ignoring arbitrary user classes`validate.test.js` has dedicated tests for unknown-class, unsupported-variant, internal-class (via fixture), invalid-part, unknown-data-attribute, invalid-target and a11y, plus valid data-synth usage and ignored user classes.
  • YESEvery official example validates with zero errors`tools.test.js` 'every official example validates with zero errors' covers patterns, valid examples, component/primitive examples, requiredMarkup and notCovered.
  • YESDrift test: a modified contract fixture loaded via the override changes tool output`drift.test.js` writes a modified contract to a temp file, loads it via `contractPath`, and checks changed output from every tool; the env override is also tested.
  • YESA test scans packages/synthmcp/src/ and fails on child_process, net, http(s), fetch and fs write APIs`security.test.js` has the FORBIDDEN regex list, an import allowlist, a readFileSync-only fs import check and self-tests of the scanner.
  • YESEvery tool response includes synthVersion and contractVersion`callTool` spreads both versions into every payload, and `server.test.js` checks success, error and unknown-tool responses.
  • UNCLEARContract changes are additive and contract minor version bumpedThe verifier tests now assert `contractVersion` 1.4.0 and the new keys are added to JSON_KEYS, but the `synthcss.ai.json` diff itself is truncated so additivity cannot be inspected.
  • UNCLEARExisting build and test commands still pass, and the root test command runs the synthmcp testsThe root `test` script appends `npm run test -w synthmcp`, but no CI ran, so passing is unverified.
  • UNCLEARBrowser dist/ output is byte-identical apart from intentional version stringsNo `src/` CSS/JS changes are visible and a new `build.test.mjs` asserts outputs contain no synthmcp/parse5 references, but byte-identity was not shown or run.
  • YESNo MCP dependency appears in browser bundles or in the core package's dependency listRoot `package.json` dependencies are unchanged and `build.test.mjs` scans build outputs for MCP strings.
Concerns
  • Acceptance criterion deliberately unmet: `resolve_intent("sidebar next to main content")` returns `.sidebar`, not `.split`. The builder's reasoning is grounded in the contract's existing intentMap and is well argued, but backers or the maintainer must explicitly accept this deviation. Getting `.split` would mean changing intent keywords in the contract.
  • No CI ran on this commit, so none of the claims (`npm test` including the synthmcp tests, the stdio and npm-run tests, the contract verifier and byte-identical `dist/`) are verified by an actual run.
  • The diff is truncated: the `synthcss.ai.json` changes (the 1.4.0 bump, new sections, additive-only guarantee), the `synthcss.llm.md` header and the showcase SynthMCP section (`.cluster`/`.button-danger`) cannot be inspected. Those criteria are judged only from the tests and docs that reference them.
  • The release workflow now triggers an automatic minor bump and CDN release whenever `packages/synthmcp/src/` or its `package.json` changes. The spec asked for minimal, additive workflow edits; this widens what produces CDN releases. A new npm publish step needing an `NPM_TOKEN` secret is also added.
  • `synthcss` is declared as `"file:../.."` rather than a version, contrary to the spec's assumption (justified because the core package is private), and the published package ships a copied contract. Separately, `npm run mcp` without `--silent` writes npm's banner onto the protocol stdout; the tests only exercise `npm run --silent mcp`.
CI details
No CI checks ran on this commit.

BackersAccepted
1 accept · 0 rebuild · 0 not voted · quorum 1 of 1
MaintainerMerge

Accepted by the backers and merged by the maintainer.

Ballots · 1
AcceptJonathan Miller

Automated review cost $0.42, counted as builder cost.

Motivation

Coding agents should be able to query and validate SynthCSS through MCP instead of having the full docs embedded in their prompts. Every answer comes from synthcss.ai.json, the single source of truth.

Scope

Package layout (maintainer decision)

  • Add SynthMCP as a workspace sub-package at packages/synthmcp/ in the existing repository.
  • It has its own package.json, with @modelcontextprotocol/sdk and parse5 as its only runtime dependencies.
  • Do not hand-roll the MCP transport or HTML parsing.
  • The core synthcss package gains no runtime dependencies. The browser CSS/SynthJS build must never import or bundle anything from packages/synthmcp/.
  • Add "workspaces": ["packages/*"] to the root package.json.
  • The sub-package exposes a bin named synthmcp, pointing at packages/synthmcp/src/server.js.
  • The root npm run mcp delegates to the workspace, for example npm run start -w synthmcp.
  • Assumption: the sub-package reads the repository's canonical synthcss.ai.json, resolved via the synthcss package (declared as a dependency of synthmcp, "synthcss": "<current version>", linked by the workspace). If needed, add ./synthcss.ai.json to the core package exports/files. This is an additive change only. Do not copy the contract into the sub-package source.
  • Assumption: the existing release workflow is extended to also build, test and publish packages/synthmcp. Its version tracks the core synthVersion. Make minimal, additive workflow edits only.
  • Assumption: the code uses ES modules (or the repo's existing module style) and requires Node >= 18.

Single source of truth

  • At startup the server reads all of the following from synthcss.ai.json:
    • components, layouts, variants and parts
    • accessibility expectations
    • internal classes
    • SynthJS metadata
    • intents and examples
  • A contract path override (env var SYNTHMCP_CONTRACT or a constructor option) is allowed, for tests only.
  • packages/synthmcp/ contains no hard-coded class registry.
  • Contract extension (maintainer decision): add the missing fields: parts, accessibility expectations, internal markers, a new intents section and a new examples section.
    • Changes are additive only. Do not rename or remove existing fields.
    • Bump the contract minor version.
    • Update any existing scripts or tests that validate the contract shape.

Tools (v1)

All responses are compact JSON (serialised as text content) and include synthVersion and contractVersion. The server metadata reports both versions as well.

  1. list_components(): returns name, class and a one-line intent for each public component.
  2. get_component({name}): returns intent, class, variants, parts, accessibility expectations, SynthJS behaviours/attributes (when the contract defines them) and a minimal example. An unknown name returns {error:"not-found", name, available:[...]}.
  3. list_layouts(): returns name, class and a one-line intent for each layout primitive.
  4. get_layout({name}): returns intent, class, variants, responsive behaviour, recommended composition and an example. An unknown name returns a structured not-found error.
  5. resolve_intent({intent}):
    • Uses deterministic keyword/synonym scoring against the contract intents section. No LLM.
    • Returns {class, reason, alternatives?}.
    • Returns {error:"no-match"} below a fixed threshold.
  6. validate_markup({html}), parsed with parse5:
    • Returns {valid, issues:[{type, severity, value, message, suggestion?}]}.
    • Issue types:
      • unknown-class
      • unsupported-variant
      • internal-class
      • invalid-part
      • unknown-data-attribute (for data-synth-*)
      • invalid-target (a data-synth-* target that does not resolve within the fragment)
      • a11y (contract-listed expectations)
    • Only synth-namespaced or contract-known classes are checked. Arbitrary user classes are ignored.
    • Suggestions are the closest public names by edit distance.
    • valid is false if any issue has severity error.
  7. get_example({pattern}):
    • Returns the official example from the contract examples section.
    • Required patterns: dashboard-header, settings-form, card-grid, dialog, tabs, empty-state.
    • An unknown pattern returns an error listing the available names.

Security

  • The server reads only the contract (or the test override path) and its tool arguments.
  • No file writes, shell execution, network access or reads of arbitrary paths.

Docs and showcase

  • Add docs/mcp.md (linked from the README) covering:
    • the run commands (npx synthmcp, npm run mcp)
    • a Claude Desktop/Code client config snippet
    • each tool's arguments, with an example call and response
    • versioning
    • the relationship to synthcss.ai.json and SynthJS
  • Add a static SynthMCP section to the showcase with the .cluster and .button-danger examples.
    • Assumption: if .button-danger is not a public contract class, use the contract's actual danger-button form and note it.

Acceptance criteria

  • packages/synthmcp/package.json exists, declares @modelcontextprotocol/sdk and parse5, and defines the synthmcp bin.
  • The root package.json declares workspaces and adds no new runtime dependencies.
  • npm run mcp, the synthmcp bin and node packages/synthmcp/src/server.js all start a stdio MCP server.
  • A test using the SDK client over an in-memory or stdio transport lists exactly 7 tools.
  • get_component and get_layout output matches the contract for every entry.
  • Unknown names and patterns return structured errors and never throw.
  • Every intent-mapping target and every class used in examples is a public, non-internal contract class.
  • resolve_intent returns:
    • .cluster for "a row of items/buttons that wraps"
    • .split for "sidebar next to main content"
    • no-match for nonsense input
  • validate_markup tests cover each of the 7 issue types, valid and invalid data-synth-* usage, and the case where arbitrary user classes are ignored.
  • Every official example validates with zero errors.
  • Drift test: a modified contract fixture loaded via the override changes tool output.
  • A test scans packages/synthmcp/src/ and fails on:
    • child_process, net, http(s) or fetch
    • fs write APIs (writeFile, appendFile, createWriteStream, mkdir, rm, unlink)
  • Every tool response includes synthVersion and contractVersion.
  • Contract changes are additive and the contract minor version is bumped.
  • Existing build and test commands still pass, and the root test command also runs the synthmcp tests.
  • The browser dist/ output is byte-identical apart from intentional version strings.
  • No MCP dependency appears in browser bundles or in the core package's dependency list.

Out of scope

  • suggest_structure (deferred by the maintainer)
  • Editing user files
  • Application or arbitrary CSS generation
  • Hosted MCP, authentication or network access
  • Browser control
  • Design-system ingestion
  • Refactoring existing source

No comments yet.