@getflip/swirl-mcp 0.3.0 → 0.4.0

package/README.md

@@ -32,12 +32,17 @@ Add to your MCP settings:
 }
 ```
 
-## Local testing
+## Local development
+
+Inspect the server with the
+[MCP Inspector](https://github.com/modelcontextprotocol/inspector) over either
+transport. Prepend `SWIRL_AI_LOCAL=1` to either command to load artifacts
+from the local monorepo instead of the unpkg CDN.
 
 ### stdio
 
 ```sh
-npx @modelcontextprotocol/inspector node dist/transports/stdio.js
+SWIRL_AI_LOCAL=1 npx @modelcontextprotocol/inspector node dist/transports/stdio.js
 ```
 
 ### HTTP
@@ -46,20 +51,31 @@ Start the server, then open the Inspector and connect with transport type
 "Streamable HTTP" and URL `http://localhost:3000/mcp`:
 
 ```sh
-npx tsx src/transports/http.ts
+SWIRL_AI_LOCAL=1 npx tsx src/transports/http.ts
 npx @modelcontextprotocol/inspector
 ```
 
+### `SWIRL_AI_LOCAL`
+
+When set, agent artifacts are read from `packages/swirl-ai/dist/agent` and
+component source (`get_component_source`) is read from
+`packages/swirl-components/src/components/<tag>/<tag>.{tsx,css}`. The
+`version` parameter is ignored for cache keying. Make sure swirl-ai has been
+built (`pnpm --filter @getflip/swirl-ai build`).
+
 ## Tools
 
-| Tool                      | Description                                                                  |
-| ------------------------- | ---------------------------------------------------------------------------- |
-| **list_components**       | Lists all Swirl UI components with brief summaries and related components.   |
-| **list_icons**            | Lists all Swirl icon components.                                             |
-| **list_symbols**          | Lists all Swirl symbol components.                                           |
-| **get_component_details** | Full component docs: props, events, slots, examples, and accessibility info. |
-| **get_component_source**  | Versioned original TSX and CSS source for a specific component.              |
-| **get_started**           | Installation and setup guide for Web Components, Angular, and React.         |
+| Tool                         | Description                                                                  |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| **list_components**          | Lists all Swirl UI components with brief summaries and related components.   |
+| **list_icons**               | Lists all Swirl icon components.                                             |
+| **list_symbols**             | Lists all Swirl symbol components.                                           |
+| **get_component_details**    | Full component docs: props, events, slots, examples, and accessibility info. |
+| **get_component_source**     | Versioned original TSX and CSS source for a specific component.              |
+| **list_color_tokens**        | Lists Swirl color tokens (light + dark) as CSS / SCSS / Tailwind keys.       |
+| **list_typography_tokens**   | Lists Swirl typography tokens as CSS / SCSS / Tailwind keys.                 |
+| **list_layout_tokens**       | Lists Swirl layout tokens (spacing, radius, shadow, z-index, blur).          |
+| **get_started**              | Installation and setup guide for Web Components, Angular, and React.         |
 
 All tools accept a `version` parameter matching the installed
 `@getflip/swirl-components` version.

package/dist/{chunk-HWC76PLD.js → chunk-QVNIVXYL.js}

@@ -3,8 +3,67 @@
 // src/create-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+// package.json
