vibedsgn-mcp 1.2.0

package/README.md

@@ -0,0 +1,159 @@
+# vibedsgn-mcp
+
+MCP server for posting designs to [Vibedsgn](https://vibedsgn.com) from AI agents like Claude Code, Cursor, Codex, and any other MCP-compatible tool.
+
+Built for agents — every tool has a workflow-explaining description, structured error codes, and a `whoami` pre-flight so your agent can fail fast on bad auth.
+
+## Quick Start
+
+### 1. Get your API key
+
+1. Go to [vibedsgn.com/settings](https://vibedsgn.com/settings)
+2. Scroll to **API Key** section
+3. Click **Generate API Key**
+4. Copy the key (it's shown only once — starts with `vdsgn_`)
+
+### 2. Configure your agent
+
+**Option A: Interactive setup**
+
+```bash
+npx vibedsgn-mcp init
+```
+
+**Option B: Manual configuration**
+
+<details>
+<summary>Claude Code (~/.claude.json)</summary>
+
+```json
+{
+  "mcpServers": {
+    "vibedsgn": {
+      "command": "npx",
+      "args": ["-y", "vibedsgn-mcp"],
+      "env": {
+        "VIBEDSGN_API_KEY": "vdsgn_your_key_here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Cursor (~/.cursor/mcp.json)</summary>
+
+```json
+{
+  "mcpServers": {
+    "vibedsgn": {
+      "command": "npx",
+      "args": ["-y", "vibedsgn-mcp"],
+      "env": {
+        "VIBEDSGN_API_KEY": "vdsgn_your_key_here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## Tools
+
+### `whoami`
+
+Verify the API key and return the authenticated user. **Call this first** to confirm auth before doing real work — cheap, no DB writes.
+
+Returns: `{ user: { id, name, handle, image } }`
+
+### `list_design_tools`
+
+Browse the design tool registry on Vibedsgn so you can pick a valid `primaryToolId` for `post_vibe`.
+
+| Param | Type | Notes |
+|-------|------|-------|
+| `category` | string | Exact category match: `ai-design`, `ai-agents`, `design-skills`, `ai-stack` |
+| `slug` | string | Exact tool slug lookup (case-insensitive) |
+| `q` | string | Fuzzy substring across name/slug/description |
+
+All params optional; multiple combine with AND. No params returns the full registry.
+
+Returns: `{ count, tools: [{ id, name, slug, category, description }] }`
+
+### `post_vibe`
+
+Publish a design to Vibedsgn. Vibes go live immediately — no draft step.
+
+**Workflow:**
+1. Call `whoami` to confirm auth
+2. Call `list_design_tools` (with `q: "cursor"` or similar) to pick `primaryToolId`
+3. **(Optional)** Call `post_vibe` with `dryRun: true` to preview the predicted slug + tool name without uploading or publishing — useful for "show the user, then commit" flows
+4. Call `post_vibe` with the title, primaryToolId, and **either** `desktopImageUrl` (a public URL — preferred) **or** `desktopImage` (base64 PNG, max 4MB)
+
+**Required fields:**
+- `title` — Project name
+- `primaryToolId` — Tool ID from `list_design_tools`
+- `desktopImageUrl` *or* `desktopImage` — at least one
+
+**Optional fields:**
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `description` | string | 1-2 sentences |
+| `desktopImageUrl` | url | Preferred. Server fetches and uploads. |
+| `desktopImage` | base64 | Fallback. Slower because base64 doubles payload. |
+| `mobileImageUrl` / `mobileImage` | url / base64 | Optional mobile screenshot |
+| `tags` | string[] | Free-form curation tags |
+| `systemPrompt` | string | Generation prompt used |
+| `processNotes` | string | Notes about the build process |
+| `aiStack` | object | `{ codingAgents?, imageGen?, videoGen?, other? }` — all inner arrays optional |
+| `designSystem` | object | `{ colors?, typography? }` |
+| `liveUrl` | url | Live project URL |
+| `githubUrl` | url | GitHub repo URL |
+| `dryRun` | boolean | When `true`, validate inputs and return the predicted slug + tool without uploading or publishing. No DB write, no Vercel Blob call. Default `false`. |
+
+Returns: `{ id, slug, url, message }` — `url` is the absolute https URL of the published vibe.
+
+When `dryRun: true`, returns: `{ dryRun: true, wouldCreate: { slug, url, title, primaryTool: { id, name, slug } }, message }` instead. No `id` because no row is created.
+
+### `delete_vibe`
+
+Permanently delete a vibe you own. Cascades to likes, bookmarks, comments, and notifications. **Irreversible.**
+
+| Param | Type | Notes |
+|-------|------|-------|
+| `id` | string | The vibe id returned by `post_vibe` |
+
+You can only delete vibes owned by the authenticated user. Attempts to delete someone else's vibe return `NOT_FOUND` (we don't distinguish from "doesn't exist", to avoid leaking ownership info).
+
+## Error format
+
+All tools return errors in a structured format your agent can branch on:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "UNAUTHORIZED" | "VALIDATION_ERROR" | "NOT_FOUND" | "RATE_LIMIT" | "INTERNAL" | "...",
+    "message": "Human-readable description",
+    "details": { "...optional..." }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `VIBEDSGN_API_KEY` | Yes* | Your API key from vibedsgn.com/settings |
+| `VIBEDSGN_API_URL` | No | Custom API base (default: `https://vibedsgn.com`) |
+| `VIBEDSGN_SESSION_TOKEN` | No | Alternative: OAuth session token |
+
+*Either `VIBEDSGN_API_KEY` or `VIBEDSGN_SESSION_TOKEN` is required.
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var p = __toESM(require("@clack/prompts"), 1);
+var import_fs = __toESM(require("fs"), 1);
+var import_path = __toESM(require("path"), 1);
+var import_os = __toESM(require("os"), 1);
+var CLAUDE_CONFIG_PATH = import_path.default.join(import_os.default.homedir(), ".claude.json");
+var CURSOR_CONFIG_PATH = import_path.default.join(import_os.default.homedir(), ".cursor", "mcp.json");
+function getMcpServerConfig(apiKey, apiUrl) {
+  const env = { VIBEDSGN_API_KEY: apiKey };
+  if (apiUrl) env.VIBEDSGN_API_URL = apiUrl;
+  return {
+    command: "npx",
+    args: ["-y", "vibedsgn-mcp"],
+    env
+  };
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args[0] !== "init") {
+    console.log("Usage: vibedsgn-mcp init");
+    console.log("  Interactive setup for Claude Code, Cursor, or other MCP-compatible agents.");
+    process.exit(0);
+  }
+  p.intro("Vibedsgn MCP Server Setup");
+  const apiKey = await p.text({
+    message: "Enter your Vibedsgn API key:",
+    placeholder: "vdsgn_...",
+    validate: (val) => {
+      if (!val || !val.startsWith("vdsgn_")) return "API key must start with vdsgn_";
+      if (val.length < 20) return "API key is too short";
+      return void 0;
+    }
+  });
+  if (p.isCancel(apiKey)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  const customUrl = await p.confirm({
+    message: "Use custom API URL? (default: https://vibedsgn.com)",
+    initialValue: false
+  });
+  if (p.isCancel(customUrl)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  let apiUrl;
+  if (customUrl) {
+    const url = await p.text({
+      message: "Enter API URL:",
+      placeholder: "https://vibedsgn.com"
+    });
+    if (p.isCancel(url)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    apiUrl = url;
+  }
+  const agent = await p.select({
+    message: "Which AI agent are you configuring?",
+    options: [
+      { value: "claude", label: "Claude Code", hint: "~/.claude.json" },
+      { value: "cursor", label: "Cursor", hint: "~/.cursor/mcp.json" },
+      { value: "manual", label: "Other / Manual", hint: "Print config to copy" }
+    ]
+  });
+  if (p.isCancel(agent)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  const serverConfig = getMcpServerConfig(apiKey, apiUrl);
+  if (agent === "manual") {
+    p.note(
+      JSON.stringify({ mcpServers: { vibedsgn: serverConfig } }, null, 2),
+      "Add this to your MCP configuration file:"
+    );
+    p.outro("Done! Add the config above to your agent's MCP settings.");
+    return;
+  }
+  const configPath = agent === "claude" ? CLAUDE_CONFIG_PATH : CURSOR_CONFIG_PATH;
+  const configDir = import_path.default.dirname(configPath);
+  let config = {};
+  if (import_fs.default.existsSync(configPath)) {
+    try {
+      config = JSON.parse(import_fs.default.readFileSync(configPath, "utf-8"));
+    } catch {
+      p.log.warn(`Could not parse existing ${configPath} \u2014 will create new.`);
+    }
+  }
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+  config.mcpServers.vibedsgn = serverConfig;
+  if (!import_fs.default.existsSync(configDir)) {
+    import_fs.default.mkdirSync(configDir, { recursive: true });
+  }
+  import_fs.default.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  p.outro(`Config written to ${configPath}. Restart your agent to activate.`);
+}
+main().catch((err) => {
+  console.error("Setup failed:", err);
+  process.exit(1);
+});

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import * as p from "@clack/prompts";
+import fs from "fs";
+import path from "path";
+import os from "os";
+var CLAUDE_CONFIG_PATH = path.join(os.homedir(), ".claude.json");
+var CURSOR_CONFIG_PATH = path.join(os.homedir(), ".cursor", "mcp.json");
+function getMcpServerConfig(apiKey, apiUrl) {
+  const env = { VIBEDSGN_API_KEY: apiKey };
+  if (apiUrl) env.VIBEDSGN_API_URL = apiUrl;
+  return {
+    command: "npx",
+    args: ["-y", "vibedsgn-mcp"],
+    env
+  };
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args[0] !== "init") {
+    console.log("Usage: vibedsgn-mcp init");
+    console.log("  Interactive setup for Claude Code, Cursor, or other MCP-compatible agents.");
+    process.exit(0);
+  }
+  p.intro("Vibedsgn MCP Server Setup");
+  const apiKey = await p.text({
+    message: "Enter your Vibedsgn API key:",
+    placeholder: "vdsgn_...",
+    validate: (val) => {
+      if (!val || !val.startsWith("vdsgn_")) return "API key must start with vdsgn_";
+      if (val.length < 20) return "API key is too short";
+      return void 0;
+    }
+  });
+  if (p.isCancel(apiKey)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  const customUrl = await p.confirm({
+    message: "Use custom API URL? (default: https://vibedsgn.com)",
+    initialValue: false
+  });
+  if (p.isCancel(customUrl)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  let apiUrl;
+  if (customUrl) {
+    const url = await p.text({
+      message: "Enter API URL:",
+      placeholder: "https://vibedsgn.com"
+    });
+    if (p.isCancel(url)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    apiUrl = url;
+  }
+  const agent = await p.select({
+    message: "Which AI agent are you configuring?",
+    options: [
+      { value: "claude", label: "Claude Code", hint: "~/.claude.json" },
+      { value: "cursor", label: "Cursor", hint: "~/.cursor/mcp.json" },
+      { value: "manual", label: "Other / Manual", hint: "Print config to copy" }
+    ]
+  });
+  if (p.isCancel(agent)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  const serverConfig = getMcpServerConfig(apiKey, apiUrl);
+  if (agent === "manual") {
+    p.note(
+      JSON.stringify({ mcpServers: { vibedsgn: serverConfig } }, null, 2),
+      "Add this to your MCP configuration file:"
+    );
+    p.outro("Done! Add the config above to your agent's MCP settings.");
+    return;
+  }
+  const configPath = agent === "claude" ? CLAUDE_CONFIG_PATH : CURSOR_CONFIG_PATH;
+  const configDir = path.dirname(configPath);
+  let config = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    } catch {
+      p.log.warn(`Could not parse existing ${configPath} \u2014 will create new.`);
+    }
+  }
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+  config.mcpServers.vibedsgn = serverConfig;
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  p.outro(`Config written to ${configPath}. Restart your agent to activate.`);
+}
+main().catch((err) => {
+  console.error("Setup failed:", err);
+  process.exit(1);
+});