@aicanvas/mcp 0.1.0 → 0.2.0

package/README.md

@@ -13,18 +13,23 @@ 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:
+Eight tools, derived from the live [aicanvas.me](https://aicanvas.me) registry. Adding a component to the website auto-updates the MCP within minutes. The registry holds 75 standalone components, plus the Andromeda design system with its own components and templates.
 
 | 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. |
+| `list_components` | Browse standalone components, optionally filtered by category. Paginated. |
+| `search_components` | Fuzzy keyword search across standalone AND design-system components (slugs, names, descriptions, categories, tags). Ranked results. |
+| `get_component` | Full metadata plus complete `.tsx` source code for one component. Resolves both standalone slugs and design-system component slugs (e.g. `andromeda-heat-grid`). |
+| `get_install_command` | Get the `npx shadcn add @aicanvas/<slug>` command for any standalone or design-system component. |
+| `list_systems` | List the design systems available (e.g. Andromeda), with component and template counts. |
+| `get_system` | Every file for a whole design system, plus its shared tokens, its component install commands, and the dependency chain. |
+| `get_template` | Every file for a single template (a ready-made composition), with the registry dependencies it pulls in. |
 
 All tools are read-only. Nothing is mutated on AI Canvas's side.
 
+Standalone components and design-system components are kept in separate buckets. `list_components` and `list_categories` cover the 75 standalones only, so the catalog stays clean. Design-system components are reached through `list_systems` / `get_system`, and are also resolvable by slug through `get_component`, `get_install_command`, and `search_components`.
+
 ## Setup
 
 ### Claude Desktop
@@ -100,7 +105,7 @@ 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.
+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:
 
@@ -115,10 +120,15 @@ This opens a browser UI where you can call each tool by hand.
 | 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. |
+| `AICANVAS_TOKEN` | _(none)_ | Optional per-account token. The website bakes it into the MCP config it gives you. It identifies your account so pulls count against the right quota and unlock premium content. Sent as a `Bearer` token on every registry request. Absent means anonymous, which is subject to the daily free limit. |
+
+### Daily limits and premium content
+
+Anonymous use is capped by a daily free limit, and some content (such as full design systems) is premium. When you hit the limit or request gated content without entitlement, a source fetch returns HTTP 402 and the tool reports a clear message: upgrade at [aicanvas.me/pricing](https://aicanvas.me/pricing), set `AICANVAS_TOKEN` to use your account, and update with `npx @aicanvas/mcp@latest`. Metadata browsing (`list_categories`, `list_components`, `search_components`, `list_systems`) is not gated. The 402 only affects source fetches (`get_component`, `get_system`, `get_template`).
 
 ## 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 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).
 
@@ -141,4 +151,4 @@ Edit `src/index.ts`, run `npm run build`, restart your AI editor.
 
 ## License
 
-MIT — same as the AI Canvas project.
+MIT, same as the AI Canvas project.

package/dist/index.js

@@ -7,7 +7,8 @@
  * inspect, and install components without leaving the chat.
  *
  * Data flow:
- *   - aicanvas.me/r/aicanvas-mcp.json   → all 64+ components' metadata
+ *   - aicanvas.me/r/aicanvas-mcp.json   → metadata for the 75 standalone
+ *     components plus the Andromeda design system, its components, and templates
  *   - aicanvas.me/r/<slug>.json         → full source code per component
  *
  * Both are static files, served from Vercel's CDN. Stateless server.
@@ -19,15 +20,26 @@ import { z } from 'zod';
 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
+const MCP_VERSION = '0.2.0';
+const USER_AGENT = `aicanvas-mcp/${MCP_VERSION}`;
+// Optional per-user token (the website bakes it into the copied MCP config).
+// Identifies the account so pulls count against the right quota and unlock
+// premium content. Absent = anonymous (subject to the daily free limit).
+const USER_TOKEN = process.env.AICANVAS_TOKEN ?? '';
+function registryHeaders() {
+    return {
+        Accept: 'application/json',
+        'User-Agent': USER_AGENT,
+        ...(USER_TOKEN ? { Authorization: `Bearer ${USER_TOKEN}` } : {}),
+    };
+}
 // ── 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' },
-    });
+    const res = await fetch(META_URL, { headers: registryHeaders() });
     if (!res.ok) {
         throw new Error(`Failed to fetch AI Canvas registry meta from ${META_URL}: ${res.status} ${res.statusText}`);
     }
