@getflip/swirl-mcp 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,7 @@
 # @getflip/swirl-mcp
 
-MCP server that lets AI agents discover and use [Swirl Design System](https://getflip.dev) components.
+MCP server that lets AI agents discover and use
+[Swirl Design System](https://getflip.dev) components.
 
 ## Setup
 
@@ -31,35 +32,58 @@ 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
 
-Start the server, then open the Inspector and connect with transport type "Streamable HTTP" and URL `http://localhost:3000/mcp`:
+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
 ```
 
-## Tools
+### `SWIRL_AI_LOCAL`
 
-| 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_started**           | Installation and setup guide for Web Components, Angular, and React.         |
+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
 
-All tools accept a `version` parameter matching the installed `@getflip/swirl-components` version.
+| 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.
 
 ## How it works
 
-Component metadata and documentation are fetched at runtime from `@getflip/swirl-ai` artifacts on the unpkg CDN. Loaded libraries are cached in-memory to avoid redundant fetches.
+Component metadata and documentation are fetched at runtime from
+`@getflip/swirl-ai` artifacts on the unpkg CDN. Versioned component source is
+fetched from matching `@getflip/swirl-components@<version>` tags in the Swirl
+GitHub repository. Loaded libraries are cached in-memory to avoid redundant
+fetches.

package/dist/chunk-QVNIVXYL.js

@@ -0,0 +1,564 @@
+#!/usr/bin/env node
+
+// 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
+import { readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+var RemoteDataSource = class {
+  constructor(version) {
+    this.version = version;
+  }
+  async readJson(relativePath) {
+    const url = `${this.baseUrl}/${relativePath}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+      throw new Error(
+        `Failed to fetch ${url}: ${res.status} ${res.statusText}`
+      );
+    }
+    return await res.json();
+  }
+  async readText(relativePath) {
+    const url = `${this.baseUrl}/${relativePath}`;
+    return this.readTextUrl(url);
+  }
+  async readComponentSource(tag) {
+    const componentPath = `packages/swirl-components/src/components/${tag}/${tag}`;
+    const [tsx, css] = await Promise.all([
+      this.readTextUrl(`${this.sourceBaseUrl}/${componentPath}.tsx`),
+      this.readTextUrl(`${this.sourceBaseUrl}/${componentPath}.css`)
+    ]);
+    return { tsx, css };
+  }
+  async readTextUrl(url) {
+    try {
+      const res = await fetch(url);
+      if (!res.ok) {
+        return void 0;
+      }
+      return await res.text();
+    } catch {
+      return void 0;
+    }
+  }
+  get baseUrl() {
+    return `https://unpkg.com/@getflip/swirl-ai@${this.version}/dist/agent`;
+  }
+  get sourceBaseUrl() {
+    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, tokens, dataSource) {
+    this.catalog = catalog;
+    this.tokens = tokens;
+    this.dataSource = dataSource;
+    this.tagIndex = /* @__PURE__ */ new Map();
+    for (const entry of this.catalog) {
+      this.tagIndex.set(entry.tag, entry);
+    }
+  }
+  /**
+   * Load artifacts from a remote base URL (CDN).
+   */
+  static async fromRemote(version) {
+    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);
+  }
+  getByTag(tag) {
+    return this.tagIndex.get(tag);
+  }
+  async getComponentMarkdown(tag) {
+    return this.dataSource.readText(`components/${tag}.md`);
+  }
+  async getComponentSource(tag) {
+    return this.dataSource.readComponentSource(tag);
+  }
+  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-")) {
+    return "icon";
+  }
+  if (tag.startsWith("swirl-symbol-")) {
+    return "symbol";
+  }
+  return "core";
+}
+
+// src/library-cache.ts
+var LibraryCache = class {
+  cache = /* @__PURE__ */ new Map();
+  maxSize;
+  constructor(maxSize = 20) {
+    this.maxSize = maxSize;
+  }
+  get(version) {
+    const lib = this.cache.get(version);
+    if (lib) {
+      this.cache.delete(version);
+      this.cache.set(version, lib);
+    }
+    return lib;
+  }
+  set(version, lib) {
+    if (this.cache.has(version)) {
+      this.cache.delete(version);
+    } else if (this.cache.size >= this.maxSize) {
+      const oldest = this.cache.keys().next().value;
+      this.cache.delete(oldest);
+    }
+    this.cache.set(version, lib);
+  }
+};
+
+// src/tools/get-component-details.ts
+import { z } from "zod";
+var VERSION_DESCRIPTION = "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.";
+function registerGetComponentDetails(server, loadLibrary2) {
+  server.registerTool(
+    "get_component_details",
+    {
+      description: "Get full details for a Swirl component including all props with types and defaults, events, methods, slots, accessibility info, and usage examples.",
+      inputSchema: {
+        tag: z.string().describe('The component tag name, e.g. "swirl-button"'),
+        version: z.string().describe(VERSION_DESCRIPTION)
+      }
+    },
+    // @ts-ignore - MCP SDK + zod 3.x causes excessively deep type instantiation
+    async ({ tag, version }) => {
+      const lib = await loadLibrary2(version);
+      const entry = lib.getByTag(tag);
+      if (!entry) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Component "${tag}" not found. Use list_components to see available components.`
+            }
+          ]
+        };
+      }
+      const markdown = await lib.getComponentMarkdown(tag);
+      if (!markdown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Component "${tag}" exists but no detailed documentation was found.`
+            }
+          ]
+        };
+      }
+      return {
+        content: [{ type: "text", text: markdown }]
+      };
+    }
+  );
+}
+
+// src/tools/get-component-source.ts
+import { z as z2 } from "zod";
+var VERSION_DESCRIPTION2 = "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.";
+function registerGetComponentSource(server, loadLibrary2) {
+  server.registerTool(
+    "get_component_source",
+    {
+      description: "Get the versioned original TSX and CSS source files for a Swirl component. Use this when behavior, styling, layout, rendering details, debugging, or uncertainty requires the full implementation.",
+      inputSchema: {
+        tag: z2.string().describe('The component tag name, e.g. "swirl-button"'),
+        version: z2.string().describe(VERSION_DESCRIPTION2)
+      }
+    },
+    // @ts-ignore - MCP SDK + zod 3.x causes excessively deep type instantiation
+    async ({ tag, version }) => {
+      const lib = await loadLibrary2(version);
+      const entry = lib.getByTag(tag);
+      if (!entry) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Component "${tag}" not found. Use list_components to see available components.`
+            }
+          ]
+        };
+      }
+      const source = await lib.getComponentSource(tag);
+      const sections = [
+        formatSourceSection(tag, "tsx", source.tsx),
+        formatSourceSection(tag, "css", source.css)
+      ].filter(Boolean);
+      if (sections.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Component "${tag}" exists but no original source files were found for version "${version}". Make sure the version matches an @getflip/swirl-components release tag.`
+            }
+          ]
+        };
+      }
+      return {
+        content: [{ type: "text", text: sections.join("\n\n") }]
+      };
+    }
+  );
+}
+function formatSourceSection(tag, extension, content) {
+  if (!content) {
+    return void 0;
+  }
+  const path = `packages/swirl-components/src/components/${tag}/${tag}.${extension}`;
+  return [`## ${path}`, "", `\`\`\`\`${extension}`, content, "````"].join("\n");
+}
+
+// src/tools/get-started.ts
+import { z as z3 } from "zod";
+var VERSION_DESCRIPTION3 = "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.";
+function registerGetStarted(server, loadLibrary2) {
+  server.registerTool(
+    "get_started",
+    {
+      description: "Get installation and setup instructions for Swirl components. Covers Web Components, Angular, and React wrapper libraries.",
+      inputSchema: {
+        version: z3.string().describe(VERSION_DESCRIPTION3)
+      }
+    },
+    async ({ version }) => {
+      const lib = await loadLibrary2(version);
+      const markdown = await lib.getGuide("get-started");
+      if (!markdown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Getting started guide not found."
+            }
+          ]
+        };
+      }
+      return {
+        content: [{ type: "text", text: markdown }]
+      };
+    }
+  );
+}
+
+// src/tools/list-components.ts
+import { z as z4 } from "zod";
+var VERSION_DESCRIPTION4 = "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.";
+function registerListComponents(server, loadLibrary2) {
+  registerListTool(
+    server,
+    loadLibrary2,
+    "list_components",
+    "List all Swirl design system UI components (buttons, modals, forms, etc.) with brief summaries and related components. Does NOT include icons or symbols \u2014 use list_icons or list_symbols for those. Use get_component_details for full props, events, slots, and examples.",
+    "core"
+  );
+}
+function registerListIcons(server, loadLibrary2) {
+  registerListTool(
+    server,
+    loadLibrary2,
+    "list_icons",
+    "List all Swirl icon components (swirl-icon-*). Use get_component_details for full details on a specific icon.",
+    "icon"
+  );
+}
+function registerListSymbols(server, loadLibrary2) {
+  registerListTool(
+    server,
+    loadLibrary2,
+    "list_symbols",
+    "List all Swirl symbol components (swirl-symbol-*). Use get_component_details for full details on a specific symbol.",
+    "symbol"
+  );
+}
+function registerListTool(server, loadLibrary2, name, description, category) {
+  server.registerTool(
+    name,
+    {
+      description,
+      inputSchema: {
+        version: z4.string().describe(VERSION_DESCRIPTION4)
+      }
+    },
+    // @ts-ignore - MCP SDK + zod 3.x causes excessively deep type instantiation
+    async ({ version }) => {
+      const lib = await loadLibrary2(version);
+      const components = lib.getByCategory(category);
+      return {
+        content: [{ type: "text", text: JSON.stringify(components) }]
+      };
+    }
+  );
+}
+
+// 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 cacheKey = useLocal ? "__local__" : version;
+  const cached = cache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+  try {
+    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}`
+    );
+  }
+}
+var INSTRUCTIONS = `Use this server as the authoritative, version-aware source for the Swirl design system (@getflip/swirl-components).
+
+If a project has @getflip/swirl-components installed, use Swirl as the default
+UI system for all UI work. Prefer Swirl components, icons, symbols, tokens, and
+documented patterns over custom UI. Only build custom UI when no suitable Swirl
+component or pattern exists.
+
+For any UI task in a project that uses Swirl, call the appropriate Swirl MCP
+tool before choosing or implementing UI. Do not infer component APIs, prop names,
+token values, icon names, or usage patterns from memory.
+
+Use get_component_details for documented component APIs, accessibility guidance,
+slots, events, examples, and related components. When behavior, styling, layout,
+rendering details, debugging, or uncertainty requires the full picture, use
+get_component_source to read the versioned original source and styles for the
+specific component as well.
+
+Every tool requires a 'version' parameter matching the project's
+installed @getflip/swirl-components version. Read it from the user's
+package.json (or node_modules/@getflip/swirl-components/package.json)
+before the first tool call and reuse it for subsequent calls.`;
+function createMcpServer() {
+  const server = new McpServer(
+    {
+      name: "swirl-mcp",
+      version: package_default.version
+    },
+    {
+      instructions: INSTRUCTIONS
+    }
+  );
+  registerListComponents(server, loadLibrary);
+  registerListIcons(server, loadLibrary);
+  registerListSymbols(server, loadLibrary);
+  registerGetComponentDetails(server, loadLibrary);
+  registerGetComponentSource(server, loadLibrary);
+  registerGetStarted(server, loadLibrary);
+  registerListColorTokens(server, loadLibrary);
+  registerListTypographyTokens(server, loadLibrary);
+  registerListLayoutTokens(server, loadLibrary);
+  return server;
+}
+
+export {
+  createMcpServer
+};

package/dist/transports/http.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createMcpServer
-} from "../chunk-4X45IM6A.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-4X45IM6A.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.2.0",
+  "version": "0.4.0",
   "description": "MCP server for Swirl Design System — lets AI agents discover and use Swirl components",
   "author": "Flip GmbH",
   "repository": {

package/dist/chunk-4X45IM6A.js

@@ -1,282 +0,0 @@
-#!/usr/bin/env node
-
-// src/create-server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-// src/data-source.ts
-var DataSource = class {
-  constructor(version) {
-    this.version = version;
-  }
-  async readJson(relativePath) {
-    const url = `${this.baseUrl}/${relativePath}`;
-    const res = await fetch(url);
-    if (!res.ok) {
-      throw new Error(
-        `Failed to fetch ${url}: ${res.status} ${res.statusText}`
-      );
-    }
-    return await res.json();
-  }
-  async readText(relativePath) {
-    const url = `${this.baseUrl}/${relativePath}`;
-    try {
-      const res = await fetch(url);
-      if (!res.ok) {
-        return void 0;
-      }
-      return await res.text();
-    } catch {
-      return void 0;
-    }
-  }
-  get baseUrl() {
-    return `https://unpkg.com/@getflip/swirl-ai@${this.version}/dist/agent`;
-  }
-};
-
-// src/artifact-library.ts
-var ArtifactLibrary = class _ArtifactLibrary {
-  catalog;
-  tagIndex;
-  dataSource;
-  constructor(catalog, dataSource) {
-    this.catalog = catalog;
-    this.dataSource = dataSource;
-    this.tagIndex = /* @__PURE__ */ new Map();
-    for (const entry of this.catalog) {
-      this.tagIndex.set(entry.tag, entry);
-    }
-  }
-  /**
-   * 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);
-  }
-  getByCategory(category) {
-    return this.catalog.filter((c) => categorize(c.tag) === category);
-  }
-  getByTag(tag) {
-    return this.tagIndex.get(tag);
-  }
-  async getComponentMarkdown(tag) {
-    return this.dataSource.readText(`components/${tag}.md`);
-  }
-  async getGuide(name) {
-    return this.dataSource.readText(`${name}.md`);
-  }
-};
-function categorize(tag) {
-  if (tag.startsWith("swirl-icon-")) {
-    return "icon";
-  }
-  if (tag.startsWith("swirl-symbol-")) {
-    return "symbol";
-  }
-  return "core";
-}
-
-// src/library-cache.ts
-var LibraryCache = class {
-  cache = /* @__PURE__ */ new Map();
-  maxSize;
-  constructor(maxSize = 20) {
-    this.maxSize = maxSize;
-  }
-  get(version) {
-    const lib = this.cache.get(version);
-    if (lib) {
-      this.cache.delete(version);
-      this.cache.set(version, lib);
-    }
-    return lib;
-  }
-  set(version, lib) {
-    if (this.cache.has(version)) {
-      this.cache.delete(version);
-    } else if (this.cache.size >= this.maxSize) {
-      const oldest = this.cache.keys().next().value;
-      this.cache.delete(oldest);
-    }
-    this.cache.set(version, lib);
-  }
-};
-
-// src/tools/list-components.ts
-import { z } from "zod";
-var VERSION_DESCRIPTION = "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.";
-function registerListComponents(server, loadLibrary2) {
-  registerListTool(
-    server,
-    loadLibrary2,
-    "list_components",
-    "List all Swirl design system UI components (buttons, modals, forms, etc.) with brief summaries and related components. Does NOT include icons or symbols \u2014 use list_icons or list_symbols for those. Use get_component_details for full props, events, slots, and examples. IMPORTANT: First read the user's package.json to determine their installed @getflip/swirl-components version, then pass it as the 'version' parameter.",
-    "core"
-  );
-}
-function registerListIcons(server, loadLibrary2) {
-  registerListTool(
-    server,
-    loadLibrary2,
-    "list_icons",
-    "List all Swirl icon components (swirl-icon-*). Use get_component_details for full details on a specific icon. IMPORTANT: First read the user's package.json to determine their installed @getflip/swirl-components version, then pass it as the 'version' parameter.",
-    "icon"
-  );
-}
-function registerListSymbols(server, loadLibrary2) {
-  registerListTool(
-    server,
-    loadLibrary2,
-    "list_symbols",
-    "List all Swirl symbol components (swirl-symbol-*). Use get_component_details for full details on a specific symbol. IMPORTANT: First read the user's package.json to determine their installed @getflip/swirl-components version, then pass it as the 'version' parameter.",
-    "symbol"
-  );
-}
-function registerListTool(server, loadLibrary2, name, description, category) {
-  server.registerTool(
-    name,
-    {
-      description,
-      inputSchema: {
-        version: z.string().describe(VERSION_DESCRIPTION)
-      }
-    },
-    // @ts-ignore - MCP SDK + zod 3.x causes excessively deep type instantiation
-    async ({ version }) => {
-      const lib = await loadLibrary2(version);
-      const components = lib.getByCategory(category);
-      return {
-        content: [{ type: "text", text: JSON.stringify(components) }]
-      };
-    }
-  );
-}
-
-// src/tools/get-component-details.ts
-import { z as z2 } from "zod";
-var VERSION_DESCRIPTION2 = "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.";
-function registerGetComponentDetails(server, loadLibrary2) {
-  server.registerTool(
-    "get_component_details",
-    {
-      description: "Get full details for a Swirl component including all props with types and defaults, events, methods, slots, accessibility info, and usage examples. IMPORTANT: First read the user's package.json to determine their installed @getflip/swirl-components version, then pass it as the 'version' parameter.",
-      inputSchema: {
-        tag: z2.string().describe('The component tag name, e.g. "swirl-button"'),
-        version: z2.string().describe(VERSION_DESCRIPTION2)
-      }
-    },
-    // @ts-ignore - MCP SDK + zod 3.x causes excessively deep type instantiation
-    async ({ tag, version }) => {
-      const lib = await loadLibrary2(version);
-      const entry = lib.getByTag(tag);
-      if (!entry) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Component "${tag}" not found. Use list_components to see available components.`
-            }
-          ]
-        };
-      }
-      const markdown = await lib.getComponentMarkdown(tag);
-      if (!markdown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Component "${tag}" exists but no detailed documentation was found.`
-            }
-          ]
-        };
-      }
-      return {
-        content: [{ type: "text", text: markdown }]
-      };
-    }
-  );
-}
-
-// src/tools/get-started.ts
-import { z as z3 } from "zod";
-var VERSION_DESCRIPTION3 = "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.";
-function registerGetStarted(server, loadLibrary2) {
-  server.registerTool(
-    "get_started",
-    {
-      description: "Get installation and setup instructions for Swirl components. Covers Web Components, Angular, and React wrapper libraries. IMPORTANT: First read the user's package.json to determine their installed @getflip/swirl-components version, then pass it as the 'version' parameter.",
-      inputSchema: {
-        version: z3.string().describe(VERSION_DESCRIPTION3)
-      }
-    },
-    async ({ version }) => {
-      const lib = await loadLibrary2(version);
-      const markdown = await lib.getGuide("get-started");
-      if (!markdown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Getting started guide not found."
-            }
-          ]
-        };
-      }
-      return {
-        content: [{ type: "text", text: markdown }]
-      };
-    }
-  );
-}
-
-// src/create-server.ts
-var cache = new LibraryCache();
-async function loadLibrary(version) {
-  const cached = cache.get(version);
-  if (cached) {
-    return cached;
-  }
-  try {
-    const lib = await ArtifactLibrary.fromRemote(version);
-    cache.set(version, lib);
-    return lib;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `Version "${version}" not found or failed to load. Make sure the version matches your installed @getflip/swirl-components version. Details: ${message}`
-    );
-  }
-}
-var INSTRUCTIONS = `The authoritative source for the Swirl design system (@getflip/swirl-components).
-Covers components, icons, symbols, and usage guidance.
-
-For any task involving Swirl \u2014 a swirl-* component (e.g. swirl-button,
-swirl-file-chip), an icon or the design system in general \u2014
-you MUST call the appropriate tool on this server BEFORE reading Swirl
-source files, grepping the repo, or searching the web. Do not infer
-component APIs, prop names, token values, or icon names from source code,
-type definitions, or memory \u2014 they may be outdated. This server is the
-source of truth.`;
-function createMcpServer() {
-  const server = new McpServer({
-    name: "swirl-mcp",
-    version: "0.1.0"
-  }, {
-    instructions: INSTRUCTIONS
-  });
-  registerListComponents(server, loadLibrary);
-  registerListIcons(server, loadLibrary);
-  registerListSymbols(server, loadLibrary);
-  registerGetComponentDetails(server, loadLibrary);
-  registerGetStarted(server, loadLibrary);
-  return server;
-}
-
-export {
-  createMcpServer
-};