@aitrien/motifspec 1.13.3 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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

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 one checker holds every project that uses it to those rules.
+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
 
@@ -50,6 +50,8 @@ js/codex.js         Theme toggle, copy buttons, tooltip dismissal, TOC docking a
 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/                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, 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)
 ```
@@ -63,6 +65,8 @@ 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, 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:
@@ -75,7 +79,7 @@ npm run check -- <dir>  # check a project that uses MotifSpec (see below)
 
 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
 
@@ -109,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.3 — 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.3 — 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.3";
+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.3",
+  "version": "1.14.0",
   "changelog": "https://github.com/Aitrien/motifspec/blob/main/CHANGELOG.md",
   "tokens": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitrien/motifspec",
-  "version": "1.13.3",
+  "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"
   }
 }