From 4827330d62d879f2a0e81c73e24e14ec0f1b3f91 Mon Sep 17 00:00:00 2001
From: Noah <office@playspots.de>
Date: Wed, 5 Aug 2026 15:04:12 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20llms-install.md=20=E2=80=94=20agent-rea?=
 =?UTF-8?q?dable=20install=20guide=20(Cline,=20Claude,=20stdio)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hosted endpoint config for Cline (streamableHttp), Claude Code, Claude
connectors, plus the npx stdio alternative with the full local toolset.
Includes a curl liveness check and the keyless rate limit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0149NhkePB1zzszxUyG1L5vW
---
 llms-install.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 llms-install.md

diff --git a/llms-install.md b/llms-install.md
new file mode 100644
index 0000000..d7740e5
--- /dev/null
+++ b/llms-install.md
@@ -0,0 +1,73 @@
+# Installing MotionSpec (MCP server)
+
+MotionSpec's MCP server is **hosted** — nothing to build, nothing to install, and **no API key** for the read tools.
+
+- Endpoint: `https://api.motionspec.dev/mcp` (streamable HTTP, stateless)
+- Keyless tools: `motion_catalog`, `motion_validate` — both read-only (`readOnlyHint: true`)
+- Keyed tools on the hosted endpoint (Dev Key): `motion_compile`, `motion_audit`, `motion_stats`
+
+## Cline
+
+Add to your MCP settings (Settings → MCP Servers → Configure, or `~/.cline/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "motionspec": {
+      "type": "streamableHttp",
+      "url": "https://api.motionspec.dev/mcp",
+      "disabled": false,
+      "autoApprove": ["motion_catalog", "motion_validate"]
+    }
+  }
+}
+```
+
+`"type": "streamableHttp"` matters — omitting it falls back to legacy SSE. Both keyless tools are read-only, so `autoApprove` is safe.
+
+## Claude Code
+
+```bash
+claude mcp add --transport http motionspec https://api.motionspec.dev/mcp
+```
+
+## Claude (desktop / web)
+
+Settings → Connectors → Add custom connector → `https://api.motionspec.dev/mcp`
+
+## Local (stdio) alternative — full toolset, no key
+
+```bash
+npx -y motionspec
+```
+
+This runs the same server over stdio. Locally the **full** toolset is registered, including `motion_compile` — compilation is MIT-licensed and runs on your machine; the Dev Key only gates the hosted endpoint.
+
+```json
+{
+  "mcpServers": {
+    "motionspec-local": {
+      "command": "npx",
+      "args": ["-y", "motionspec"]
+    }
+  }
+}
+```
+
+## Verify the endpoint is alive
+
+```bash
+curl -s -X POST https://api.motionspec.dev/mcp \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+Expected: two tools (`motion_catalog`, `motion_validate`), both with `"readOnlyHint": true`. The keyless path is rate-limited (60 requests / 10 s per IP).
+
+## What the tools do
+
+1. `motion_catalog` — the 40 verified motion primitives + authoring rules (18 are persistent/looping and carry a WCAG 2.2.2 pause path).
+2. `motion_validate` — fail-closed validation of a MotionSpec JSON spec; reports WCAG 2.2.2 pause-path **candidates** as warnings (missing reduced-motion guards are flagged as a 2.3.3/AAA best-practice gap).
+
+Docs: https://motionspec.dev/docs · llms context: https://motionspec.dev/llms.txt