@aitrien/motifspec 1.13.2 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 Every release of MotifSpec (named brand-codex until 1.10.0), newest first. Entries before 1.10.0 keep the names they were released under. Versions follow the rules in `CONVENTIONS.md`: renaming or removing a semantic token is major, adding tokens, components or icons is minor, and changing a value or fixing a description is a patch. `npm run build` fails if the version in `package.json` has no entry here.
 
+## [1.14.0] - 2026-10-28
+
+### Added
+- The MotifSpec MCP server, at `https://mcp.motifspec.com/mcp`, for any AI assistant that supports remote MCP servers. Read-only, no sign-in. Five tools:
+  - `get_rules`: the README's rules and what the checker enforces.
+  - `find_tokens`: semantic tokens matching a query, with usage rule, CSS property, light and dark values, and the surfaces a colour may sit on.
+  - `get_component`: a component's doc with its Hugo partial and Markdown form, or the list.
+  - `get_doc`: `docs/hugo.md` or `docs/templates.md`.
+  - `check`: the rule checker on a piece of markup, Markdown or CSS.
+
+  It answers from this release's own files and tells assistants which version it serves. Built with the official MCP SDK (stateless Streamable HTTP, JSON responses).
+- Hosting: AWS Lambda behind an API Gateway HTTP API on the custom domain, rate-limited, defined in `infra/mcp.yml`. The release workflow bundles the server (`npm run mcp:bundle`, about 260 KB), tests the bundle, deploys it with a role GitHub assumes through OIDC (no stored AWS key; only main can use it, and it can only replace the function's code), and checks the live server reports the new version.
+- `npm run test:mcp`, run in CI on the source and on the bundle: calls every tool through the Lambda handler.
+- README: "Using it from an AI assistant", with how to connect Claude, Claude Code, VS Code and others.
+
+The npm package is unchanged apart from the version: the server's SDK, zod and esbuild are dev dependencies, and `mcp/` and `infra/` aren't in the package.
+
+## [1.13.3] - 2026-10-27
+
+### Changed
+- Docs: each fact now lives in one place. The README's Hugo section points to `docs/hugo.md` (which now has the stylesheet path note and the full front-matter example from `docs/templates.md`), the release process lives in `CONVENTIONS.md`, and `docs/hugo.md` points to the README's list of what the checker checks. Statements about an MCP server that doesn't exist yet are removed, as are the planned-only `mcp/README.md` and the SCSS row in `CONVENTIONS.md`, which the build has never generated. The npm install line pins whatever version is current instead of naming 1.13.0.
+- `AGENTS.md` (with `CLAUDE.md` pointing to it): where a change goes in this repo, what to run before finishing, and how releasing works, linking to the README and `CONVENTIONS.md` for everything else. Repo-only; not in the npm package.
+
 ## [1.13.2] - 2026-10-27
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # MotifSpec
 
-Liam Marshall's design system: the single source of truth for aitrien.com and every project after it. Tokens are [DTCG](https://www.designtokens.org/) JSON, components are documented rules with markup to copy, and an MCP server serves both to AI coding assistants.
+Liam Marshall's design system: the single source of truth for aitrien.com and every project after it. Tokens are [DTCG](https://www.designtokens.org/) JSON, components are documented rules with markup to copy, one checker holds every project that uses it to those rules, and an MCP server gives AI assistants all three.
 
 ## Principles
 
@@ -33,6 +33,7 @@ Liam Marshall's design system: the single source of truth for aitrien.com and ev
 
 ```
 LICENSE             MIT, for code, tokens and docs
+AGENTS.md           Instructions for AI agents changing this repo (CLAUDE.md points to it)
 CHANGELOG.md        Every release, newest first (the build fails without an entry for the current version)
 tokens/             DTCG source of truth (color, typography, space, size, radius, border, motion)
 css/components.css  Reference implementation of every component (tokens only)
@@ -44,14 +45,15 @@ docs/hugo.md        The Hugo partials and render hooks, their contexts and the f
 layouts/            Hugo partials (_partials/motifspec/) and Markdown render hooks (_markup/), mounted by the module
 docs/syntax-highlighting.md
 fonts/              Self-hosted WOFF2 (Latin subsets) and their OFL licences
-scripts/            validate, build, audit, check (the rule checker sites run) and release
+scripts/            validate, build, audit, check (the rule checker projects run), pack-check and release
 js/codex.js         Theme toggle, copy buttons, tooltip dismissal, TOC docking and active section (shared by sites and the showcase)
 js/theme-init.js    One-line <head> snippet that applies a stored theme before first paint
 js/plate.js         Contour survey generator for the backdrop and the specimen plate: draws the static contours at build time and animates them in the browser
 showcase/           Source of the system's showcase page
-mcp/                MCP server (Phase 3)
+mcp/                The MCP server (server.mjs), its Lambda handler, bundle step and tests
+infra/mcp.yml       The server's AWS stack and deploy role (CloudFormation, applied by hand)
 hugo.toml, go.mod   Hugo module definition and its mounts
-dist/               Generated: tokens.css, components in codex.css, chroma.css, fonts.css, icons.svg (sprite), tokens.json (for MCP), tokens.js (ES module export), codex.js and theme-init.js (behaviour), backdrop.html, plate.html and plate.js (backdrop and specimen plate), contrast.md, showcase.html (fragment for publishing), showcase.standalone.html (open locally)
+dist/               Generated: tokens.css, components in codex.css, chroma.css, fonts.css, icons.svg (sprite), tokens.json, tokens.js (ES module export), codex.js and theme-init.js (behaviour), backdrop.html, plate.html and plate.js (backdrop and specimen plate), contrast.md, showcase.html (fragment for publishing), showcase.standalone.html (open locally)
 ```
 
 ## Commands
@@ -63,9 +65,11 @@ npm run audit     # prove dist/showcase.html and the shipped scripts have no raw
 npm run release:check  # what merging this would release, and whether that release is valid
 npm run pack:check     # the npm package has every file the README and package.json promise
 npm run check -- <dir>  # check a project that uses MotifSpec (see below)
+npm run test:mcp       # call every MCP tool through the Lambda handler
+npm run mcp:bundle     # build/mcp.zip, the server's Lambda package
 ```
 
-`scripts/check.mjs` is the one rule checker: this repo's audit runs it on `layouts/` and the component docs' markup, sites run it from their pinned module, and the MCP server's `check_styles` will call it. It checks a project's `layouts/` and `content/` against the release it comes from, and fails on:
+`scripts/check.mjs` is the one rule checker: this repo's audit runs it on `layouts/` and the component docs' markup, and projects run it from the version they pin. It checks a project's `layouts/` and `content/` against the release it comes from, and fails on:
 
 - a stylesheet anywhere in the project, or a `style` attribute
 - a raw colour, or a number with a length or time unit (zero is allowed)
@@ -73,43 +77,21 @@ npm run check -- <dir>  # check a project that uses MotifSpec (see below)
 - a `cx-` class that the stylesheet and scripts don't define, or a `cx-icon-` that isn't in `icons/manifest.json`
 - "·" used as a separator
 
-Releases are automatic. Bump `version` in `package.json` and add its `CHANGELOG.md` entry in the PR; once it is merged and CI passes on main, `.github/workflows/release.yml` tags that commit, publishes a GitHub release with the entry as its notes, and publishes that commit to npm with provenance (npm trusted publishing: no token is stored). A merge that doesn't change the version releases nothing.
+Releases are automatic; `CONVENTIONS.md` (Versioning) says how.
 
-Node 20 or later, no dependencies.
+Node 20 or later. The package has no dependencies; the MCP server's are dev dependencies, bundled into its deployment.
 
 ## Using it in Hugo
 
-Import the module and pin a release with `hugo mod get github.com/aitrien/motifspec@vX.Y.Z`. It mounts `dist/` at `assets/motifspec`, `fonts/` at `static/fonts`, and `layouts/` at `layouts`, so a site gets the component partials and the Markdown render hooks as well as the CSS and scripts:
-
-```toml
-[module]
-  [[module.imports]]
-    path = "github.com/aitrien/motifspec"
-```
-
-A page template then needs only the shell partials around its own content:
-
-```go-html-template
-<head>
-  {{ partial "motifspec/head.html" . }}
-</head>
-<body class="cx-backdrop-page">
-  {{ partial "motifspec/body-start.html" . }}
-  {{ partial "motifspec/site-header.html" . }}
-  <main id="main" tabindex="-1">…</main>
-  {{ partial "motifspec/body-end.html" . }}
-</body>
-```
-
-`docs/hugo.md` lists every partial with its context, the front matter they read, the render hooks and the Markdown they expect, and the Goldmark settings they need. Keep the stylesheet's published path one level below the site root (Hugo publishes it at `/motifspec/`): its font URLs are `../fonts/…`, which resolve to the mounted `/fonts/`.
+Import `github.com/aitrien/motifspec` as a Hugo module and pin a release with `hugo mod get github.com/aitrien/motifspec@vX.Y.Z`. The site then gets the CSS, scripts, fonts, component partials and Markdown render hooks; `docs/hugo.md` covers setup, every partial and the front matter they read.
 
 ## Using it from npm
 
 ```sh
-npm install @aitrien/motifspec@1.13.0
+npm install --save-exact @aitrien/motifspec
 ```
 
-Pin an exact version, as a Hugo site pins a tag: the version you install is the version the checker and (later) the MCP server hold you to. The package has the CSS, scripts, tokens, fonts, icons, component docs, Hugo templates and the checker; it leaves out the showcase.
+Pin an exact version, as a Hugo site pins a tag: the version you install is the version the checker holds you to. The package has the CSS, scripts, tokens, fonts, icons, component docs, Hugo templates and the checker; it leaves out the showcase.
 
 | Import | What it is |
 |---|---|
@@ -131,6 +113,27 @@ npx motifspec-check . --dirs src
 
 It reads `.html`, `.jsx`, `.tsx`, `.vue`, `.svelte`, `.astro`, `.md` and `.mdx` (both `class` and `className`), and skips `node_modules`, `dist` and `build`. Its stylesheet rule applies here too: a project using MotifSpec has no CSS of its own.
 
+## Using it from an AI assistant
+
+The MCP server at `https://mcp.motifspec.com/mcp` serves the latest release to any assistant that supports remote MCP servers. It needs no sign-in and only reads.
+
+| Tool | What it returns |
+|---|---|
+| `get_rules` | The rules above, and what the checker enforces |
+| `find_tokens` | Semantic tokens matching a query: CSS property, usage rule, light and dark values, the surfaces a colour may sit on |
+| `get_component` | A component's doc (markup, do and don't, accessibility), with its Hugo partial and Markdown form; without a name, the list |
+| `get_doc` | `docs/hugo.md` or `docs/templates.md` |
+| `check` | The checker's problems in a piece of markup, Markdown or CSS |
+
+To connect it:
+
+- **Claude (web, desktop):** Customize → Connectors → Add custom connector, with the URL above and "No sign in".
+- **Claude Code:** `claude mcp add --transport http motifspec https://mcp.motifspec.com/mcp`, or a project `.mcp.json`.
+- **VS Code:** add it to `.vscode/mcp.json` with `"type": "http"` and the URL.
+- **Others:** add a remote MCP server by URL.
+
+It serves the latest release. A project pinned to an older version can be offered something its version doesn't have yet; its own checker, at its pinned version, catches that.
+
 ## The identity in brief
 
 | | |

