@empathyds/mcp-server 0.0.1

package/README.md

@@ -0,0 +1,145 @@
+# @empathyds/mcp-server
+
+MCP (Model Context Protocol) server for Empathy DS - enables AI assistants to discover and use Empathy DS Vue components and blocks.
+
+## Features
+
+- **Component Discovery**: List all 60+ Empathy DS components
+- **Detailed Information**: Get props, variants, and usage examples
+- **Category Filtering**: Browse by Forms, Layout, Feedback, Navigation, etc.
+- **Blocks Support**: Pre-built UI patterns (login forms, dashboards)
+- **Search**: Find components by name or description
+- **Remote Registry**: Fetches data from empathyds.com (works anywhere!)
+
+---
+
+## Quick Start
+
+### With Antigravity
+
+Add to `~/.gemini/antigravity/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "empathy-ds": {
+      "command": "npx",
+      "args": ["-y", "@empathyds/mcp-server"]
+    }
+  }
+}
+```
+
+---
+
+## How It Works
+
+The MCP server fetches component data from `https://empathyds.com/registry.json`:
+- Works for **anyone** using `npx @empathyds/mcp-server`
+- Falls back to local filesystem for development
+- Caches registry data for 5 minutes
+
+---
+
+## Available Tools (8 Total)
+
+| Tool | Description |
+|------|-------------|
+| `getAllComponents` | Lists all 60+ components |
+| `getComponent` | Gets props, examples for a component |
+| `getComponentsByCategory` | Filter by Forms, Layout, Feedback, etc. |
+| `searchComponents` | Search by name or description |
+| `getCategories` | Lists all 7 categories |
+| `getBlocks` | Lists all pre-built UI patterns |
+| `getBlock` | Gets details for a specific block |
+| `getUsageGuide` | Best practices for Empathy DS |
+
+---
+
+## Publishing to npm
+
+### 1. Generate the Registry
+
+```bash
+# From monorepo root
+node scripts/generate-registry.js
+```
+
+This creates `apps/docs/public/registry.json` which gets deployed to empathyds.com.
+
+### 2. Deploy Docs Site
+
+Deploy your docs to make `https://empathyds.com/registry.json` accessible.
+
+### 3. Publish MCP Server
+
+```bash
+cd packages/mcp-server
+
+# Ensure you're logged in
+npm login
+
+# Build
+pnpm build
+
+# Publish
+npm publish --access public
+```
+
+### 4. Users Can Now Use It
+
+```bash
+npx @empathyds/mcp-server
+```
+
+---
+
+## Development
+
+### Local Testing
+
+```bash
+cd packages/mcp-server
+pnpm install
+pnpm build
+pnpm inspect  # Opens MCP Inspector
+```
+
+### Local Antigravity Config
+
+For development, use the local path:
+
+```json
+{
+  "mcpServers": {
+    "empathy-ds": {
+      "command": "node",
+      "args": ["/path/to/eds-mono/packages/mcp-server/dist/server.js"],
+      "disabled": false
+    }
+  }
+}
+```
+
+---
+
+## When You Add New Components
+
+| Step | Action |
+|------|--------|
+| 1. Add component | Create in `packages/empathy-ds/src/components/ui/` |
+| 2. Add docs | Create `apps/docs/components/{name}.md` |
+| 3. Categorize | Update `src/lib/categories.ts` |
+| 4. Regenerate | Run `node scripts/generate-registry.js` |
+| 5. Redeploy | Deploy docs to update registry.json |
+| 6. (Optional) | Publish new MCP server version |
+
+---
+
+## Example AI Queries
+
+- "What components does Empathy DS have?"
+- "Show me the button variants"
+- "Get the Card component props"
+- "What form components are available?"
+- "Show me the login form block"

package/dist/server.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/server.js

