@getflip/swirl-mcp 0.2.0 → 0.3.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
 
@@ -41,7 +42,8 @@ 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
@@ -56,10 +58,16 @@ npx @modelcontextprotocol/inspector
 | **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.         |
 
-All tools accept a `version` parameter matching the installed `@getflip/swirl-components` version.
+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-4X45IM6A.js → chunk-HWC76PLD.js}

@@ -20,6 +20,17 @@ var DataSource = class {
   }
   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) {
@@ -33,6 +44,9 @@ var DataSource = class {
   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}`;
+  }
 };
 
 // src/artifact-library.ts
@@ -67,6 +81,9 @@ var ArtifactLibrary = class _ArtifactLibrary {
   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`);
   }
@@ -107,64 +124,59 @@ var LibraryCache = class {
   }
 };
 
-// src/tools/list-components.ts
+// 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 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) {
+function registerGetComponentDetails(server, loadLibrary2) {
   server.registerTool(
-    name,
+    "get_component_details",
     {
-      description,
+      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 ({ version }) => {
+    async ({ tag, version }) => {
       const lib = await loadLibrary2(version);
-      const components = lib.getByCategory(category);
+      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: JSON.stringify(components) }]
+        content: [{ type: "text", text: markdown }]
       };
     }
   );
 }
 
-// src/tools/get-component-details.ts
+// 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 registerGetComponentDetails(server, loadLibrary2) {
+function registerGetComponentSource(server, loadLibrary2) {
   server.registerTool(
-    "get_component_details",
+    "get_component_source",
     {
-      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.",
+      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)
@@ -184,23 +196,34 @@ function registerGetComponentDetails(server, loadLibrary2) {
           ]
         };
       }
-      const markdown = await lib.getComponentMarkdown(tag);
-      if (!markdown) {
+      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 detailed documentation was found.`
+              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: markdown }]
+        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";
@@ -209,7 +232,7 @@ 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.",
+      description: "Get installation and setup instructions for Swirl components. Covers Web Components, Angular, and React wrapper libraries.",
       inputSchema: {
         version: z3.string().describe(VERSION_DESCRIPTION3)
       }
@@ -234,6 +257,56 @@ function registerGetStarted(server, loadLibrary2) {
   );
 }
 
+// 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/create-server.ts
 var cache = new LibraryCache();
 async function loadLibrary(version) {
@@ -252,27 +325,42 @@ async function loadLibrary(version) {
     );
   }
 }
-var INSTRUCTIONS = `The authoritative source for the Swirl design system (@getflip/swirl-components).
-Covers components, icons, symbols, and usage guidance.
+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 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.`;
+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: "0.1.0"
-  }, {
-    instructions: INSTRUCTIONS
-  });
+  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);
+  registerGetComponentSource(server, loadLibrary);
   registerGetStarted(server, loadLibrary);
   return server;
 }

package/dist/transports/http.js

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