package/dist/codex.css

@@ -2,7 +2,7 @@
 @font-face { font-family: "JetBrains Mono"; src: url("../fonts/jetbrains-mono-latin-wght.woff2") format("woff2"); font-weight: 100 800; font-style: normal; font-display: swap; }
 @font-face { font-family: "Yarndings 12"; src: url("../fonts/yarndings-12-latin.woff2") format("woff2"); font-weight: 400; font-style: normal; font-display: block; }
 
-/* MotifSpec 1.13.2 — generated from tokens/*.json. Do not edit.
+/* MotifSpec 1.14.0 — generated from tokens/*.json. Do not edit.
    Themes: semantic colours use light-dark(); color-scheme follows the system unless
    <html data-theme="light|dark"> pins it. --cx-primitive-* are for this file only. */
 :root {

package/dist/tokens.css

@@ -1,4 +1,4 @@
-/* MotifSpec 1.13.2 — generated from tokens/*.json. Do not edit.
+/* MotifSpec 1.14.0 — generated from tokens/*.json. Do not edit.
    Themes: semantic colours use light-dark(); color-scheme follows the system unless
    <html data-theme="light|dark"> pins it. --cx-primitive-* are for this file only. */
 :root {

package/dist/tokens.js

@@ -1,5 +1,5 @@
 // Generated by npm run build. Do not edit.
-export const version = "1.13.2";
+export const version = "1.14.0";
 export const changelog = "https://github.com/Aitrien/motifspec/blob/main/CHANGELOG.md";
 export const tokens = [
   {

package/dist/tokens.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.13.2",
+  "version": "1.14.0",
   "changelog": "https://github.com/Aitrien/motifspec/blob/main/CHANGELOG.md",
   "tokens": [
     {

package/docs/components/_template.md

@@ -21,7 +21,7 @@ One sentence: what it is for.
 ## Markup
 
 ```html preview
-<!-- Minimal markup. The dashboard renders this block as a live preview, and the MCP server returns it as the pattern to copy. -->
+<!-- Minimal markup: the pattern to copy. -->
 ```
 
 ## Do

package/docs/hugo.md

@@ -18,7 +18,7 @@ The module ships the components as Hugo partials and the Markdown render hooks t
     block = true                              # {caption="…"} on tables, {file="…"} on code, {width="prose"} on figures
 ```
 
-Pin a release with `hugo mod get github.com/aitrien/motifspec@vX.Y.Z`. The module mounts `dist/` at `assets/motifspec`, `fonts/` at `static/fonts` and `layouts/` at `layouts`.
+Pin a release with `hugo mod get github.com/aitrien/motifspec@vX.Y.Z`. The module mounts `dist/` at `assets/motifspec`, `fonts/` at `static/fonts` and `layouts/` at `layouts`. Hugo publishes the stylesheet at `/motifspec/`; keep it one level below the site root, because its font URLs are `../fonts/…`.
 
 ## The page shell
 
@@ -76,6 +76,18 @@ Every partial below is called as `partial "motifspec/<name>.html" <context>`.
 
 ## Front matter the partials read
 
+```yaml
+title: Interactive WebGL globe
+accession: LM-W-001
+date: 2026-03-14
+summary: A React app that renders live routes on a 3D globe.
+role: Sole engineer
+stack: [React, WebGL, Vite]
+status: live        # live | building | archived
+tags: [react, webgl, a11y]
+hero: { src: hero.png, alt: "…", caption: "…" }
+```
+
 | Field | Used by | Notes |
 |---|---|---|
 | `summary` | cards, rows | The lede and the card or row summary. |
@@ -113,7 +125,7 @@ const motifspec = mounts.split(/\n(?=\{)/).map((m) => JSON.parse(m)).find((m) =>
 execFileSync('node', [join(motifspec.dir, 'scripts', 'check.mjs'), '.'], { stdio: 'inherit' });
 ```
 
-It checks `layouts/` and `content/` and fails on stylesheets, style attributes, raw colours and units, primitive, unknown or deprecated tokens, classes and icons MotifSpec doesn't define, and "·" separators. In GitHub Actions each problem is also an annotation on the pull request; `--json` prints the problems as JSON. In CI, give the step the same `HUGO_CACHEDIR` and `HUGO_MODULE_PROXY` as the build, because `hugo config mounts` downloads the module if it isn't cached.
+It checks `layouts/` and `content/` for what the README's Commands section lists. In GitHub Actions each problem is also an annotation on the pull request; `--json` prints the problems as JSON. In CI, give the step the same `HUGO_CACHEDIR` and `HUGO_MODULE_PROXY` as the build, because `hugo config mounts` downloads the module if it isn't cached.
 
 ## Overriding
 

package/docs/templates.md

@@ -16,15 +16,6 @@ Content hierarchy for the six page types. Every template sits on the backdrop (`
 - Work: `LM-W-001` onward. Writing: `LM-P-001` onward. Zero-padded, never reused, stored in front matter as `accession`.
 - They appear on cards, post rows, post meta lines and case-study labels.
 
-## Hugo front matter
+## Front matter
 
-```yaml
-title: Interactive WebGL globe
-accession: LM-W-001
-date: 2026-03-14
-summary: A React app that renders live routes on a 3D globe.
-role: Sole engineer
-stack: [React, WebGL, Vite]
-status: live        # live | building | archived
-tags: [react, webgl, a11y]
-```
+The fields each template reads are in `docs/hugo.md` (Front matter the partials read).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitrien/motifspec",
-  "version": "1.13.2",
+  "version": "1.14.0",
   "description": "Liam Marshall's design system: DTCG tokens, component rules, generated CSS, Hugo templates and a rule checker.",
   "keywords": [
     "design-system",
@@ -60,9 +60,16 @@
     "audit": "node scripts/audit.mjs",
     "check": "node scripts/check.mjs",
     "release:check": "node scripts/release.mjs",
-    "pack:check": "node scripts/pack-check.mjs"
+    "pack:check": "node scripts/pack-check.mjs",
+    "test:mcp": "node --test mcp/test.mjs",
+    "mcp:bundle": "node mcp/build.mjs"
   },
   "engines": {
     "node": ">=20"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "esbuild": "0.28.2",
+    "zod": "4.6.7"
   }
 }

package/scripts/check.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // The MotifSpec rule checker: one implementation for this repo's templates (npm run audit), for sites that use
-// MotifSpec (their CI runs this file from the pinned module) and for the MCP server's check_styles tool.
+// MotifSpec (their CI runs this file from the pinned module) and for any tool that imports checkText.
 //
 //   node scripts/check.mjs [project-root]                 check a consuming project's layouts/ and content/
 //   node scripts/check.mjs [project-root] --dirs src,app  check other folders instead (a non-Hugo project)