@@ -0,0 +1,465 @@
+#!/usr/bin/env node
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
+
+// src/utils/schemas.ts
+import { z } from "zod";
+var ComponentMetadataSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  category: z.string().optional()
+});
+var ComponentPropSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+  default: z.string().optional(),
+  description: z.string().optional()
+});
+var ComponentDetailSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  category: z.string().optional(),
+  import: z.string(),
+  props: z.array(ComponentPropSchema),
+  source: z.string().optional(),
+  indexSource: z.string().optional(),
+  examples: z.array(z.string()),
+  docsUrl: z.string()
+});
+var CategoryComponentsSchema = z.object({
+  category: z.string(),
+  components: z.array(ComponentMetadataSchema)
+});
+
+// src/lib/config.ts
+var mcpConfig = {
+  projectName: "empathy-ds",
+  packageName: "@empathyds/vue",
+  baseUrl: "https://empathyds.com",
+  registryUrl: "https://empathyds.com/registry.json"
+};
+
+// src/utils/formatters.ts
+function generateImportStatement(componentName) {
+  const pascalName = componentName.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  return `import { ${pascalName} } from '${mcpConfig.packageName}'`;
+}
+
+// src/utils/api.ts
+var registryCache = null;
+var registryCacheTime = 0;
+var CACHE_TTL = 5 * 60 * 1e3;
+async function getRegistry() {
+  if (registryCache && Date.now() - registryCacheTime < CACHE_TTL) {
+    return registryCache;
+  }
+  try {
+    const response = await fetch(mcpConfig.registryUrl);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch registry: ${response.statusText}`);
+    }
+    registryCache = await response.json();
+    registryCacheTime = Date.now();
+    return registryCache;
+  } catch (error) {
+    console.error("Error fetching remote registry:", error);
+    return null;
+  }
+}
+async function listComponents() {
+  const registry = await getRegistry();
+  if (!registry) return [];
+  return registry.components.map((c) => ({
+    name: c.name,
+    description: c.description,
+    category: c.category || void 0
+  }));
+}
+async function getComponentDetail(componentName) {
+  const registry = await getRegistry();
+  if (!registry) return null;
+  const component = registry.components.find((c) => c.name === componentName);
+  if (!component) return null;
+  return {
+    name: component.name,
+    description: component.description,
+    category: component.category || void 0,
+    import: generateImportStatement(componentName),
+    props: component.props || [],
+    examples: component.examples || [],
+    docsUrl: component.docsUrl
+  };
+}
+async function searchComponents(query) {
+  const allComponents = await listComponents();
+  const lowerQuery = query.toLowerCase();
+  return allComponents.filter(
+    (c) => c.name.toLowerCase().includes(lowerQuery) || c.description.toLowerCase().includes(lowerQuery)
+  );
+}
+async function getComponentsByCategory(category) {
+  const allComponents = await listComponents();
+  return allComponents.filter((c) => c.category === category);
+}
+async function listBlocks() {
+  const registry = await getRegistry();
+  if (!registry) return [];
+  return registry.blocks.map((b) => ({
+    name: b.name,
+    description: b.description,
+    category: "Blocks"
+  }));
+}
+async function getBlockDetail(blockName) {
+  const registry = await getRegistry();
+  if (!registry) return null;
+  const block = registry.blocks.find((b) => b.name === blockName);
+  if (!block) return null;
+  return {
+    name: block.name,
+    description: block.description,
+    category: "Blocks",
+    import: `// Block: ${block.name} - see documentation`,
+    props: [],
+    examples: block.examples || [],
+    docsUrl: block.docsUrl
+  };
+}
+
+// src/server.ts
+var server = new McpServer({
+  name: "empathy-ds-mcp",
+  version: "0.0.1"
+});
+server.tool(
+  "getAllComponents",
+  "Lists all 60+ Empathy DS Vue components with their names, descriptions, and categories. Use this to discover available components.",
+  {},
+  async () => {
+    try {
+      const components = await listComponents();
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              totalComponents: components.length,
+              packageName: mcpConfig.packageName,
+              docsUrl: mcpConfig.baseUrl,
+              components
+            }, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error listing components: ${error instanceof Error ? error.message : "Unknown error"}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "getComponent",
+  "Gets detailed information about a specific Empathy DS component including source code, props, variants, and usage examples. Use this when you need implementation details for a component.",
+  {
+    componentName: z2.string().describe(
+      "The kebab-case name of the component (e.g., 'button', 'alert-dialog', 'dropdown-menu')"
+    )
+  },
+  async ({ componentName }) => {
+    try {
+      const component = await getComponentDetail(componentName);
+      if (!component) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Component "${componentName}" not found. Use getAllComponents to see available components.`
+            }
+          ],
+          isError: true
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(component, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error fetching component "${componentName}": ${error instanceof Error ? error.message : "Unknown error"}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "getComponentsByCategory",
+  "Gets all Empathy DS components in a specific category. Categories: Forms, Layout, Feedback, Navigation, DataDisplay, Overlays, Actions.",
+  {
+    category: z2.enum([
+      "Forms",
+      "Layout",
+      "Feedback",
+      "Navigation",
+      "DataDisplay",
+      "Overlays",
+      "Actions"
+    ]).describe("The category to filter by")
+  },
+  async ({ category }) => {
+    try {
+      const components = await getComponentsByCategory(category);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              category,
+              totalComponents: components.length,
+              components
+            }, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error fetching category "${category}": ${error instanceof Error ? error.message : "Unknown error"}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "searchComponents",
+  "Searches Empathy DS components by name or description. Use this to find components for a specific use case.",
+  {
+    query: z2.string().describe(
+      "The search query (e.g., 'button', 'form', 'dialog', 'navigation')"
+    )
+  },
+  async ({ query }) => {
+    try {
+      const results = await searchComponents(query);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              query,
+              totalResults: results.length,
+              results,
+              tip: "Use getComponent with a component name to get full details including source code and examples."
+            }, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error searching components: ${error instanceof Error ? error.message : "Unknown error"}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "getCategories",
+  "Lists all component categories in Empathy DS with their component counts. Use this to understand how components are organized.",
+  {},
+  async () => {
+    try {
+      const components = await listComponents();
+      const categoriesMap = /* @__PURE__ */ new Map();
+      components.forEach((c) => {
+        if (c.category) {
+          categoriesMap.set(c.category, (categoriesMap.get(c.category) || 0) + 1);
+        }
+      });
+      const categories = Array.from(categoriesMap.entries()).map(([name, count]) => ({
+        name,
+        componentCount: count
+      }));
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              totalCategories: categories.length,
+              categories
+            }, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error fetching categories: ${error instanceof Error ? error.message : "Unknown error"}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "getBlocks",
+  "Lists all Empathy DS blocks (pre-built UI patterns like login forms, dashboards). Use blocks for complex, commonly-used UI patterns.",
+  {},
+  async () => {
+    try {
+      const blocks = await listBlocks();
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              totalBlocks: blocks.length,
+              docsUrl: `${mcpConfig.baseUrl}/blocks`,
+              blocks
+            }, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error listing blocks: ${error instanceof Error ? error.message : "Unknown error"}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "getBlock",
+  "Gets detailed information about a specific Empathy DS block including code examples. Use this for implementation details of a block pattern.",
+  {
+    blockName: z2.string().describe(
+      "The kebab-case name of the block (e.g., 'login-form')"
+    )
+  },
+  async ({ blockName }) => {
+    try {
+      const block = await getBlockDetail(blockName);
+      if (!block) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Block "${blockName}" not found. Use getBlocks to see available blocks.`
+            }
+          ],
+          isError: true
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(block, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error fetching block "${blockName}": ${error instanceof Error ? error.message : "Unknown error"}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "getUsageGuide",
+  "Returns the Empathy DS usage guide for AI assistants, including import patterns, styling rules, and best practices.",
+  {},
+  async () => {
+    const guide = `# Empathy DS Usage Guide
+
+## Import Pattern
+Import components from \`${mcpConfig.packageName}\`:
+\`\`\`ts
+import { Button, Card, Input } from '${mcpConfig.packageName}'
+\`\`\`
+
+## Styling
+1. Import the stylesheet in your main entry file:
+   \`\`\`ts
+   import '${mcpConfig.packageName}/style.css'
+   \`\`\`
+
+2. Use standard Tailwind utility classes for layout: \`flex\`, \`p-4\`, \`gap-2\`
+
+3. Use design tokens for colors - DO NOT hardcode colors:
+   - \`bg-primary\`, \`text-primary-foreground\`
+   - \`bg-secondary\`, \`text-secondary-foreground\`
+   - \`bg-muted\`, \`text-muted-foreground\`
+   - \`bg-destructive\`, \`text-destructive-foreground\`
+   - \`bg-accent\`, \`text-accent-foreground\`
+
+## Component Best Practices
+1. Always prefer Empathy DS components over building from scratch
+2. Use the \`variant\` prop to control visual style
+3. Use the \`size\` prop to control component size
+4. Check component documentation for all available props
+
+## Documentation
+Full documentation: ${mcpConfig.baseUrl}
+`;
+    return {
+      content: [
+        {
+          type: "text",
+          text: guide
+        }
+      ]
+    };
+  }
+);
+async function startServer() {
+  try {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("\u2705 Empathy DS MCP server started successfully");
+  } catch (error) {
+    console.error("\u274C Error starting MCP server:", error);
+    process.exit(1);
+  }
+}
+startServer();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@empathyds/mcp-server",
+  "version": "0.0.1",
+  "description": "MCP server for Empathy DS - enables AI assistants to discover and use Empathy DS components",
+  "type": "module",
+  "main": "./dist/server.js",
+  "bin": {
+    "empathy-ds-mcp": "./dist/server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/server.ts --format esm --dts --out-dir dist --clean",
+    "dev": "tsx watch src/server.ts",
+    "inspect": "npx -y @modelcontextprotocol/inspector node dist/server.js",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "empathy-ds",
+    "vue",
+    "ai",
+    "llm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://bitbucket.org/underlings/eui-mono"
+  }
+}