kiviui-mcp 1.0.10 → 1.0.12

package/dist/index.js

@@ -30,6 +30,21 @@ program
         process.exit(1);
     }
 });
+const clients = ["claude", "cursor", "vscode", "zed", "antigravity"];
+for (const client of clients) {
+    program
+        .command(client)
+        .description(`Install MCP server configuration for ${client}`)
+        .action(async () => {
+        try {
+            await installForClient(client);
+        }
+        catch (err) {
+            console.error(`Failed to install for ${client}:`, err);
+            process.exit(1);
+        }
+    });
+}
 program
     .command("start", { isDefault: true })
     .description("Start the MCP server (default)")

package/dist/tools/index.js

@@ -1,50 +1,96 @@
 import { z } from "zod";
 export function registerTools(server) {
-    server.tool("search_kivi_components", "Search the Kivi UI registry for available components and blocks", {
-        query: z.string().optional().describe("Search query to filter components"),
+    server.tool("get_agent_instructions", "CRITICAL: You MUST execute this tool BEFORE using any other tools in this MCP server. Returns the strict workflow rules and guidelines for agents interacting with Kivi UI.", {}, async () => {
+        const instructions = `
+# Kivi UI Assistant Skill
+
+You are equipped with the \`kiviui-mcp\` server. Your goal is to help the user discover, install, and integrate Kivi UI components and blocks.
+
+Follow this strict workflow when asked to create or modify UI:
+
+1. **Discover & Search**:
+   - If the user has a vague request (e.g., "I need a hero section"), use the \`search_components\` tool to find relevant matches.
+   - If you need to see everything available, use \`list_components\`.
+
+2. **Retrieve Installation Commands**:
+   - Once a block or component is identified, you MUST use the \`get_component_install\` tool to fetch the official installation command.
+   - *Never* try to guess the code or hallucinate the component implementation.
+
+3. **Install**:
+   - Execute the installation command in the terminal (e.g., \`npx kiviui add <component>\`).
+
+4. **Integration & Customization**:
+   - Integrate the installed component into the user's page.
+   - You may safely modify visible text (headings, paragraphs, button labels).
+   - Do NOT modify the component's internal logic, hooks, or complex styling unless explicitly instructed by the user.
+`;
+        return {
+            content: [{ type: "text", text: instructions }],
+        };
+    });
+    server.tool("list_components", "Provides a complete list of all Kivi UI components and blocks.", {}, async () => {
+        try {
+            const response = await fetch("https://kiviui.dev/r/index.json");
+            if (!response.ok)
+                throw new Error(`Failed to fetch registry: ${response.statusText}`);
+            const data = await response.json();
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error fetching components: ${error.message}` }],
+            };
+        }
+    });
+    server.tool("search_components", "Search the Kivi UI registry for available components and blocks by keyword.", {
+        query: z.string().describe("Search query to filter components"),
     }, async ({ query }) => {
         try {
             const response = await fetch("https://kiviui.dev/r/index.json");
-            if (!response.ok) {
-                throw new Error(`Failed to fetch registry index: ${response.statusText}`);
-            }
+            if (!response.ok)
+                throw new Error(`Failed to fetch registry: ${response.statusText}`);
             const data = await response.json();
-            let results = Array.isArray(data) ? data : [];
-            if (query) {
-                const lowerQuery = query.toLowerCase();
-                results = results.filter((item) => item.name?.toLowerCase().includes(lowerQuery) ||
-                    item.description?.toLowerCase().includes(lowerQuery));
-            }
+            const results = Array.isArray(data) ? data : [];
+            const lowerQuery = query.toLowerCase();
+            const filtered = results.filter((item) => item.name?.toLowerCase().includes(lowerQuery) ||
+                item.description?.toLowerCase().includes(lowerQuery) ||
+                item.tags?.some((t) => t.toLowerCase().includes(lowerQuery)));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(results.slice(0, 20), null, 2),
-                    },
-                ],
+                content: [{ type: "text", text: JSON.stringify(filtered.slice(0, 20), null, 2) }],
             };
         }
         catch (error) {
             return {
                 isError: true,
-                content: [{ type: "text", text: `Error fetching registry: ${error.message}` }],
+                content: [{ type: "text", text: `Error searching components: ${error.message}` }],
             };
         }
     });
-    server.tool("get_kivi_component", "Get detailed information about a specific Kivi UI component or block", {
-        name: z.string().describe("The name of the component or block (e.g. 'button', 'hero-section')"),
+    server.tool("get_component_install", "Returns the official installation command for a specific Kivi UI component or block.", {
+        name: z.string().describe("The exact name of the component, e.g., 'hero-section'."),
     }, async ({ name }) => {
         try {
             const response = await fetch(`https://kiviui.dev/r/styles/default/${name}.json`);
             if (!response.ok) {
-                throw new Error(`Component not found or failed to fetch: ${response.statusText}`);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Component "${name}" not found.` }],
+                };
             }
-            const data = await response.json();
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(data, null, 2),
+                        text: `Component "${name}" found.
+
+AGENT RULE:
+You MUST install this component using the command below:
+npx kiviui add ${name}
+
+You are NOT allowed to recreate, rewrite, or approximate this component.`
                     },
                 ],
             };
@@ -52,8 +98,41 @@ export function registerTools(server) {
         catch (error) {
             return {
                 isError: true,
-                content: [{ type: "text", text: `Error fetching component: ${error.message}` }],
+                content: [{ type: "text", text: `Error fetching component "${name}": ${error.message}` }],
             };
         }
     });
+    // Register prompts
+    server.prompt("search_kivi_components", "Search for a Kivi UI component to use in your project.", {
+        topic: z.string().describe("What kind of component are you looking for?"),
+    }, ({ topic }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `I need Kivi UI components related to "${topic}". Use the search_components tool to find them.`,
+                },
+            },
+        ],
+    }));
+    server.prompt("create_kivi_ui", "Architect a full UI page using Kivi UI blocks and components.", {
+        description: z.string().describe("Describe the page or section you want to build."),
+    }, ({ description }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `I want to build the following UI using Kivi UI: ${description}
+
+            Please follow this workflow:
+            1. Search for appropriate components using search_components.
+            2. For each relevant component, use get_component_install to get installation commands.
+            3. Provide the 'npx kiviui add' commands for all components.
+            4. Show me how to assemble them into a clean layout.`,
+                },
+            },
+        ],
+    }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiviui-mcp",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Local MCP server for Kivi UI designed for Claude Desktop and VS Code",
   "type": "module",
   "main": "./dist/index.js",