@@ -37,7 +49,14 @@ async function fetchMeta() {
 }
 async function fetchComponentSource(slug) {
     const url = `${REGISTRY_BASE}/${encodeURIComponent(slug)}.json`;
-    const res = await fetch(url, { headers: { Accept: 'application/json' } });
+    const res = await fetch(url, { headers: registryHeaders() });
+    if (res.status === 402) {
+        const j = (await res.json().catch(() => ({})));
+        throw new Error(j.message ??
+            'This requires AI Canvas Premium, or you have hit the daily free limit. ' +
+                'Upgrade at https://aicanvas.me/pricing. Set AICANVAS_TOKEN to use your account, ' +
+                'and update with: npx @aicanvas/mcp@latest');
+    }
     if (!res.ok) {
         throw new Error(`Failed to fetch source for "${slug}" from ${url}: ${res.status} ${res.statusText}`);
     }
@@ -84,6 +103,37 @@ function scoreMatch(query, c) {
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+// Minimal searchable surface for design-system components — slug, name,
+// description, and the system name. Mirrors scoreMatch's token logic so DS
+// components rank alongside standalones in search results.
+function scoreSystemComponent(query, c) {
+    const q = normalize(query);
+    if (!q)
+        return 0;
+    const tokens = q.split(/\s+/).filter((t) => t.length > 2);
+    if (tokens.length === 0)
+        return 0;
+    const fields = [
+        { text: normalize(c.slug), weight: 5 },
+        { text: normalize(c.name), weight: 4 },
+        { text: normalize(c.description), weight: 1 },
+        { text: normalize(c.system), weight: 2 },
+    ];
+    let score = 0;
+    for (const tok of tokens) {
+        for (const f of fields) {
+            if (!f.text)
+                continue;
+            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 asTextContent(value) {
     return {
         type: 'text',
@@ -97,7 +147,7 @@ function errorResult(message) {
     };
 }
 // ── Server ───────────────────────────────────────────────────────────────────
-const server = new McpServer({ name: 'aicanvas-mcp', version: '0.1.0' }, { capabilities: { tools: {}, logging: {} } });
+const server = new McpServer({ name: 'aicanvas-mcp', version: MCP_VERSION }, { capabilities: { tools: {}, logging: {} } });
 // ── Tool: list_categories ────────────────────────────────────────────────────
 server.registerTool('list_categories', {
     title: 'List AI Canvas categories',
@@ -203,14 +253,25 @@ server.registerTool('search_components', {
 }, async ({ query, limit = 10 }) => {
     try {
         const meta = await fetchMeta();
-        const ranked = meta.components
-            .map((c) => ({ component: c, score: scoreMatch(query, c) }))
+        // Rank standalones AND design-system components together so DS slugs
+        // (e.g. "andromeda-heat-grid") surface in search. Each result object stays
+        // usable: standalones keep their full shape; DS components carry their
+        // metadata (slug, name, description, system, install command, …).
+        const standaloneRanked = meta.components.map((c) => ({
+            item: c,
+            score: scoreMatch(query, c),
+        }));
+        const systemRanked = (meta.systemComponents ?? []).map((c) => ({
+            item: c,
+            score: scoreSystemComponent(query, c),
+        }));
+        const ranked = [...standaloneRanked, ...systemRanked]
             .filter((r) => r.score > 0)
             .sort((a, b) => b.score - a.score)
             .slice(0, limit)
-            .map((r) => r.component);
+            .map((r) => r.item);
         const summary = ranked.length === 0
-            ? `No matches for "${query}". Try \`list_categories\` to browse what exists.`
+            ? `No matches for "${query}". Try \`list_categories\` to browse standalones, or \`list_systems\` for design systems.`
             : `${ranked.length} match${ranked.length === 1 ? '' : 'es'} for "${query}"`;
         return {
             content: [asTextContent(summary + '\n\n' + JSON.stringify(ranked, null, 2))],
@@ -236,12 +297,41 @@ server.registerTool('get_component', {
     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.`);
+        // Fall back to design-system components (kept out of components[]).
+        const systemComponent = component
+            ? undefined
+            : (meta.systemComponents ?? []).find((c) => c.slug === slug);
+        if (!component && !systemComponent) {
+            return errorResult(`No component found with slug "${slug}". Use \`search_components\` or \`list_components\` to find standalone slugs, ` +
+                `or \`list_systems\` / \`get_system\` for design-system components (e.g. "andromeda-heat-grid").`);
         }
         const source = await fetchComponentSource(slug);
         const code = source.files[0]?.content ?? '';
         const filePath = source.files[0]?.path ?? `components/aicanvas/${slug}.tsx`;
+        if (systemComponent) {
+            const result = { ...systemComponent, filePath, code };
+            return {
+                content: [
+                    asTextContent([
+                        `# ${systemComponent.name}`,
+                        '',
+                        systemComponent.description,
+                        '',
+                        `Design system: ${systemComponent.system}`,
+                        `Dependencies: ${systemComponent.dependencies.join(', ') || '(none)'}`,
+                        `Registry dependencies: ${(systemComponent.registryDependencies ?? []).join(', ') || '(none)'}`,
+                        `Install: ${systemComponent.installCommand}`,
+                        `Homepage: ${systemComponent.homepageUrl}`,
+                        '',
+                        'Note: a manual (non-CLI) write must ALSO install the shared tokens this component depends on (see registry dependencies above and `get_system`). The CLI install resolves them automatically.',
+                        '',
+                        `--- ${filePath} ---`,
+                        code,
+                    ].join('\n')),
+                ],
+                structuredContent: result,
+            };
+        }
         const result = {
             ...component,
             filePath,
@@ -284,9 +374,11 @@ server.registerTool('get_install_command', {
 }, async ({ slug }) => {
     try {
         const meta = await fetchMeta();
-        const component = meta.components.find((c) => c.slug === slug);
+        const component = meta.components.find((c) => c.slug === slug) ??
+            (meta.systemComponents ?? []).find((c) => c.slug === slug);
         if (!component) {
-            return errorResult(`No component found with slug "${slug}". Use \`search_components\` to find valid slugs.`);
+            return errorResult(`No component found with slug "${slug}". Use \`search_components\` to find standalone slugs, ` +
+                `or \`list_systems\` / \`get_system\` for design-system components.`);
         }
         const out = {
             slug: component.slug,
@@ -315,6 +407,144 @@ server.registerTool('get_install_command', {
         return errorResult(err instanceof Error ? err.message : String(err));
     }
 });
+// ── Tool: list_systems ───────────────────────────────────────────────────────
+server.registerTool('list_systems', {
+    title: 'List AI Canvas design systems',
+    description: 'Return every design system available on AI Canvas. A design system is a coordinated set of components plus shared tokens and utilities — installable in one CLI command. Use when the user asks about "themes", "design systems", or wants more than a single component.',
+    inputSchema: {},
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+}, async () => {
+    try {
+        const meta = await fetchMeta();
+        const systems = meta.systems ?? [];
+        if (systems.length === 0) {
+            return {
+                content: [asTextContent('No design systems available in this registry build.')],
+                structuredContent: { systems: [] },
+            };
+        }
+        const lines = [
+            `${systems.length} design system${systems.length === 1 ? '' : 's'} on AI Canvas:`,
+            '',
+            ...systems.map((s) => `  ${s.name.padEnd(16)}  ${String(s.componentCount).padStart(2)} components, ${s.templateSlugs.length} templates`),
+            '',
+            'Use `get_system` to fetch the full source of a system, or `get_template` for a single composition.',
+        ];
+        return {
+            content: [asTextContent(lines.join('\n'))],
+            structuredContent: { systems },
+        };
+    }
+    catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+    }
+});
+// ── Tool: get_system ─────────────────────────────────────────────────────────
+server.registerTool('get_system', {
+    title: 'Get a complete AI Canvas design system (every file)',
+    description: 'Return all files for a design system in a single response — every component, plus shared tokens and utilities — ready to write into the user\'s project. Use when the user wants to adopt a whole system rather than pick individual components.',
+    inputSchema: {
+        slug: z
+            .string()
+            .min(1)
+            .describe('Design system slug, e.g. "andromeda". Use `list_systems` to discover.'),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+}, async ({ slug }) => {
+    try {
+        const meta = await fetchMeta();
+        const system = (meta.systems ?? []).find((s) => s.slug === slug);
+        if (!system) {
+            return errorResult(`No design system found with slug "${slug}". Use \`list_systems\` to see what's available.`);
+        }
+        const item = await fetchComponentSource(slug);
+        // The system's own design-system components, with their per-component
+        // install commands — so an agent can install (or hand-write) any subset.
+        const components = (meta.systemComponents ?? []).filter((c) => c.system === system.slug ||
+            (system.componentSlugs ?? []).includes(c.slug));
+        const summary = [
+            `# ${system.name} design system`,
+            '',
+            system.description,
+            '',
+            `Files: ${item.files.length}`,
+            `Dependencies: ${system.dependencies.join(', ') || '(none)'}`,
+            `Registry dependencies: ${(system.registryDependencies ?? []).join(', ') || '(none)'}`,
+            `Install (whole system): ${system.installCommand}`,
+            ...(system.tokensInstallCommand
+                ? [`Install (shared tokens only): ${system.tokensInstallCommand}`]
+                : []),
+            ...(system.tokensSourceUrl ? [`Tokens source: ${system.tokensSourceUrl}`] : []),
+            `Homepage: ${system.homepageUrl}`,
+            '',
+            'Note: the shared tokens ship as a SEPARATE registry dependency. For a manual (non-CLI) file write you must ALSO install the tokens (see "Install (shared tokens only)" above); the CLI resolves them automatically.',
+            '',
+            `--- components (${components.length}) ---`,
+            ...components.map((c) => `  ${c.slug.padEnd(28)}  ${c.installCommand}`),
+            '',
+            `--- file index ---`,
+            ...item.files.map((f) => `  ${f.path}`),
+        ].join('\n');
+        return {
+            content: [asTextContent(summary)],
+            structuredContent: {
+                ...system,
+                components,
+                files: item.files,
+            },
+        };
+    }
+    catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+    }
+});
+// ── Tool: get_template ───────────────────────────────────────────────────────
+server.registerTool('get_template', {
+    title: 'Get a complete AI Canvas design-system template (every file)',
+    description: 'Return all files for a single template — the example composition plus every component it uses plus shared tokens. Use for "I want exactly this dashboard" / "give me the entire mission-control screen". One CLI command installs all files.',
+    inputSchema: {
+        slug: z
+            .string()
+            .min(1)
+            .describe('Template slug, e.g. "andromeda-mission-control", "andromeda-exchange-terminal". Use `list_systems` then inspect templateSlugs to discover.'),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+}, async ({ slug }) => {
+    try {
+        const meta = await fetchMeta();
+        const template = (meta.templates ?? []).find((t) => t.slug === slug);
+        if (!template) {
+            return errorResult(`No template found with slug "${slug}". Use \`list_systems\` to see available templates.`);
+        }
+        const item = await fetchComponentSource(slug);
+        const summary = [
+            `# ${template.name} (${template.system}${template.domain ? ` · ${template.domain}` : ''})`,
+            '',
+            template.description,
+            '',
+            `Files: ${item.files.length}`,
+            `Dependencies: ${template.dependencies.join(', ') || '(none)'}`,
+            `Registry dependencies: ${(template.registryDependencies ?? []).join(', ') || '(none)'}`,
+            `Install: ${template.installCommand}`,
+            `Preview: ${template.homepageUrl}`,
+            '',
+            'Note: a manual (non-CLI) file write must ALSO install the registry dependencies above (the base components + shared tokens) for the composition to build. The CLI install resolves them automatically.',
+            '',
+            `--- file index ---`,
+            ...item.files.map((f) => `  ${f.path}`),
+        ].join('\n');
+        return {
+            content: [asTextContent(summary)],
+            structuredContent: {
+                ...template,
+                files: item.files,
+            },
+        };
+    }
+    catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+    }
+});
 // ── Boot ─────────────────────────────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicanvas/mcp",
-  "version": "0.1.0",
+  "version": "0.2.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",