@iyulab/u-widgets-mcp 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+# @iyulab/u-widgets-mcp
+
+MCP (Model Context Protocol) server for the [u-widgets](https://github.com/iyulab/u-widgets) declarative widget system.
+
+Exposes u-widgets' developer tools as MCP tools, enabling AI assistants to create, validate, and suggest data-driven widget specs.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `help` | List available widget types. Filter by name or category. |
+| `template` | Generate a minimal, valid widget spec with sample data. |
+| `validate` | Check a widget spec for errors and warnings. |
+| `suggest_mapping` | Analyze data and suggest the best widget type + mapping. |
+| `auto_spec` | Generate a complete spec from raw data (one-call convenience). |
+
+## Installation
+
+```bash
+npm install -g @iyulab/u-widgets-mcp
+```
+
+Or run directly with npx:
+
+```bash
+npx @iyulab/u-widgets-mcp
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "u-widgets": {
+      "command": "npx",
+      "args": ["-y", "@iyulab/u-widgets-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your `.claude/settings.json` or project `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "u-widgets": {
+      "command": "npx",
+      "args": ["-y", "@iyulab/u-widgets-mcp"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "u-widgets": {
+      "command": "npx",
+      "args": ["-y", "@iyulab/u-widgets-mcp"]
+    }
+  }
+}
+```
+
+## Tool Examples
+
+### help
+
+```
+List all widget types:
+→ help()
+
+List chart types only:
+→ help({ widget: "chart" })
+
+Get details for a specific widget:
+→ help({ widget: "chart.bar" })
+```
+
+### template
+
+```
+Generate a bar chart template:
+→ template({ widget: "chart.bar" })
+
+Result:
+{
+  "widget": "chart.bar",
+  "data": [{ "category": "A", "value": 30 }, ...],
+  "mapping": { "x": "category", "y": "value" }
+}
+```
+
+### validate
+
+```
+Check if a spec is valid:
+→ validate({ spec: { "widget": "metric", "data": { "value": 42 } } })
+
+Result:
+{ "valid": true, "errors": [], "warnings": [] }
+```
+
+### suggest_mapping
+
+```
+Get widget suggestions for your data:
+→ suggest_mapping({ data: [{ "name": "A", "value": 30 }, { "name": "B", "value": 70 }] })
+
+Result:
+[
+  { "widget": "chart.bar", "confidence": 0.9, "mapping": { "x": "name", "y": "value" }, ... },
+  { "widget": "chart.line", ... },
+  ...
+]
+```
+
+### auto_spec
+
+```
+Generate a complete spec from data:
+→ auto_spec({ data: [{ "quarter": "Q1", "revenue": 100 }, { "quarter": "Q2", "revenue": 150 }] })
+
+Result:
+{
+  "widget": "chart.bar",
+  "data": [{ "quarter": "Q1", "revenue": 100 }, ...],
+  "mapping": { "x": "quarter", "y": "revenue" }
+}
+```
+
+## Development
+
+```bash
+cd mcp
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Interactive testing with MCP Inspector
+npm run inspect
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+try {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+catch (err) {
+    process.stderr.write(`[u-widgets-mcp] Failed to start: ${err}\n`);
+    process.exit(1);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,IAAI,CAAC;IACH,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,GAAG,IAAI,CAAC,CAAC;IAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create and configure the u-widgets MCP server.
+ *
+ * Returns a configured McpServer instance without connecting
+ * to any transport — the caller is responsible for connecting.
+ */
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAYpE;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAiGxC"}

package/dist/server.js

@@ -0,0 +1,87 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { help, template, suggestMapping, autoSpec } from '@iyulab/u-widgets/tools';
+import { validate } from '@iyulab/u-widgets';
+function errorResult(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text', text: `Internal error: ${msg}` }], isError: true };
+}
+/**
+ * Create and configure the u-widgets MCP server.
+ *
+ * Returns a configured McpServer instance without connecting
+ * to any transport — the caller is responsible for connecting.
+ */
+export function createServer() {
+    const server = new McpServer({
+        name: 'u-widgets-mcp',
+        version: '0.1.0',
+    });
+    // ── Tool: help ──────────────────────────────────────────────
+    server.tool('help', 'List available u-widget types. Returns the full catalog when no argument is given, or filters by widget name or category (e.g. "chart", "chart.bar", "display").', { widget: z.string().max(100).optional().describe('Widget type or category to filter (e.g. "chart.bar", "chart", "display"). Omit for full catalog.') }, async ({ widget }) => {
+        try {
+            const result = widget ? help(widget) : help();
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // ── Tool: template ──────────────────────────────────────────
+    server.tool('template', 'Generate a minimal, valid u-widget spec with sample data for a given widget type. Use this as a starting point when creating widgets.', { widget: z.string().max(100).describe('Widget type (e.g. "metric", "chart.bar", "table", "form").') }, async ({ widget }) => {
+        try {
+            const result = template(widget);
+            if (!result) {
+                return {
+                    content: [{ type: 'text', text: `Unknown widget type: "${widget}". Use the "help" tool to list available types.` }],
+                    isError: true,
+                };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // ── Tool: validate ─────────────────────────────────────────
+    server.tool('validate', 'Validate a u-widget spec. Returns errors (fatal) and warnings (non-fatal). Use this to check if a spec is correct before rendering.', { spec: z.record(z.unknown()).describe('The u-widget spec object to validate. Must be a plain object with a "widget" field.') }, async ({ spec }) => {
+        try {
+            const result = validate(spec);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // ── Tool: suggest_mapping ──────────────────────────────────
+    server.tool('suggest_mapping', 'Analyze data and suggest the best widget type with auto-inferred mapping. Returns ranked suggestions sorted by confidence. Optionally constrain to a specific widget type.', {
+        data: z.union([z.record(z.unknown()), z.array(z.record(z.unknown()))]).describe('The data to analyze — a single object or an array of records.'),
+        widget: z.string().max(100).optional().describe('Optional widget type to constrain the suggestion (e.g. "chart.pie"). Must be a known widget type from the catalog.'),
+    }, async ({ data, widget }) => {
+        try {
+            const result = suggestMapping(data, widget);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // ── Tool: auto_spec ────────────────────────────────────────
+    server.tool('auto_spec', 'Generate a complete, ready-to-use u-widget spec from raw data. Picks the best widget type and mapping automatically. One-call convenience for quick visualizations.', { data: z.union([z.record(z.unknown()), z.array(z.record(z.unknown()))]).describe('The data to visualize — a single object or an array of records.') }, async ({ data }) => {
+        try {
+            const result = autoSpec(data);
+            if (!result) {
+                return {
+                    content: [{ type: 'text', text: 'Could not generate a spec from this data. The data may be empty or have no recognizable pattern.' }],
+                    isError: true,
+                };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@iyulab/u-widgets-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the u-widgets declarative widget system",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "u-widgets-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "inspect": "npx @modelcontextprotocol/inspector dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "widgets",
+    "ai",
+    "u-widgets"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iyulab/u-widgets",
+    "directory": "mcp"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@iyulab/u-widgets": "^0.4.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "~5.7.0",
+    "vitest": "^3.0.0"
+  }
+}