@aicanvas/mcp 0.1.1 → 0.2.1

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 AI Canvas account so source pulls are authorized and any premium content you own unlocks. Sent as a `Bearer` token on every registry request. Without it you are anonymous: metadata browsing still works, but pulling a component's source returns a short "create a free account" notice instead of the code. |
+
+### Accounts and premium content
+
+Browsing metadata (`list_categories`, `list_components`, `search_components`, `list_systems`, `get_install_command`) is free and needs no account. Pulling actual source (`get_component`, `get_system`, `get_template`) runs against a free AI Canvas account: set `AICANVAS_TOKEN` from your account and the website gives you the ready-made config. Without a token, a free-component source pull returns a short "create a free account" notice instead of the code, and premium content (full design systems and templates) returns HTTP 402 with an upgrade link at [aicanvas.me/pricing](https://aicanvas.me/pricing). Update anytime with `npx @aicanvas/mcp@latest`.
 
 ## 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,17 +20,27 @@ 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.1.1';
+const MCP_VERSION = '0.2.1';
 const USER_AGENT = `aicanvas-mcp/${MCP_VERSION}`;
+// Optional per-user token (the website bakes it into the copied MCP config).
+// Identifies the account so free-component source pulls are authorized and any
+// premium content you own unlocks. Absent = anonymous: metadata browsing still
+// works, but source pulls of free components need a free account.
+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', 'User-Agent': USER_AGENT },
-    });
+    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}`);
     }
@@ -39,9 +50,34 @@ async function fetchMeta() {
 }
 async function fetchComponentSource(slug) {
     const url = `${REGISTRY_BASE}/${encodeURIComponent(slug)}.json`;
-    const res = await fetch(url, {
-        headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
-    });
+    const res = await fetch(url, { headers: registryHeaders() });
+    if (res.status === 402) {
+        const j = (await res.json().catch(() => ({})));
+        throw new Error(j.message ??
+            'This is premium AI Canvas content. Upgrade at https://aicanvas.me/pricing, ' +
+                'then use the AI Canvas MCP config from your account (your token is included) ' +
+                'and update with: npx @aicanvas/mcp@latest');
+    }
+    // Free component pulled without an account: the registry returns a 200
+    // placeholder (not a 402), tagged with this header. Surface a warm sign-up
+    // CTA instead of handing the placeholder back as if it were real source.
+    if (res.headers.get('x-aicanvas-content-type') === 'free-account-required') {
+        const j = (await res.json().catch(() => ({})));
+        const name = typeof j.title === 'string'
+            ? j.title.replace(/\s*\(free account required\)\s*$/i, '')
+            : slug;
+        throw new Error(`Almost there! "${name}" is free with an AI Canvas account (free, unlimited installs). ` +
+            `Sign up at https://aicanvas.me/account/sign-up, then use the AI Canvas MCP config from ` +
+            `your account (your token is included) and ask again.`);
+    }
+    // NOTE: premium standalones ALSO return a 200 placeholder (header
+    // 'premium-standalone'), but that header value is NOT unique to the
+    // placeholder — an entitled subscriber's REAL source carries it too (the
+    // success path stamps the contentType). Keying the MCP on it would strip a
+    // paying subscriber's real component. So premium is deliberately NOT
+    // intercepted here. Closing that footgun safely needs premiumStub to emit a
+    // distinct header (like freeAccountStub's 'free-account-required'); tracked
+    // as a separate, billing-reviewed follow-up.
     if (!res.ok) {
         throw new Error(`Failed to fetch source for "${slug}" from ${url}: ${res.status} ${res.statusText}`);
     }
@@ -88,6 +124,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',
@@ -112,7 +179,7 @@ server.registerTool('list_categories', {
     try {
         const meta = await fetchMeta();
         const lines = [
-            `AI Canvas — ${meta.componentCount} components across ${meta.categories.length} categories.`,
+            `AI Canvas: ${meta.componentCount} components across ${meta.categories.length} categories.`,
             '',
             ...meta.categories.map((c) => `  ${c.label.padEnd(24)}  ${String(c.count).padStart(3)} components`),
         ];
@@ -207,14 +274,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))],
@@ -240,12 +318,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,
@@ -288,9 +395,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,
@@ -307,7 +416,7 @@ server.registerTool('get_install_command', {
                     '',
                     `  ${component.installCommand}`,
                     '',
-                    `Dependencies: ${component.dependencies.join(', ') || '(none — React only)'}`,
+                    `Dependencies: ${component.dependencies.join(', ') || '(none, React only)'}`,
                     `Source: ${component.sourceUrl}`,
                     `Preview: ${component.homepageUrl}`,
                 ].join('\n')),
@@ -319,6 +428,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,15 +1,29 @@
 {
   "name": "@aicanvas/mcp",
-  "version": "0.1.1",
+  "version": "0.2.1",
+  "mcpName": "io.github.uinerd16/aicanvas",
   "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",
+    "mcp-server",
     "aicanvas",
     "shadcn",
-    "react",
-    "components",
-    "framer-motion"
+    "shadcn-registry",
+    "shadcn-ui",
+    "react-components",
+    "ui-components",
+    "component-library",
+    "framer-motion",
+    "animated-components",
+    "tailwindcss",
+    "design-system",
+    "ai-agents",
+    "ai-coding",
+    "claude",
+    "cursor",
+    "code-generation",
+    "registry"
   ],
   "homepage": "https://aicanvas.me",
   "repository": {