@aicanvas/mcp 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# `@aicanvas/mcp`
+
+Model Context Protocol server for [AI Canvas](https://aicanvas.me). Lets your AI editor (Claude Code, Cursor, Claude Desktop, Codex) discover and install AI Canvas components without leaving the chat.
+
+```
+You:   "find me an animated card stack"
+AI:    [calls search_components → ranks matches → picks polaroid-stack]
+       [calls get_install_command → returns: npx shadcn add @aicanvas/polaroid-stack]
+       [runs the command — file lands in your project]
+You:   "make the rotation more dramatic"
+AI:    [edits the file directly]
+```
+
+## What it exposes
+
+Five tools, derived from the live [aicanvas.me](https://aicanvas.me) registry — adding a component to the website auto-updates the MCP within minutes:
+
+| Tool | Purpose |
+|---|---|
+| `list_categories` | Show every category with component counts. Orient before drilling in. |
+| `list_components` | Browse components, optionally filtered by category. Paginated. |
+| `search_components` | Fuzzy keyword search across slugs, names, descriptions, categories, tags. Ranked results. |
+| `get_component` | Full metadata + complete `.tsx` source code for one component. |
+| `get_install_command` | Get the `npx shadcn add @aicanvas/<slug>` command for a component. |
+
+All tools are read-only. Nothing is mutated on AI Canvas's side.
+
+## Setup
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "aicanvas": {
+      "command": "npx",
+      "args": ["-y", "@aicanvas/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The `aicanvas` tools should appear in the tools list.
+
+### Cursor
+
+Project-level (`.cursor/mcp.json` in your repo) or global (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "aicanvas": {
+      "command": "npx",
+      "args": ["-y", "@aicanvas/mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Project-level `.mcp.json` (committed alongside your code):
+
+```json
+{
+  "mcpServers": {
+    "aicanvas": {
+      "command": "npx",
+      "args": ["-y", "@aicanvas/mcp"]
+    }
+  }
+}
+```
+
+Or via the CLI:
+
+```bash
+claude mcp add aicanvas -- npx -y @aicanvas/mcp
+```
+
+### Codex
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.aicanvas]
+command = "npx"
+args = ["-y", "@aicanvas/mcp"]
+```
+
+## Verify it works
+
+Inside any of the AI editors above, ask:
+
+> "What categories of components does AI Canvas have?"
+
+You should see all 11 categories with counts. If you don't, check the host's MCP logs — typically a "Failed to spawn process" or network error means npx couldn't fetch the package, or the host wasn't restarted after editing the config.
+
+To inspect the server outside an editor:
+
+```bash
+npx -y @modelcontextprotocol/inspector npx -y @aicanvas/mcp
+```
+
+This opens a browser UI where you can call each tool by hand.
+
+## Configuration
+
+| Env var | Default | What it does |
+|---|---|---|
+| `AICANVAS_REGISTRY_BASE` | `https://aicanvas.me/r` | Registry root URL. Override only for local development against a self-hosted mirror. |
+
+## How the registry stays fresh
+
+The MCP fetches `https://aicanvas.me/r/aicanvas-mcp.json` on first use and caches it for 5 minutes. New components on AI Canvas appear in the MCP automatically — no package update required.
+
+The full source code for each component is fetched on demand from `/r/<slug>.json` (the same shadcn registry items the CLI installs).
+
+## Local development
+
+```bash
+git clone https://github.com/uiNerd16/aicanvas.git
+cd aicanvas/mcp
+npm install
+npm run build
+
+# Smoke-test against the deployed registry:
+npm run inspect
+
+# Or point at a locally running aicanvas dev server:
+AICANVAS_REGISTRY_BASE=http://localhost:3000/r node dist/index.js
+```
+
+Edit `src/index.ts`, run `npm run build`, restart your AI editor.
+
+## License
+
+MIT — same as the AI Canvas project.

package/dist/index.js

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * AI Canvas MCP server
+ * --------------------
+ * Exposes the AI Canvas standalone component registry to AI editors
+ * (Claude Code, Cursor, Claude Desktop, Codex). The AI can search,
+ * inspect, and install components without leaving the chat.
+ *
+ * Data flow:
+ *   - aicanvas.me/r/aicanvas-mcp.json   → all 64+ components' metadata
+ *   - aicanvas.me/r/<slug>.json         → full source code per component
+ *
+ * Both are static files, served from Vercel's CDN. Stateless server.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+// ── Configuration ────────────────────────────────────────────────────────────
+const REGISTRY_BASE = process.env.AICANVAS_REGISTRY_BASE ?? 'https://aicanvas.me/r';
+const META_URL = `${REGISTRY_BASE}/aicanvas-mcp.json`;
+const META_TTL_MS = 5 * 60 * 1000; // 5 minutes — meta updates with deploys
+// ── Cached fetchers ──────────────────────────────────────────────────────────
+let metaCache = null;
+async function fetchMeta() {
+    if (metaCache && Date.now() - metaCache.fetchedAt < META_TTL_MS) {
+        return metaCache.data;
+    }
+    const res = await fetch(META_URL, {
+        headers: { Accept: 'application/json' },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch AI Canvas registry meta from ${META_URL}: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    metaCache = { data, fetchedAt: Date.now() };
+    return data;
+}
+async function fetchComponentSource(slug) {
+    const url = `${REGISTRY_BASE}/${encodeURIComponent(slug)}.json`;
+    const res = await fetch(url, { headers: { Accept: 'application/json' } });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch source for "${slug}" from ${url}: ${res.status} ${res.statusText}`);
+    }
+    return (await res.json());
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function normalize(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+function scoreMatch(query, c) {
+    const q = normalize(query);
+    if (!q)
+        return 0;
+    // Drop tokens of <=2 chars — they cause false positives via substring
+    // matches in unrelated words (e.g. "no" hits "notification").
+    const tokens = q.split(/\s+/).filter((t) => t.length > 2);
+    if (tokens.length === 0)
+        return 0;
+    // Searchable surface — slug carries the most weight, then name, then
+    // description, then categories/tags.
+    const fields = [
+        { text: normalize(c.slug), weight: 5 },
+        { text: normalize(c.name), weight: 4 },
+        { text: normalize(c.description), weight: 1 },
+        { text: normalize(c.categories.join(' ')), weight: 2 },
+        { text: normalize(c.tags.join(' ')), weight: 1 },
+    ];
+    let score = 0;
+    for (const tok of tokens) {
+        for (const f of fields) {
+            if (!f.text)
+                continue;
+            // Whole-word match scores higher than substring.
+            if (new RegExp(`\\b${escapeRegExp(tok)}\\b`).test(f.text)) {
+                score += f.weight * 2;
+            }
+            else if (f.text.includes(tok)) {
+                score += f.weight;
+            }
+        }
+    }
+    return score;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function asTextContent(value) {
+    return {
+        type: 'text',
+        text: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+    };
+}
+function errorResult(message) {
+    return {
+        content: [asTextContent(`Error: ${message}`)],
+        isError: true,
+    };
+}
+// ── Server ───────────────────────────────────────────────────────────────────
+const server = new McpServer({ name: 'aicanvas-mcp', version: '0.1.0' }, { capabilities: { tools: {}, logging: {} } });
+// ── Tool: list_categories ────────────────────────────────────────────────────
+server.registerTool('list_categories', {
+    title: 'List AI Canvas categories',
+    description: 'Return every category in the AI Canvas standalone component library, with the number of components in each. Use to orient before listing or searching — e.g. "what kinds of components are available?"',
+    inputSchema: {},
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+}, async () => {
+    try {
+        const meta = await fetchMeta();
+        const lines = [
+            `AI Canvas — ${meta.componentCount} components across ${meta.categories.length} categories.`,
+            '',
+            ...meta.categories.map((c) => `  ${c.label.padEnd(24)}  ${String(c.count).padStart(3)} components`),
+        ];
+        return {
+            content: [asTextContent(lines.join('\n'))],
+            structuredContent: {
+                componentCount: meta.componentCount,
+                categories: meta.categories,
+            },
+        };
+    }
+    catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+    }
+});
+// ── Tool: list_components ────────────────────────────────────────────────────
+server.registerTool('list_components', {
+    title: 'List AI Canvas components',
+    description: 'Return AI Canvas components, optionally filtered by category. Use after `list_categories` to drill into one, or pass no filter to browse everything. Each result includes slug, name, description, categories, screenshot URL, install command, and homepage URL — enough to evaluate without a separate `get_component` call. Pagination via `limit` and `offset`.',
+    inputSchema: {
+        category: z
+            .string()
+            .optional()
+            .describe('Optional category label, e.g. "Cards & Modals", "Backgrounds", "Typography". Case-insensitive. Omit to list all components.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe('Max number of components to return. Default 25.'),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Number of components to skip (for pagination). Default 0.'),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+}, async ({ category, limit = 25, offset = 0 }) => {
+    try {
+        const meta = await fetchMeta();
+        let pool = meta.components;
+        if (category) {
+            const wanted = normalize(category);
+            pool = pool.filter((c) => c.categories.some((cat) => normalize(cat) === wanted));
+        }
+        const total = pool.length;
+        const slice = pool.slice(offset, offset + limit);
+        const summary = category != null
+            ? `${total} components in category "${category}"` +
+                (total > slice.length
+                    ? ` (showing ${slice.length} from offset ${offset})`
+                    : '')
+            : `${total} components total` +
+                (total > slice.length
+                    ? ` (showing ${slice.length} from offset ${offset})`
+                    : '');
+        return {
+            content: [asTextContent(summary + '\n\n' + JSON.stringify(slice, null, 2))],
+            structuredContent: {
+                total,
+                offset,
+                limit,
+                returned: slice.length,
+                components: slice,
+            },
+        };
+    }
+    catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+    }
+});
+// ── Tool: search_components ──────────────────────────────────────────────────
+server.registerTool('search_components', {
+    title: 'Search AI Canvas components',
+    description: 'Fuzzy keyword search across component slug, name, description, categories, and tags. Returns best matches ranked by relevance. Use when the user describes what they want in their own words, e.g. "an animated card stack", "background with waves", "typography that reveals on scroll". Results include screenshot URLs and install commands for immediate evaluation.',
+    inputSchema: {
+        query: z
+            .string()
+            .min(1)
+            .describe('Free-text search query. Multiple words are tokenized and matched independently.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Max number of matches to return. Default 10.'),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+}, async ({ query, limit = 10 }) => {
+    try {
+        const meta = await fetchMeta();
+        const ranked = meta.components
+            .map((c) => ({ component: c, score: scoreMatch(query, c) }))
+            .filter((r) => r.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map((r) => r.component);
+        const summary = ranked.length === 0
+            ? `No matches for "${query}". Try \`list_categories\` to browse what exists.`
+            : `${ranked.length} match${ranked.length === 1 ? '' : 'es'} for "${query}"`;
+        return {
+            content: [asTextContent(summary + '\n\n' + JSON.stringify(ranked, null, 2))],
+            structuredContent: { query, count: ranked.length, components: ranked },
+        };
+    }
+    catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+    }
+});
+// ── Tool: get_component ──────────────────────────────────────────────────────
+server.registerTool('get_component', {
+    title: 'Get an AI Canvas component (full metadata + source code)',
+    description: 'Return the complete record for a single component: metadata + the entire .tsx source code as a string. Use after the user picks one from a search/list result and wants to see the implementation, or before installing if they want to inspect first. The source is the exact file the CLI install would write into a project.',
+    inputSchema: {
+        slug: z
+            .string()
+            .min(1)
+            .describe('The component slug, e.g. "ai-job-cards", "wave-lines", "halo-type". Use exact slugs from list/search results.'),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+}, async ({ slug }) => {
+    try {
+        const meta = await fetchMeta();
+        const component = meta.components.find((c) => c.slug === slug);
+        if (!component) {
+            return errorResult(`No component found with slug "${slug}". Use \`search_components\` or \`list_components\` to find valid slugs.`);
+        }
+        const source = await fetchComponentSource(slug);
+        const code = source.files[0]?.content ?? '';
+        const filePath = source.files[0]?.path ?? `components/aicanvas/${slug}.tsx`;
+        const result = {
+            ...component,
+            filePath,
+            code,
+        };
+        return {
+            content: [
+                asTextContent([
+                    `# ${component.name}`,
+                    '',
+                    component.description,
+                    '',
+                    `Categories: ${component.categories.join(', ') || '(none)'}`,
+                    `Dependencies: ${component.dependencies.join(', ') || '(none)'}`,
+                    `Install: ${component.installCommand}`,
+                    `Homepage: ${component.homepageUrl}`,
+                    '',
+                    `--- ${filePath} ---`,
+                    code,
+                ].join('\n')),
+            ],
+            structuredContent: result,
+        };
+    }
+    catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+    }
+});
+// ── Tool: get_install_command ────────────────────────────────────────────────
+server.registerTool('get_install_command', {
+    title: 'Get the AI Canvas install command for a component',
+    description: 'Return the shadcn CLI command to install a single component into the user\'s project. After calling this, suggest the user run the command (or run it yourself if you have shell access). Requires shadcn-aware setup (Tailwind v4, components.json) — for projects without that, fall back to `get_component` and write the file manually.',
+    inputSchema: {
+        slug: z
+            .string()
+            .min(1)
+            .describe('The component slug, e.g. "ai-job-cards".'),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+}, async ({ slug }) => {
+    try {
+        const meta = await fetchMeta();
+        const component = meta.components.find((c) => c.slug === slug);
+        if (!component) {
+            return errorResult(`No component found with slug "${slug}". Use \`search_components\` to find valid slugs.`);
+        }
+        const out = {
+            slug: component.slug,
+            name: component.name,
+            installCommand: component.installCommand,
+            sourceUrl: component.sourceUrl,
+            homepageUrl: component.homepageUrl,
+            dependencies: component.dependencies,
+        };
+        return {
+            content: [
+                asTextContent([
+                    `Install ${component.name}:`,
+                    '',
+                    `  ${component.installCommand}`,
+                    '',
+                    `Dependencies: ${component.dependencies.join(', ') || '(none — React only)'}`,
+                    `Source: ${component.sourceUrl}`,
+                    `Preview: ${component.homepageUrl}`,
+                ].join('\n')),
+            ],
+            structuredContent: out,
+        };
+    }
+    catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+    }
+});
+// ── Boot ─────────────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdio transport runs forever — closes when host kills stdin
+}
+main().catch((err) => {
+    // stderr only — stdout is reserved for JSON-RPC
+    console.error('aicanvas-mcp fatal:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@aicanvas/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for AI Canvas — search, inspect, and install components from the aicanvas.me registry directly from your AI editor.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "aicanvas",
+    "shadcn",
+    "react",
+    "components",
+    "framer-motion"
+  ],
+  "homepage": "https://aicanvas.me",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uiNerd16/aicanvas.git",
+    "directory": "mcp"
+  },
+  "license": "MIT",
+  "author": "AI Canvas <https://aicanvas.me>",
+  "type": "module",
+  "bin": {
+    "aicanvas-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "test": "npm run build && node test/smoke.mjs && node test/offline.mjs",
+    "test:smoke": "npm run build && node test/smoke.mjs",
+    "test:offline": "npm run build && node test/offline.mjs",
+    "inspect": "npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.6.0"
+  }
+}