tabbied-mcp 0.2.2 → 0.2.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Sy Hong and Ye Joo Park
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, 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.
+MIT License
+
+Copyright (c) 2026 Sy Hong and Ye Joo Park
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, 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.

package/README.md

@@ -1,83 +1,147 @@
-# tabbied-mcp
-
-An [MCP](https://modelcontextprotocol.io) server for
-[Tabbied](https://tabbied.com): search 338 generative pattern designs, look at
-them, and render them to SVG or PNG - from Claude Code, Claude Desktop, Cursor,
-or any other MCP client.
-
-## Use it without installing anything
-
-The same server runs at `https://tabbied.com/mcp`:
-
-```bash
-claude mcp add --transport http tabbied https://tabbied.com/mcp
-```
-
-```jsonc
-{
-  "mcpServers": {
-    "tabbied": { "url": "https://tabbied.com/mcp" }
-  }
-}
-```
-
-## Or run it locally, and render real files
-
-```bash
-claude mcp add tabbied -- npx -y tabbied-mcp
-```
-
-```jsonc
-{
-  "mcpServers": {
-    "tabbied": { "command": "npx", "args": ["-y", "tabbied-mcp"] }
-  }
-}
-```
-
-The local server adds `render_design`, which the remote one cannot offer -
-rendering a css-doodle pattern needs a real browser. Install a Playwright
-alongside it (`npm i -D playwright`) or point `TABBIED_CHROMIUM` at a Chromium
-binary.
-
-## Tools
-
-| Tool | What it does |
-| --- | --- |
-| `search_designs` | Filter by motif, mood, density, intended use, free text, or SVG-export support. |
-| `get_design` | The full record for one slug, plus ready-to-paste snippets. |
-| `preview_design` | The rendered preview image for up to six designs, so the model can *look*. |
-| `get_docs` | The complete API reference (`llms-full.txt`). |
-| `render_design` | SVG or PNG at any size, seed, palette, and option set. **Local only.** |
-
-Slugs are opaque - `cleat`, `karst`, `radius` - so the intended flow is
-`search_designs` to narrow, `preview_design` to look, then `get_design` for the
-options. Choosing off tags alone is the main way this goes wrong.
-
-## Programmatic use
-
-The package's main entry point is runtime-agnostic (no node imports), so it can
-be embedded in a Worker or any Web-standard server. It exposes the tools and an
-`McpServer` factory; the transport is the MCP SDK's:
-
-```ts
-import { createMcpHandler } from '@modelcontextprotocol/server';
-import { buildServer, catalogTools } from 'tabbied-mcp';
-
-const tools = catalogTools({ catalog, fetchPreview, fetchDocs });
-
-export default {
-  fetch: createMcpHandler(() => buildServer(tools)).fetch,
-};
-```
-
-Pass the *factory*, not a built server: MCP v2 is stateless and the handler
-constructs one server per request.
-
-Built on [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
-v2, so it speaks the stateless `2026-07-28` revision and still serves 2025-era
-clients. `docs/mcp-server.md` in the repository has the details.
-
-## License
-
-MIT
+# tabbied-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for
+[Tabbied](https://tabbied.com): search 338 generative pattern designs, look at
+them, and render them to SVG or PNG - from Claude Code, Claude Desktop, Cursor,
+or any other MCP client.
+
+## Use it without installing anything
+
+The same server runs at `https://tabbied.com/mcp`, with no account or key:
+
+```bash
+claude mcp add --transport http tabbied https://tabbied.com/mcp   # Claude Code
+codex mcp add tabbied --url https://tabbied.com/mcp               # Codex
+```
+
+- **Claude** (web and desktop): Customize, Connectors, + Add, Add custom
+  connector; enter the URL and choose "No sign in".
+- **ChatGPT**: turn on Developer mode (Settings, Security and login), then add
+  it under [Plugins](https://chatgpt.com/plugins) with the URL as a public
+  endpoint. ChatGPT reaches hosted servers only.
+- **Codex**: the command above, or `[mcp_servers.tabbied]` with
+  `url = "https://tabbied.com/mcp"` in `~/.codex/config.toml`, which the CLI,
+  the IDE extension and the ChatGPT desktop app share.
+- **Cursor** and other clients that read an `mcpServers` JSON file (VS Code's
+  `.vscode/mcp.json` uses `servers` with `"type": "http"` instead):
+
+```jsonc
+{
+  "mcpServers": {
+    "tabbied": { "url": "https://tabbied.com/mcp" }
+  }
+}
+```
+
+## Or run it locally, and render real files
+
+The local server adds `render_design`, which the remote one cannot offer:
+rendering a css-doodle pattern needs a real browser. It drives Chromium through
+Playwright, which this package does not install, so start the server with
+Playwright beside it, and download the browser once:
+
+```bash
+npx playwright install chromium
+
+claude mcp add tabbied -- npx -y -p tabbied-mcp -p playwright tabbied-mcp   # Claude Code
+codex mcp add tabbied -- npx -y -p tabbied-mcp -p playwright tabbied-mcp    # Codex
+```
+
+Claude Desktop (`claude_desktop_config.json`), Cursor and other clients that
+start local servers from JSON:
+
+```jsonc
+{
+  "mcpServers": {
+    "tabbied": {
+      "command": "npx",
+      "args": ["-y", "-p", "tabbied-mcp", "-p", "playwright", "tabbied-mcp"]
+    }
+  }
+}
+```
+
+A Playwright installed in the project the server starts in is found too
+(`npm i -D playwright`), and `TABBIED_CHROMIUM` points it at a Chromium binary
+of your own. Without either, `npx -y tabbied-mcp` serves the other six tools,
+and `render_design` says what to install. Needs Node 20 or later.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `search_designs` | Filter by motif, mood, density, intended use, free text, or SVG-export support. |
+| `get_design` | The full record for one slug, plus ready-to-paste snippets. |
+| `preview_design` | The rendered preview image for up to six designs, so the model can *look*. |
+| `get_docs` | The complete API reference (`llms-full.txt`). |
+| `list_templates` | The Tabbied website templates, a page at a time, filtered by category or by words. |
+| `get_template` | One template's editable-section spec, its download links, and how to edit each format. |
+| `render_design` | SVG or PNG at any size, seed, palette, and option set. **Local only.** |
+
+Slugs are opaque - `cleat`, `karst`, `radius` - so the intended flow is
+`search_designs` to narrow, `preview_design` to look, then `get_design` for the
+options. Choosing off tags alone is the main way this goes wrong.
+
+The website templates are licensed per Tabbied account, not with this package:
+downloading one needs an account that has chosen it, under the
+[Template License](https://tabbied.com/terms-of-service/#template-license).
+
+Setup for each client, the tools and example prompts are also on
+[tabbied.com/docs/mcp](https://tabbied.com/docs/mcp/).
+
+## Programmatic use
+
+The package is ESM only (the `tabbied-mcp` bin is unaffected). Its main entry
+point is runtime-agnostic (no node imports), so it can be embedded in a Worker
+or any Web-standard server. It exposes the tools and an `McpServer` factory;
+the transport is the MCP SDK's. On Node, `tabbied-mcp/node` has the readers the
+bin itself uses:
+
+```ts
+import { createMcpHandler } from '@modelcontextprotocol/server';
+import { buildServer, catalogTools } from 'tabbied-mcp';
+import {
+  fetchDocs,
+  fetchPreview,
+  fetchTemplate,
+  fetchTemplateCatalog,
+  loadCatalog,
+} from 'tabbied-mcp/node';
+
+const tools = catalogTools({
+  catalog: await loadCatalog(),
+  fetchPreview,
+  fetchDocs,
+  fetchTemplateCatalog,
+  fetchTemplate,
+});
+
+// A Web-standard fetch handler, for Bun.serve, Deno.serve or a Node adapter.
+export default {
+  fetch: createMcpHandler(() => buildServer(tools)).fetch,
+};
+```
+
+Pass the *factory*, not a built server: MCP v2 is stateless and the handler
+constructs one server per request.
+
+Only `catalog` is required. Each fetcher adds tools, and one left out drops
+them: `fetchPreview` gives `preview_design`, `fetchDocs` gives `get_docs`,
+`fetchTemplateCatalog` gives `list_templates`, and with `fetchTemplate` as
+well, `get_template`. With all five, as above, it serves the same six tools as
+the hosted server at `https://tabbied.com/mcp`. `renderTool(catalog)`, also
+from `tabbied-mcp/node`, is `render_design`, for a host with a browser.
+
+The Node readers take the catalog and the docs from the installed `tabbied`
+package and the rest from tabbied.com. A Worker cannot use them, so it passes
+its own: each is an async function returning the same JSON (`Catalog`,
+`TemplateCatalog` and the rest are exported types), and the hosted server's
+read its own static assets.
+
+Built on [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
+v2, so it speaks the stateless `2026-07-28` revision and still serves 2025-era
+clients. `docs/mcp-server.md` in the repository has the details.
+
+## License
+
+MIT

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC","sourcesContent":["// The runtime-agnostic half of the server: the tool definitions and the\r\n// `McpServer` factory. Nothing reachable from here may import node, because\r\n// this entry point is what the Cloudflare Worker bundles; the local catalog\r\n// reader and `render_design` live behind the bin. See docs/mcp-server.md.\r\nexport { buildServer } from './server.js';\r\nexport { catalogTools, createToolset, type Toolset } from './tools.js';\r\nexport { templateTools } from './templates.js';\r\nexport { INSTRUCTIONS, SERVER_NAME, VERSION } from './info.js';\r\nexport type {\r\n  Catalog,\r\n  CatalogDesign,\r\n  CatalogOption,\r\n  TemplateCatalog,\r\n  TemplateCatalogEntry,\r\n  TemplateSpec,\r\n  Tool,\r\n  ToolContent,\r\n  ToolContext,\r\n  ToolDefinition,\r\n  ToolResult,\r\n} from './types.js';\r\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC","sourcesContent":["// The runtime-agnostic half of the server: the tool definitions and the\n// `McpServer` factory. Nothing reachable from here may import node, because\n// this entry point is what the Cloudflare Worker bundles; the local catalog\n// reader and `render_design` live behind the bin. See docs/mcp-server.md.\nexport { buildServer } from './server.js';\nexport { catalogTools, createToolset, type Toolset } from './tools.js';\nexport { templateTools } from './templates.js';\nexport { INSTRUCTIONS, SERVER_NAME, VERSION } from './info.js';\nexport type {\n  Catalog,\n  CatalogDesign,\n  CatalogOption,\n  TemplateCatalog,\n  TemplateCatalogEntry,\n  TemplateSpec,\n  Tool,\n  ToolContent,\n  ToolContext,\n  ToolDefinition,\n  ToolResult,\n} from './types.js';\n"]}

package/dist/info.d.ts

@@ -1,5 +1,5 @@
 export declare const SERVER_NAME = "tabbied";
-export declare const VERSION = "0.2.2";
+export declare const VERSION = "0.2.4";
 /**
  * Shown to the model as a preamble. It carries what no tool description can,
  * because they are properties of the *set* rather than of one call: slugs

package/dist/info.js

@@ -1,10 +1,11 @@
 // Server identity and the instructions clients hand to the model.
 //
 // VERSION is a literal rather than a package.json read because this module is
-// bundled into a Cloudflare Worker, which has no filesystem. test/info.test.mjs
-// pins it to package.json so the two can't drift.
+// bundled into a Cloudflare Worker, which has no filesystem. The release's
+// `version-packages` step rewrites it from package.json
+// (scripts/sync-version.mjs), and test/info.test.mjs pins the two together.
 export const SERVER_NAME = 'tabbied';
-export const VERSION = '0.2.2';
+export const VERSION = '0.2.4';
 /**
  * Shown to the model as a preamble. It carries what no tool description can,
  * because they are properties of the *set* rather than of one call: slugs
@@ -12,11 +13,11 @@ export const VERSION = '0.2.2';
  * sizing rule is the most common way a correct-looking integration renders as
  * nothing.
  */
-export const INSTRUCTIONS = `Tabbied is a catalog of generative patterns (css-doodle) usable as backgrounds, textures, posters, and exported SVG/PNG assets.
-
-Designs are addressed by slug, and slugs are opaque - "cleat", "karst", "radius" say nothing about what they look like. Never guess one: call search_designs, which filters on a closed vocabulary of motifs, moods, density, and intended use.
-
-Metadata narrows the field; it does not settle it. These are pictures, so call preview_design on your shortlist and look before you commit. Choosing off tags alone is the main way this goes wrong.
-
+export const INSTRUCTIONS = `Tabbied is a catalog of generative patterns (css-doodle) usable as backgrounds, textures, posters, and exported SVG/PNG assets.
+
+Designs are addressed by slug, and slugs are opaque - "cleat", "karst", "radius" say nothing about what they look like. Never guess one: call search_designs, which filters on a closed vocabulary of motifs, moods, density, and intended use.
+
+Metadata narrows the field; it does not settle it. These are pictures, so call preview_design on your shortlist and look before you commit. Choosing off tags alone is the main way this goes wrong.
+
 When you write integration code, remember a pattern has no intrinsic size: it fills its parent and collapses to nothing in a parent that sizes to content. Pass height or aspectRatio unless the parent is definitely sized. get_docs has the full API contract and recipes.`;
 //# sourceMappingURL=info.js.map

package/dist/info.js.map

@@ -1 +1 @@
-{"version":3,"file":"info.js","sourceRoot":"","sources":["../src/info.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,kDAAkD;AAClD,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;6QAMiP,CAAC","sourcesContent":["// Server identity and the instructions clients hand to the model.\r\n//\r\n// VERSION is a literal rather than a package.json read because this module is\r\n// bundled into a Cloudflare Worker, which has no filesystem. test/info.test.mjs\r\n// pins it to package.json so the two can't drift.\r\nexport const SERVER_NAME = 'tabbied';\r\nexport const VERSION = '0.2.2';\r\n\r\n/**\r\n * Shown to the model as a preamble. It carries what no tool description can,\r\n * because they are properties of the *set* rather than of one call: slugs\r\n * cannot be guessed, the previews are what a choice should rest on, and the\r\n * sizing rule is the most common way a correct-looking integration renders as\r\n * nothing.\r\n */\r\nexport const INSTRUCTIONS = `Tabbied is a catalog of generative patterns (css-doodle) usable as backgrounds, textures, posters, and exported SVG/PNG assets.\r\n\r\nDesigns are addressed by slug, and slugs are opaque - \"cleat\", \"karst\", \"radius\" say nothing about what they look like. Never guess one: call search_designs, which filters on a closed vocabulary of motifs, moods, density, and intended use.\r\n\r\nMetadata narrows the field; it does not settle it. These are pictures, so call preview_design on your shortlist and look before you commit. Choosing off tags alone is the main way this goes wrong.\r\n\r\nWhen you write integration code, remember a pattern has no intrinsic size: it fills its parent and collapses to nothing in a parent that sizes to content. Pass height or aspectRatio unless the parent is definitely sized. get_docs has the full API contract and recipes.`;\r\n"]}
+{"version":3,"file":"info.js","sourceRoot":"","sources":["../src/info.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,wDAAwD;AACxD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;6QAMiP,CAAC","sourcesContent":["// Server identity and the instructions clients hand to the model.\n//\n// VERSION is a literal rather than a package.json read because this module is\n// bundled into a Cloudflare Worker, which has no filesystem. The release's\n// `version-packages` step rewrites it from package.json\n// (scripts/sync-version.mjs), and test/info.test.mjs pins the two together.\nexport const SERVER_NAME = 'tabbied';\nexport const VERSION = '0.2.4';\n\n/**\n * Shown to the model as a preamble. It carries what no tool description can,\n * because they are properties of the *set* rather than of one call: slugs\n * cannot be guessed, the previews are what a choice should rest on, and the\n * sizing rule is the most common way a correct-looking integration renders as\n * nothing.\n */\nexport const INSTRUCTIONS = `Tabbied is a catalog of generative patterns (css-doodle) usable as backgrounds, textures, posters, and exported SVG/PNG assets.\n\nDesigns are addressed by slug, and slugs are opaque - \"cleat\", \"karst\", \"radius\" say nothing about what they look like. Never guess one: call search_designs, which filters on a closed vocabulary of motifs, moods, density, and intended use.\n\nMetadata narrows the field; it does not settle it. These are pictures, so call preview_design on your shortlist and look before you commit. Choosing off tags alone is the main way this goes wrong.\n\nWhen you write integration code, remember a pattern has no intrinsic size: it fills its parent and collapses to nothing in a parent that sizes to content. Pass height or aspectRatio unless the parent is definitely sized. get_docs has the full API contract and recipes.`;\n"]}

package/dist/node/index.d.ts

@@ -0,0 +1,2 @@
+export { fetchDocs, fetchPreview, fetchTemplate, fetchTemplateCatalog, loadCatalog, tabbiedRoot, } from './resources.js';
+export { renderTool } from './render.js';

package/dist/node/index.js

@@ -0,0 +1,7 @@
+// The Node half, for hosts that run on Node rather than a Worker: what the
+// `tabbied-mcp` bin itself passes to `catalogTools`, plus `render_design`.
+// Kept off the main entry point, which a Worker bundles and which must stay
+// free of node imports (see ../index.ts).
+export { fetchDocs, fetchPreview, fetchTemplate, fetchTemplateCatalog, loadCatalog, tabbiedRoot, } from './resources.js';
+export { renderTool } from './render.js';
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,0CAA0C;AAC1C,OAAO,EACL,SAAS,EACT,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC","sourcesContent":["// The Node half, for hosts that run on Node rather than a Worker: what the\n// `tabbied-mcp` bin itself passes to `catalogTools`, plus `render_design`.\n// Kept off the main entry point, which a Worker bundles and which must stay\n// free of node imports (see ../index.ts).\nexport {\n  fetchDocs,\n  fetchPreview,\n  fetchTemplate,\n  fetchTemplateCatalog,\n  loadCatalog,\n  tabbiedRoot,\n} from './resources.js';\nexport { renderTool } from './render.js';\n"]}