@shippp/mcp 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @shippp/mcp
+
+Pull production-perfect Chakra UI code from your Shippp design files straight into your IDE agent (Claude Code, Cursor, …).
+
+## Setup
+
+1. Create an API key in your Shippp workspace settings. It's shown once — copy it.
+2. Add the server to your IDE's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "shippp": {
+      "command": "npx",
+      "args": ["-y", "@shippp/mcp"],
+      "env": {
+        "SHIPPP_API_KEY": "sk_...",
+        "SHIPPP_API_URL": "https://app.shippp.ai"
+      }
+    }
+  }
+}
+```
+
+`SHIPPP_API_URL` is optional (defaults to the Shippp production URL).
+
+## Tools
+
+| Tool | Returns |
+|---|---|
+| `shippp_list_units` | The file's screens + components (id + name). Call first to discover ids. |
+| `shippp_get_component` | One component's Chakra `.tsx`. |
+| `shippp_get_tokens` | The design tokens as a Chakra theme. |
+| `shippp_get_design_system` | The whole design system as a package. |
+| `shippp_get_project` | The whole file as a runnable Next.js project. |
+| `shippp_diff` | Your current code vs a fresh generation. |
+
+Read-only. The server never modifies your design.

package/dist/client.js

@@ -0,0 +1,43 @@
+export class ShipppApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "ShipppApiError";
+    }
+}
+export class ShipppClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(path, init) {
+        let res;
+        try {
+            res = await fetch(`${this.config.apiUrl}${path}`, {
+                ...init,
+                headers: {
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                    "Content-Type": "application/json",
+                    ...(init.headers ?? {}),
+                },
+            });
+        }
+        catch (e) {
+            throw new ShipppApiError(0, `Could not reach Shippp at ${this.config.apiUrl}: ${e.message}`);
+        }
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new ShipppApiError(res.status, body?.error || `HTTP ${res.status}`);
+        return body;
+    }
+    manifest(fileId) {
+        return this.request(`/api/mcp/manifest?fileId=${encodeURIComponent(fileId)}`, { method: "GET" });
+    }
+    generate(fileId, request, baseline) {
+        return this.request("/api/mcp/generate", {
+            method: "POST",
+            body: JSON.stringify(baseline ? { fileId, request, baseline } : { fileId, request }),
+        });
+    }
+}

package/dist/config.js

@@ -0,0 +1,11 @@
+const DEFAULT_API_URL = "https://app.shippp.ai";
+export function loadConfig() {
+    const apiKey = process.env.SHIPPP_API_KEY?.trim();
+    if (!apiKey) {
+        console.error("[shippp-mcp] SHIPPP_API_KEY is not set. Mint a key in your Shippp workspace " +
+            "settings and add it to the MCP server's `env` in your IDE config.");
+        process.exit(1);
+    }
+    const apiUrl = (process.env.SHIPPP_API_URL?.trim() || DEFAULT_API_URL).replace(/\/+$/, "");
+    return { apiUrl, apiKey };
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { ShipppClient } from "./client.js";
+import { registerTools } from "./tools.js";
+const INSTRUCTIONS = `Shippp exposes DETERMINISTIC, production-perfect Chakra UI code from a designer's Shippp file. Everything returned is GENERATED (never guessed) and reproducible — the same source always yields the same code + hash (see each result's receipt).
+
+Workflow: call shippp_list_units first to discover screen/master ids, then pull code with shippp_get_component / shippp_get_tokens / shippp_get_design_system / shippp_get_project. Write the returned "=== FILE: <path> ===" blocks to those paths. Do NOT hand-edit generated code to reflect a design change — change the design in Shippp and regenerate. Use shippp_diff to see exactly what a designer changed since your current code.`;
+async function main() {
+    const config = loadConfig();
+    const server = new McpServer({ name: "shippp", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+    registerTools(server, new ShipppClient(config));
+    await server.connect(new StdioServerTransport());
+    console.error(`[shippp-mcp] connected via stdio → ${config.apiUrl}`);
+}
+main().catch((e) => {
+    console.error("[shippp-mcp] fatal:", e);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { ShipppApiError } from "./client.js";
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+const fail = (s) => ({ content: [{ type: "text", text: s }], isError: true });
+function errText(e) {
+    if (e instanceof ShipppApiError) {
+        const hint = e.status === 401 ? " — check SHIPPP_API_KEY." : "";
+        return `Error ${e.status}: ${e.message}${hint}`;
+    }
+    return `Error: ${e.message}`;
+}
+function renderFiles(result) {
+    const files = result.files.map((f) => `=== FILE: ${f.path} ===\n${f.content}`).join("\n\n");
+    return `${files}\n\n--- RECEIPT (reproducible: ${result.receipt.reproducible}, engine: ${result.receipt.config.engine}) ---\n${JSON.stringify(result.receipt, null, 2)}`;
+}
+function renderDiff(result) {
+    const changed = result.changed_files.map((f) => `${f.status}\t${f.path}`).join("\n");
+    return `changed: ${result.changed}\n\n${result.diff || "(no changes)"}\n\n--- files ---\n${changed}\n\n--- RECEIPT ---\n${JSON.stringify(result.receipt, null, 2)}`;
+}
+const fileId = z.string().min(1).describe("The Shippp file id (from the file's URL, or shippp_list_units).");
+export function registerTools(server, client) {
+    server.registerTool("shippp_list_units", {
+        description: "List a Shippp file's screens and master components (id + name). Call this FIRST to discover the ids for shippp_get_component.",
+        inputSchema: { fileId },
+    }, async ({ fileId }) => {
+        try {
+            const { manifest } = await client.manifest(fileId);
+            return text(JSON.stringify(manifest, null, 2));
+        }
+        catch (e) {
+            return fail(errText(e));
+        }
+    });
+    server.registerTool("shippp_get_component", {
+        description: "Get ONE component's deterministic Chakra UI code + a reproducibility receipt. `unitType` is 'master' (a design-system component) or 'screen' (a depth-0 artboard). Get ids from shippp_list_units.",
+        inputSchema: {
+            fileId,
+            unitId: z.string().min(1).describe("The master/screen id from shippp_list_units."),
+            unitType: z.enum(["master", "screen"]),
+        },
+    }, async ({ fileId, unitId, unitType }) => {
+        try {
+            return text(renderFiles((await client.generate(fileId, { unit: "component", unitId, unitType }))));
+        }
+        catch (e) {
+            return fail(errText(e));
+        }
+    });
+    server.registerTool("shippp_get_tokens", {
+        description: "Get the design system's tokens as a Chakra theme (createSystem) + receipt.",
+        inputSchema: { fileId },
+    }, async ({ fileId }) => {
+        try {
+            return text(renderFiles((await client.generate(fileId, { unit: "tokens" }))));
+        }
+        catch (e) {
+            return fail(errText(e));
+        }
+    });
+    server.registerTool("shippp_get_design_system", {
+        description: "Get the whole design system as a publishable package (tokens + theme + recipes + every component + stories + package.json).",
+        inputSchema: { fileId },
+    }, async ({ fileId }) => {
+        try {
+            return text(renderFiles((await client.generate(fileId, { unit: "design-system" }))));
+        }
+        catch (e) {
+            return fail(errText(e));
+        }
+    });
+    server.registerTool("shippp_get_project", {
+        description: "Get the whole file as a runnable Next.js project (screens as pages + the design system).",
+        inputSchema: { fileId },
+    }, async ({ fileId }) => {
+        try {
+            return text(renderFiles((await client.generate(fileId, { unit: "project" }))));
+        }
+        catch (e) {
+            return fail(errText(e));
+        }
+    });
+    server.registerTool("shippp_diff", {
+        description: "Diff your CURRENT code against a fresh deterministic generation of a unit — shows exactly what a designer changed. Pass the same unit params as the get tools, plus `baseline` (the files you currently have for that unit).",
+        inputSchema: {
+            fileId,
+            unit: z.enum(["tokens", "design-system", "project", "component"]),
+            unitId: z.string().optional().describe("Required when unit='component'."),
+            unitType: z.enum(["master", "screen"]).optional().describe("Required when unit='component'."),
+            baseline: z
+                .array(z.object({ path: z.string(), content: z.string() }))
+                .describe("Your current files for this unit (path + content)."),
+        },
+    }, async ({ fileId, unit, unitId, unitType, baseline }) => {
+        try {
+            let request;
+            if (unit === "component") {
+                if (!unitId || !unitType)
+                    return fail("unit='component' requires unitId + unitType.");
+                request = { unit, unitId, unitType };
+            }
+            else {
+                request = { unit };
+            }
+            return text(renderDiff((await client.generate(fileId, request, baseline))));
+        }
+        catch (e) {
+            return fail(errText(e));
+        }
+    });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@shippp/mcp",
+  "version": "0.1.0",
+  "description": "Shippp MCP server — pull deterministic, production-perfect Chakra UI code from your Shippp design files, straight into your IDE agent.",
+  "type": "module",
+  "bin": {
+    "shippp-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "rm -rf dist && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "shippp",
+    "chakra-ui",
+    "design-to-code"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}