+var package_default = {
+  name: "@getflip/swirl-mcp",
+  version: "0.4.0",
+  description: "MCP server for Swirl Design System \u2014 lets AI agents discover and use Swirl components",
+  author: "Flip GmbH",
+  repository: {
+    type: "git",
+    url: "https://github.com/getflip/swirl"
+  },
+  license: "SEE LICENSE IN LICENSE.md",
+  bugs: {
+    url: "https://github.com/getflip/swirl/issues"
+  },
+  type: "module",
+  bin: {
+    "swirl-mcp": "dist/transports/stdio.js"
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  scripts: {
+    build: "tsup",
+    start: "node dist/transports/http.js",
+    dev: "tsx src/transports/stdio.ts",
+    "dev:server": "tsx src/transports/http.ts",
+    lint: "tsc --noEmit"
+  },
+  tsup: {
+    entry: {
+      "transports/stdio": "src/transports/stdio.ts",
+      "transports/http": "src/transports/http.ts"
+    },
+    format: [
+      "esm"
+    ],
+    target: "node18",
+    outDir: "dist",
+    clean: true,
+    banner: {
+      js: "#!/usr/bin/env node"
+    }
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    zod: "3.24.0"
+  },
+  devDependencies: {
+    "@types/node": "25.3.0",
+    tsup: "^8.0.0",
+    tsx: "^4.7.0",
+    typescript: "5.9.3"
+  }
+};
+
 // src/data-source.ts
-var DataSource = class {
+import { readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+var RemoteDataSource = class {
   constructor(version) {
     this.version = version;
   }
@@ -48,14 +107,43 @@ var DataSource = class {
     return `https://raw.githubusercontent.com/getflip/swirl/@getflip/swirl-components@${this.version}`;
   }
 };
+var LocalDataSource = class {
+  async readJson(relativePath) {
+    return JSON.parse(readFileSync(this.agentPath(relativePath), "utf8"));
+  }
+  async readText(relativePath) {
+    try {
+      return readFileSync(this.agentPath(relativePath), "utf8");
+    } catch {
+      return void 0;
+    }
+  }
+  async readComponentSource(tag) {
+    const componentDir = join(packagesDir, "swirl-components", "src", "components", tag);
+    const read = (ext) => {
+      try {
+        return readFileSync(join(componentDir, `${tag}.${ext}`), "utf8");
+      } catch {
+        return void 0;
+      }
+    };
+    return { tsx: read("tsx"), css: read("css") };
+  }
+  agentPath(relativePath) {
+    return join(packagesDir, "swirl-ai", "dist", "agent", relativePath);
+  }
+};
+var packagesDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 // src/artifact-library.ts
 var ArtifactLibrary = class _ArtifactLibrary {
   catalog;
   tagIndex;
+  tokens;
   dataSource;
-  constructor(catalog, dataSource) {
+  constructor(catalog, tokens, dataSource) {
     this.catalog = catalog;
+    this.tokens = tokens;
     this.dataSource = dataSource;
     this.tagIndex = /* @__PURE__ */ new Map();
     for (const entry of this.catalog) {
@@ -66,11 +154,15 @@ var ArtifactLibrary = class _ArtifactLibrary {
    * Load artifacts from a remote base URL (CDN).
    */
   static async fromRemote(version) {
-    const ds = new DataSource(version);
-    const json = await ds.readJson(
-      "components-index.json"
-    );
-    return new _ArtifactLibrary(json.components, ds);
+    return _ArtifactLibrary.fromDataSource(new RemoteDataSource(version));
+  }
+  /**
+   * Load artifacts from the local monorepo (`packages/swirl-ai/dist` and
+   * `packages/swirl-components/src`) for development against an unpublished
+   * swirl-ai build.
+   */
+  static async fromLocal() {
+    return _ArtifactLibrary.fromDataSource(new LocalDataSource());
   }
   getByCategory(category) {
     return this.catalog.filter((c) => categorize(c.tag) === category);
@@ -87,6 +179,16 @@ var ArtifactLibrary = class _ArtifactLibrary {
   async getGuide(name) {
     return this.dataSource.readText(`${name}.md`);
   }
+  getTokensByCategory(category) {
+    return this.tokens[category];
+  }
+  static async fromDataSource(dataSource) {
+    const [components, tokens] = await Promise.all([
+      dataSource.readJson("components-index.json"),
+      dataSource.readJson("tokens.json")
+    ]);
+    return new _ArtifactLibrary(components.components, tokens, dataSource);
+  }
 };
 function categorize(tag) {
   if (tag.startsWith("swirl-icon-")) {
@@ -307,19 +409,108 @@ function registerListTool(server, loadLibrary2, name, description, category) {
   );
 }
 
+// src/tools/list-tokens.ts
+import { z as z5 } from "zod";
+var VERSION_DESCRIPTION5 = "The @getflip/swirl-components version installed in the project. Read the user's package.json or node_modules/@getflip/swirl-components/package.json to find this.";
+var FORMAT_DESCRIPTION = "Output format for the token key. 'css' - CSS custom property. 'scss' - SCSS variable. 'tailwind' - returns `key: '{name}'` + `namespace` (e.g. 'colors', 'fontSize', 'spacing') so the agent can build the right utility class. Pick the format that matches the project's styling stack.";
+function registerListColorTokens(server, loadLibrary2) {
+  registerListTokensTool(
+    server,
+    loadLibrary2,
+    "list_color_tokens",
+    "List Swirl color tokens with light + dark values. Pass 'format' to choose css / scss / tailwind output. For tailwind, all colors use the 'colors' namespace (e.g. `text-{name}`, `bg-{name}`, `border-{name}`). Prefer these over hard-coded hex/rgb values.",
+    "colors"
+  );
+}
+function registerListTypographyTokens(server, loadLibrary2) {
+  registerListTokensTool(
+    server,
+    loadLibrary2,
+    "list_typography_tokens",
+    "List Swirl typography tokens. Pass 'format' to choose css / scss / tailwind output. Prefer these over ad-hoc font sizes/weights.",
+    "typography"
+  );
+}
+function registerListLayoutTokens(server, loadLibrary2) {
+  registerListTokensTool(
+    server,
+    loadLibrary2,
+    "list_layout_tokens",
+    "List Swirl layout tokens (spacing, border radius, border width, box shadows, z-index, blur). Pass 'format' to choose css / scss / tailwind output. Prefer these over arbitrary px/rem values.",
+    "layout"
+  );
+}
+function registerListTokensTool(server, loadLibrary2, name, description, category) {
+  server.registerTool(
+    name,
+    {
+      description,
+      inputSchema: {
+        version: z5.string().describe(VERSION_DESCRIPTION5),
+        format: z5.enum(["css", "scss", "tailwind"]).describe(FORMAT_DESCRIPTION)
+      }
+    },
+    // @ts-ignore - MCP SDK + zod 3.x causes excessively deep type instantiation
+    async ({ version, format }) => {
+      const lib = await loadLibrary2(version);
+      const tokens = lib.getTokensByCategory(category);
+      const formatted = tokens.map((t) => formatToken(t, format)).filter((t) => t !== null);
+      return {
+        content: [{ type: "text", text: JSON.stringify(formatted) }]
+      };
+    }
+  );
+}
+function formatToken(token, format) {
+  if (format === "tailwind" && !token.tailwindNamespace) {
+    return null;
+  }
+  const out = { key: tokenKey(token, format) };
+  if (format === "tailwind") {
+    out.namespace = token.tailwindNamespace;
+  }
+  if (token.valueLight !== void 0) {
+    out.valueLight = token.valueLight;
+    out.valueDark = token.valueDark;
+  } else if (token.value !== void 0) {
+    out.value = token.value;
+  }
+  if (token.description) {
+    out.description = token.description;
+  }
+  return out;
+}
+function tokenKey(token, format) {
+  switch (format) {
+    case "css":
+      return `--s-${token.name}`;
+    case "scss":
+      return `$s-${token.name}`;
+    case "tailwind":
+      return token.name;
+  }
+}
+
 // src/create-server.ts
 var cache = new LibraryCache();
+var useLocal = Boolean(process.env.SWIRL_AI_LOCAL);
 async function loadLibrary(version) {
-  const cached = cache.get(version);
+  const cacheKey = useLocal ? "__local__" : version;
+  const cached = cache.get(cacheKey);
   if (cached) {
     return cached;
   }
   try {
-    const lib = await ArtifactLibrary.fromRemote(version);
-    cache.set(version, lib);
+    const lib = useLocal ? await ArtifactLibrary.fromLocal() : await ArtifactLibrary.fromRemote(version);
+    cache.set(cacheKey, lib);
     return lib;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (useLocal) {
+      throw new Error(
+        `Failed to load local swirl-ai artifacts. Make sure swirl-ai has been built (\`pnpm --filter @getflip/swirl-ai build\`). Details: ${message}`
+      );
+    }
     throw new Error(
       `Version "${version}" not found or failed to load. Make sure the version matches your installed @getflip/swirl-components version. Details: ${message}`
     );
@@ -350,7 +541,7 @@ function createMcpServer() {
   const server = new McpServer(
     {
       name: "swirl-mcp",
-      version: "0.1.0"
+      version: package_default.version
     },
     {
       instructions: INSTRUCTIONS
@@ -362,6 +553,9 @@ function createMcpServer() {
   registerGetComponentDetails(server, loadLibrary);
   registerGetComponentSource(server, loadLibrary);
   registerGetStarted(server, loadLibrary);
+  registerListColorTokens(server, loadLibrary);
+  registerListTypographyTokens(server, loadLibrary);
+  registerListLayoutTokens(server, loadLibrary);
   return server;
 }
 

package/dist/transports/http.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createMcpServer
-} from "../chunk-HWC76PLD.js";
+} from "../chunk-QVNIVXYL.js";
 
 // src/transports/http.ts
 import { createServer } from "http";

package/dist/transports/stdio.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createMcpServer
-} from "../chunk-HWC76PLD.js";
+} from "../chunk-QVNIVXYL.js";
 
 // src/transports/stdio.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getflip/swirl-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for Swirl Design System — lets AI agents discover and use Swirl components",
   "author": "Flip GmbH",
   "repository": {