gridform-mcp 1.0.0

package/GUIDE.md

@@ -0,0 +1,244 @@
+# Gridform MCP — full guide
+
+Connect Gridform to Claude Desktop, IDEs, and agents via the [Model Context
+Protocol](https://modelcontextprotocol.io). The server exposes the poster engine as a
+complete, programmatic design studio — **discover, generate, vary, refine, reformat, and
+produce** posters — returning real PNG/SVG/PDF/JPG inline. **29 tools** (most need no API
+key), plus browseable **resources** and reusable **prompts**.
+
+- [What it is](#what-it-is)
+- [How it renders (headless)](#how-it-renders-headless)
+- [Connect to Claude Desktop](#connect-to-claude-desktop)
+- [Connect to other clients](#connect-to-other-clients)
+- [The tools](#the-tools)
+- [Resources & prompts](#resources--prompts)
+- [A worked example](#a-worked-example)
+- [Determinism, fonts & keys](#determinism-fonts--keys)
+- [Developing from source](#developing-from-source)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## What it is
+
+A self-contained Node server, published on npm as **`gridform-mcp`**, that wraps the
+Gridform engine. It speaks MCP over **stdio**: the client launches it (typically via
+`npx -y gridform-mcp`), exchanges JSON-RPC on stdin/stdout, and calls the tools below.
+
+- **23 engine tools need no API key** — they run the pure, deterministic engine.
+- **6 AI tools** call Anthropic with a key you provide (per call or via the environment);
+  these are the only ones that touch the network.
+
+It does **not** change or require the web app — it's an additional way to drive the same
+engine. Every poster is a reusable **document JSON**: tools return it, and you can pass it
+back to refine, reformat, or export.
+
+## How it renders (headless)
+
+Gridform's core rule is *one* inline SVG is the single source of truth for the preview and
+every export. The MCP honours that: it imports the very same `serializePosterArt` →
+`<PosterArt>` renderer and produces the identical SVG, then rasterises **once** with
+[`resvg`](https://github.com/yisibl/resvg-js). No browser, no second render path.
+
+- **PNG / SVG** — the canonical SVG (PNG = its resvg raster; transparent crops supported).
+- **PDF** — the resvg PNG embedded on a physically-sized page with `pdf-lib` (optional crop
+  + registration marks). **JPG** — the raw resvg pixmap encoded with `jpeg-js`.
+- **Specimen sheets** — many small posters composited into one SVG → one resvg pass.
+- Fonts are the self-hosted `woff2` typefaces that ship inside the package (`fonts/`),
+  embedded as base64 `@font-face`, so output matches the web export exactly. Override the
+  directory with `GRIDFORM_FONTS_DIR`.
+
+## Connect to Claude Desktop
+
+Prerequisites: **Node 20+**. Nothing to clone or build — `npx` fetches the published
+package on first run and caches it.
+
+1. Open the config: Claude Desktop → **Settings → Developer → Edit Config**
+   (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`).
+2. Add the server:
+
+   ```json
+   {
+     "mcpServers": {
+       "gridform": {
+         "command": "npx",
+         "args": ["-y", "gridform-mcp"],
+         "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
+       }
+     }
+   }
+   ```
+
+   `ANTHROPIC_API_KEY` is optional — omit it to use only the 23 no-key engine tools, or
+   pass a key per call via each AI tool's `apiKey` argument.
+3. Restart Claude Desktop. The Gridform tools appear under the tools menu (the 🔌 icon).
+
+## Connect to other clients
+
+Any MCP client that launches a stdio server works: the command is `npx` with args
+`["-y", "gridform-mcp"]` (or `gridform-mcp` directly after a global
+`npm install -g gridform-mcp`). For programmatic use, the official SDK:
+
+```js
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const transport = new StdioClientTransport({ command: 'npx', args: ['-y', 'gridform-mcp'] });
+const client = new Client({ name: 'my-app', version: '1.0.0' });
+await client.connect(transport);
+
+const res = await client.callTool({ name: 'create_poster', arguments: { content: { title: 'Open Studio' }, ratio: '1:1' } });
+// res.content → [ {type:'text', text:'Document JSON…'}, {type:'image', mimeType:'image/png', data:'<base64>'} ]
+```
+
+## The tools
+
+Tools that edit a poster return the new **document JSON** plus a rendered image; most take an
+optional `format` (`png` | `svg`) and `scale` (0.25–8). Engine tools are deterministic — the
+same inputs + `seed` always produce the same poster. Ratios: `3:4 · A4 · 4:5 · 1:1 · 5:7 ·
+16:9 · 1.91:1`.
+
+### Discovery — no key
+
+Browse the design vocabulary (each returns JSON). Pipe the ids into the tools below.
+
+- **`list_layouts`** `{ query?, limit? }` — search the layout library → `{ id, name, tags }`.
+- **`list_looks`** — one-tap aesthetic presets (palette + type + motion).
+- **`list_formats`** `{ category? }` — artboard formats (Paper · Social · Screen · Photo).
+- **`list_palettes`** — built-in palettes + curated themes (paper/ink/muted/accent).
+- **`list_fonts`** `{ query? }` — typeface families (id, category, weights, variable).
+- **`list_vibes`** — the mood "vibes" + mood dimensions.
+
+### Generate — no key
+
+- **`create_poster`** `{ content?, layoutId?, look?, ratio?, seed? }` — a poster from text per
+  slot (`title, headline, subhead, metaA, metaB, caption, logo, footer, dateline, index, body,
+  byline, source`; `\n` for line breaks).
+- **`poster_from_text`** `{ text }` — paste any blob; layout + look + copy chosen automatically.
+- **`generate_layout`** `{ document, seed? }` — synthesize a brand-new content-fit layout.
+- **`bento_poster`** `{ document, seed?, smart?, tries? }` — best-of-N bento grid composition.
+- **`resonate`** `{ document, vibe?, seed? }` — mood-match palette/type/scale (vibes: `bold ·
+  calm · warm · cool · editorial · vintage · minimal · luxe · playful`).
+
+### Vary — no key
+
+- **`shuffle_poster`** `{ document, seed? }` — best-of-N re-roll of the current style.
+- **`surprise_poster`** `{ document, seed? }` — a new layout + fresh style.
+- **`explore_variations`** `{ document, direction?, count?, seed? }` — a graded, diverse
+  shortlist (directions: `surprise · bold · calm · warm · cool · mono · editorial · image ·
+  minimal`). Returns each variant render + its document.
+- **`morph_posters`** `{ documentA, documentB, t?, steps? }` — blend two designs (layout +
+  palette + scale) at `t∈[0,1]`, or `steps` evenly-spaced points.
+
+### Refine — no key
+
+- **`art_direct`** `{ document, strength?, seed? }` — elevate the whole composition to the best
+  variation that is **never worse** than the original (`strength`: `subtle · balanced · bold`).
+- **`critique_poster`** `{ document }` — score (contrast/hierarchy/alignment/balance, 0–100) +
+  located issues.
+- **`harmonize_palette`** `{ baseHex, scheme?, dark?, document? }` — a four-role palette from
+  one hex (`scheme`: `complementary · analogous · triadic · split`); pass a `document` to apply it.
+
+### Format — no key
+
+- **`resize_poster`** `{ document, formatId? | ratio? | width?+height?, orientation?, stretch? }`
+  — adapt the layout to a new format/ratio/custom size (reflows to the new aspect; `stretch`
+  keeps the grid).
+
+### Output — no key
+
+- **`render_poster`** `{ document, format?, scale?, transparent? }` — PNG/SVG (+ transparent
+  sticker crop).
+- **`export_pdf`** `{ document, dpi?, widthMm?, cropMarks? }` — print-ready PDF (returns an
+  embedded `application/pdf` resource), optional trim + registration marks.
+- **`export_jpg`** `{ document, scale?, quality? }` — a JPEG (smaller web file; opaque).
+- **`batch_render`** `{ document, targets[], format?, scale? }` — render to many formats/sizes
+  in one call (each target = a `formatId`, a `ratio`, or `width`+`height`).
+
+### AI — needs an Anthropic key
+
+Pass `apiKey` per call, or set `ANTHROPIC_API_KEY` in the server env. `model?` overrides the
+default. With no key, these return a clear, non-fatal error (no tokens spent).
+
+- **`compose_poster`** `{ brief }` — a brief → AI writes copy, picks a layout + palette.
+- **`design_poster`** `{ brief }` — a full design: also picks the typeface, type scale, and motion.
+- **`write_copy`** `{ kind, context, count? }` — on-brand copy variants (`headline · subhead ·
+  tagline · cta · caption · hashtags · concept`).
+- **`translate_poster`** `{ document, languages }` — localize every line (1–8 **Latin-script**
+  languages) → a document per language.
+- **`brief_to_campaign`** `{ brief, count?, seed? }` — a brief → a designed base, then N on-brand
+  compositional variations (same palette/type, distinct layouts).
+- **`critique_and_fix`** `{ document, strength? }` — the AI tightens the lead line, then the
+  engine applies never-worse art-direction; returns before/after scores + renders.
+
+## Resources & prompts
+
+**Resources** (browse without a tool call):
+
+- `gridform://catalog/{layouts,looks,formats,palettes,fonts,vibes}` — the vocabulary as JSON.
+- `gridform://guide` — this guide.
+- `gridform://specimen/{looks,palettes,fonts}.png` — rendered specimen sheets (PNG).
+- `gridform://specimen/layout/{layoutId}.png` — any single layout rendered (id autocompletes).
+
+**Prompts** (reusable scaffolds):
+
+- `design_brief` `{ topic, audience?, tone? }` — turn a topic into a ready brief.
+- `critique_request` `{ document }` — renders the poster + asks for a design critique.
+- `campaign_plan` `{ brief, channels? }` — a multi-channel campaign request.
+- `localize` `{ document, languages }` — a translation request.
+
+## A worked example
+
+> **You:** Design a poster for a late-night jazz set, then make me a print PDF and an
+> Instagram set.
+
+A capable assistant chains:
+
+1. `design_poster {brief:"a late-night jazz set at a downtown loft"}` → a fully-designed
+   document + PNG. *(or `compose_poster` without a key for copy+layout+palette.)*
+2. `critique_poster {document}` → a score; if needed, `art_direct {document}` to elevate it.
+3. `export_pdf {document, cropMarks:true}` → a print-ready PDF.
+4. `batch_render {document, targets:[{formatId:"social-ig-square"},{formatId:"social-ig-story"}]}`
+   → both Instagram sizes in one call.
+
+No-key flow: `poster_from_text` → `bento_poster` / `shuffle_poster` → `resize_poster` →
+`export_pdf`. To explore directions: `explore_variations {direction:"editorial", count:4}`.
+
+## Determinism, fonts & keys
+
+- **Deterministic.** Engine tools are pure: identical inputs + `seed` always produce the
+  identical poster. Re-render or re-edit any returned `document`.
+- **Fonts.** Output uses the self-hosted typefaces that ship inside the package (`fonts/`);
+  set `GRIDFORM_FONTS_DIR` only to point at a custom directory. The typefaces are
+  open-licensed (OFL / Apache and similar) and remain under their own licences. For CJK /
+  RTL, take the translated copy and apply a matching font yourself.
+- **Keys.** Your Anthropic key is sent directly to Anthropic from the server process, never
+  to any third party. Prefer the `env` block (or per-call `apiKey`) over committing it.
+
+## Developing from source
+
+Working in the Gridform repo itself:
+
+```bash
+cd mcp
+npm install
+npm run build      # → dist/server.mjs (and dist/smoke.mjs); syncs fonts/ + LICENSE
+npm run smoke      # renders SVG/PNG/JPG/PDF + specimen sheets in Node; writes dist/sample.png
+npm test           # spawns the server and drives all tools/resources/prompts over stdio
+```
+
+Point a client at the local build with `"command": "node"` and the absolute path to
+`mcp/dist/server.mjs` in `args`.
+
+## Troubleshooting
+
+- **Tools don't appear** — confirm Node 20+ is on the PATH the client app sees (GUI apps
+  don't always inherit your shell PATH), then fully restart the client. The first run
+  downloads the package (~15 MB) plus its three dependencies and caches them in
+  `~/.npm/_npx`; give it a moment on a slow connection.
+- **"No Anthropic API key"** — set `ANTHROPIC_API_KEY` in the `env` block, or pass `apiKey`.
+- **Blank text in a PNG** — the font directory wasn't found; unset `GRIDFORM_FONTS_DIR`
+  (the packaged `fonts/` is the default) or point it at a directory of woff2 files.
+- **A large batch / PDF is slow or heavy** — lower `scale`, fewer `targets`, or a lower `dpi`.
+- **Protocol errors** — only JSON-RPC may go to stdout; the server logs to stderr by design.
+  Don't pipe other output into stdout.

package/LICENSE

@@ -0,0 +1,31 @@
+Gridform — Proprietary Software License
+Copyright (c) 2026 Gridform (0xDragoon). All rights reserved.
+
+This software, including its source code, design, layouts, generated assets, and
+all associated materials (the "Software"), is the proprietary and confidential
+property of the copyright holder. ALL RIGHTS ARE RESERVED.
+
+No license or right is granted, by implication, estoppel, or otherwise, to use,
+copy, reproduce, modify, merge, publish, distribute, sublicense, sell, rent,
+lease, host, reverse engineer, decompile, disassemble, scrape, or create
+derivative works of the Software, in whole or in part, except with the prior
+express written permission of the copyright holder.
+
+Use of the publicly hosted application is additionally governed by the in-app
+Terms of Use and Privacy Policy.
+
+DISCLAIMER OF WARRANTY. THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE",
+WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT
+LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, TITLE, AND NONINFRINGEMENT.
+
+LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL
+THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, INCLUDING ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING THIRD-PARTY API OR SERVICE CHARGES), WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Third-party names such as "Anthropic" and "Claude" are trademarks of Anthropic,
+and other product names are trademarks of their respective owners; they are used
+for identification only and no affiliation or endorsement is implied.

package/README.md

@@ -0,0 +1,86 @@
+# Gridform MCP server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
+Gridform poster engine to any MCP client (Claude Desktop, IDEs, agents). It generates,
+renders, and translates Swiss-style posters **headlessly in Node** — the same single
+inline SVG the web app renders, rasterised to PNG with [`resvg`](https://github.com/yisibl/resvg-js).
+No browser, no second render path.
+
+Most tools need **no API key**. The AI tools call Anthropic with a key you provide (per call
+or via the environment).
+
+> **New here? Read the [full guide](GUIDE.md)** — setup, Claude Desktop config, every tool
+> with examples, and troubleshooting.
+
+## Use it
+
+With **Node 20+** installed, add the server to any stdio MCP client — nothing to clone or
+build; `npx` fetches the published package on first run and caches it. For Claude Desktop,
+add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`):
+
+```json
+{
+  "mcpServers": {
+    "gridform": {
+      "command": "npx",
+      "args": ["-y", "gridform-mcp"],
+      "env": { "ANTHROPIC_API_KEY": "sk-ant-…" }
+    }
+  }
+}
+```
+
+The `ANTHROPIC_API_KEY` is optional — the engine tools work without it, and the AI tools
+also accept an `apiKey` argument per call. Then ask, e.g. *"make a poster for a jazz night,
+16:9"* or *"translate it into Spanish and French"*.
+
+## Tools (29)
+
+**Discovery** (no key): `list_layouts` · `list_looks` · `list_formats` · `list_palettes` · `list_fonts` · `list_vibes` — browse the design vocabulary.
+
+**Generate** (no key): `create_poster` (text → poster) · `poster_from_text` (paste a blob → a finished poster) · `generate_layout` (synthesize a content-fit layout) · `bento_poster` (best-of-N bento grid) · `resonate` (mood-match palette / type / scale).
+
+**Vary** (no key): `shuffle_poster` · `surprise_poster` · `explore_variations` (a graded shortlist) · `morph_posters` (blend two designs).
+
+**Refine** (no key): `art_direct` (never-worse elevation) · `critique_poster` (score + located issues) · `harmonize_palette` (one hex → four roles).
+
+**Format** (no key): `resize_poster` (adapt the layout to any format / ratio / custom size).
+
+**Output** (no key): `render_poster` (PNG/SVG + transparent crop) · `export_pdf` (print-ready, DPI + crop / registration marks) · `export_jpg` · `batch_render` (many formats in one call).
+
+**AI** (Anthropic key): `compose_poster` · `design_poster` (full design incl. typeface + motion) · `write_copy` · `translate_poster` · `brief_to_campaign` (brief → N on-brand variations) · `critique_and_fix` (AI tightens the copy, the engine art-directs).
+
+Everything renders the **same SVG** the web app uses — PNG/JPG via resvg, PDF via the same resvg PNG embedded with pdf-lib. Deterministic by `seed`.
+
+## Resources & prompts
+
+- **Resources:** JSON catalogs `gridform://catalog/{layouts,looks,formats,palettes,fonts,vibes}`, a `gridform://guide`, rendered **specimen sheets** `gridform://specimen/{looks,palettes,fonts}.png`, and a templated `gridform://specimen/layout/{layoutId}.png` (with id autocompletion).
+- **Prompts:** `design_brief`, `critique_request`, `campaign_plan`, `localize`.
+
+## Developing in this repo
+
+```bash
+cd mcp
+npm install
+npm run build        # bundles dist/server.mjs (+ dist/smoke.mjs) and syncs fonts/ + LICENSE
+npm run smoke        # headless render self-check (writes dist/sample.png)
+npm test             # spawns the server and drives it over stdio
+```
+
+Point a client at the local build with `"command": "node", "args": ["…/mcp/dist/server.mjs"]`
+instead of the npx config.
+
+## Notes
+
+- **Same SVG as the app.** Rendering reuses `serializePosterArt` → `<PosterArt>`; the
+  self-hosted woff2 typefaces ship inside the package (`fonts/`), embedded as base64
+  (override the directory with `GRIDFORM_FONTS_DIR`). PNGs match the web export by
+  construction.
+- **Bundled typefaces.** The `fonts/` woff2 files are open-licensed typefaces (OFL / Apache
+  and similar); they remain under their own licences. The package licence covers the server
+  only.
+- **Latin-script translation.** `translate_poster` targets languages the bundled fonts cover
+  (Spanish, French, German, Portuguese, Italian, …). For CJK / RTL, take the returned copy and
+  set a matching font.
+- **Determinism.** Engine tools are pure: the same inputs + `seed` always produce the same poster.
+- `stdout` is the JSON-RPC channel; all logs go to `stderr`.