kavel-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kavel (https://www.kavel.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# Kavel MCP
+
+An MCP server for **[Kavel](https://www.kavel.ai)** — bring Kavel's AI photo & video generators into any MCP client (Claude, Cursor, Cline, …). Ask for an effect, get a model-tuned prompt, and open the right tool to generate it on [www.kavel.ai](https://www.kavel.ai).
+
+No account or API key required to use this server — it helps you pick a tool and craft a prompt, then hands off to Kavel's free-tier generators.
+
+## What it does
+
+| Tool | What it returns |
+|---|---|
+| `list_kavel_tools` | Browse/search Kavel's generators by goal (e.g. "make my dog look royal") |
+| `build_kavel_prompt` | A model-tuned prompt recipe for a chosen effect, customized with your details |
+| `open_in_kavel` | The direct generator URL, pre-set to the right mode |
+| `list_kavel_models` | The image/video models Kavel runs and what each is good at |
+
+## Featured generators
+
+- [AI Hairstyle Changer](https://www.kavel.ai/image/ai-hairstyle-changer)
+- [AI Figurine Generator](https://www.kavel.ai/image/ai-figurine-generator)
+- [AI Pet Portrait Generator](https://www.kavel.ai/image/ai-pet-portrait-generator)
+- [AI Wedding Photo Generator](https://www.kavel.ai/image/ai-wedding-photo-generator)
+- [90s Yearbook Photos](https://www.kavel.ai/image/90s-yearbook-photos)
+- [AI Dance Video Generator](https://www.kavel.ai/video/ai-dance-video-generator)
+- [HD Photo Converter](https://www.kavel.ai/image/hd-photo-converter)
+- [Browse all →](https://www.kavel.ai)
+
+## Install
+
+Run directly with npx:
+
+```bash
+npx kavel-mcp
+```
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "kavel": {
+      "command": "npx",
+      "args": ["-y", "kavel-mcp"]
+    }
+  }
+}
+```
+
+### Cursor / Cline
+
+Point the client at the command `npx -y kavel-mcp` (stdio transport).
+
+## Develop
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## Links
+
+- Website: <https://www.kavel.ai>
+- Issues: <https://github.com/hanshs474/kavel-mcp/issues>
+
+## License
+
+MIT © [Kavel](https://www.kavel.ai)

package/dist/catalog.js

@@ -0,0 +1,200 @@
+// Kavel tool catalog — mirrors src/config/tool-pages.ts in the kavel site.
+// Keep slugs/models/hubs in sync with the site so deep links stay valid.
+export const KAVEL_BASE_URL = "https://www.kavel.ai";
+export const KAVEL_MODELS = [
+    {
+        id: "nano-banana-2-lite",
+        name: "Nano Banana 2 Lite",
+        mediaType: "image",
+        freeTier: true,
+        summary: "Fast photo-editing image model. Strong at identity-preserving image-to-image edits (change hair, outfit, style) while keeping the same face and pose.",
+    },
+    {
+        id: "veo-3-1",
+        name: "Veo 3.1",
+        mediaType: "video",
+        freeTier: true,
+        summary: "Video model for text-to-video and image-to-video. Turns a still photo into short, coherent motion clips.",
+    },
+];
+export const KAVEL_TOOLS = [
+    {
+        slug: "ai-dance-video-generator",
+        hub: "video",
+        title: "AI Dance Video Generator",
+        keyword: "AI Dance Video Generator",
+        desc: "Turn a photo into a dancing video.",
+        model: "veo-3-1",
+        scene: "image-to-video",
+        needsPhoto: true,
+        recipe: "Make the person in the photo do an energetic street dance — full body in frame, smooth on-beat moves, dynamic camera.",
+    },
+    {
+        slug: "ai-hairstyle-changer",
+        hub: "image",
+        title: "AI Hairstyle Changer",
+        keyword: "AI Hairstyle Changer",
+        desc: "Try a new hairstyle on your own photo.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Restyle the hair in the photo into a modern shoulder-length layered cut with soft waves, keeping the same face, skin, and expression. Natural lighting, photorealistic.",
+    },
+    {
+        slug: "ai-outfit-generator",
+        hub: "image",
+        title: "AI Outfit Generator",
+        keyword: "AI Outfit Generator",
+        desc: "Change the outfit on your photo.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Change the clothing in the photo into a well-tailored navy-blue blazer over a crisp white shirt, keeping the same face, hair, and pose. Photorealistic, natural fabric.",
+    },
+    {
+        slug: "ai-figurine-generator",
+        hub: "image",
+        title: "AI Figurine Generator",
+        keyword: "AI Figurine Generator",
+        desc: "Turn your photo into a collectible figurine.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn the person in the photo into a cute collectible vinyl designer figurine on a small round display base, glossy finish, keeping the same face and pose. Studio product-shot lighting, photorealistic render.",
+    },
+    {
+        slug: "ai-selfie-generator",
+        hub: "image",
+        title: "AI Selfie Generator",
+        keyword: "AI Selfie Generator",
+        desc: "Turn any photo into a polished selfie.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn this photo into a polished golden-hour portrait selfie of the same person outdoors — warm sunset backlight, softly blurred bokeh background, cinematic colour grade. Keep the same face, hair, and pose. Photorealistic.",
+    },
+    {
+        slug: "ai-muscle-generator",
+        hub: "image",
+        title: "AI Muscle Generator",
+        keyword: "AI Muscle Generator",
+        desc: "Add an athletic build to your photo.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Give the person in the photo a more muscular, athletic gym physique with broader shoulders and defined arms, keeping the same fitted shirt, face, and pose. Photorealistic, natural.",
+    },
+    {
+        slug: "ai-sticker-generator",
+        hub: "image",
+        title: "AI Sticker Generator",
+        keyword: "AI Sticker Generator",
+        desc: "Turn your photo into a die-cut sticker.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn the person in the photo into a cute die-cut vinyl sticker — bold vector cartoon style, thick white border, flat bright colours, keeping the same face, hair, and pose.",
+    },
+    {
+        slug: "ai-polaroid-generator",
+        hub: "image",
+        title: "AI Polaroid Generator",
+        keyword: "AI Polaroid Generator",
+        desc: "Turn your photo into a retro instant print.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn this photo into a vintage Polaroid instant print — classic white frame with a thick blank strip at the bottom, faded warm retro colour, soft film grain and a slight light leak. Keep the same people and pose.",
+    },
+    {
+        slug: "ai-pet-portrait-generator",
+        hub: "image",
+        title: "AI Pet Portrait Generator",
+        keyword: "AI Pet Portrait Generator",
+        desc: "Paint your pet as a royal oil painting.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn the animal in the photo into a majestic Renaissance royal oil painting of itself — ornate red velvet coat with gold embroidery and a lace collar, rich classical brushstrokes, dramatic lighting, gilded frame. Keep the same breed, face, and pose.",
+    },
+    {
+        slug: "90s-yearbook-photos",
+        hub: "image",
+        title: "90s Yearbook Photos",
+        keyword: "90s Yearbook Photos",
+        desc: "Turn a selfie into a retro class portrait.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn this into a cheesy 1990s high-school yearbook portrait of the same person — mottled blue laser studio backdrop, soft-focus glow, feathered nineties hair, a collared shirt under a sweater, faded scanned-print colour. Keep the same face.",
+    },
+    {
+        slug: "ai-wedding-photo-generator",
+        hub: "image",
+        title: "AI Wedding Photo Generator",
+        keyword: "AI Wedding Photo Generator",
+        desc: "See the two of you as a wedding portrait.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn this into an elegant wedding photograph of the same couple — a white lace gown with a bouquet and a fitted black tuxedo, at a sunlit venue with a floral arch and warm golden-hour bokeh. Keep both faces and the pose.",
+    },
+    {
+        slug: "ai-christmas-card-generator",
+        hub: "image",
+        title: "AI Christmas Card Generator",
+        keyword: "AI Christmas Card Generator",
+        desc: "Turn a photo into a festive holiday card.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn this into a festive Christmas holiday card photo of the same person — a cosy red knitted sweater and a Santa hat, beside a warmly lit decorated tree with fairy lights, a fireplace and stockings behind, snow through the window. Keep the same face.",
+    },
+    {
+        slug: "hd-photo-converter",
+        hub: "image",
+        title: "HD Photo Converter",
+        keyword: "HD Photo Converter",
+        desc: "Turn a blurry picture into a sharp HD photo.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Restore and upscale this photo into a crisp, high-definition picture of the same subject — remove the blur, the noise, and the compression artefacts, recover sharp skin texture, hair detail, and clean edges, and correct washed-out colour to natural tones. Keep the exact same person, pose, clothing, and background.",
+    },
+    {
+        slug: "ai-birthday-photoshoot-generator",
+        hub: "image",
+        title: "AI Birthday Photoshoot Generator",
+        keyword: "AI Birthday Photoshoot",
+        desc: "Turn a selfie into a cinematic birthday portrait.",
+        model: "nano-banana-2-lite",
+        scene: "image-to-image",
+        needsPhoto: true,
+        recipe: "Turn this into a cinematic birthday photoshoot of the same person — an elegant sequin party dress, gold foil number balloons and warm fairy lights behind, a softly blurred background with a candlelit birthday cake. Keep the exact same face, hair, and expression. Photorealistic.",
+    },
+];
+// Deep link to a tool's generator page. en has no locale prefix (localePrefix
+// 'as-needed'), and the page presets its own tuned prompt; the ?scene=/?mode=
+// param opens the correct tab/mode.
+export function toolUrl(tool) {
+    const param = tool.hub === "video" ? "mode" : "scene";
+    return `${KAVEL_BASE_URL}/${tool.hub}/${tool.slug}?${param}=${tool.scene}`;
+}
+export function findTool(slug) {
+    return KAVEL_TOOLS.find((t) => t.slug === slug);
+}
+// Lightweight keyword match over title/keyword/desc/slug for browse + recommend.
+export function searchTools(query) {
+    const q = query.toLowerCase().trim();
+    if (!q)
+        return KAVEL_TOOLS;
+    const words = q.split(/\s+/);
+    return KAVEL_TOOLS.map((t) => {
+        const hay = `${t.title} ${t.keyword} ${t.desc} ${t.slug}`.toLowerCase();
+        const score = words.reduce((s, w) => (hay.includes(w) ? s + 1 : s), 0);
+        return { t, score };
+    })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .map((x) => x.t);
+}

package/dist/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { KAVEL_BASE_URL, KAVEL_MODELS, KAVEL_TOOLS, findTool, searchTools, toolUrl, } from "./catalog.js";
+const server = new McpServer({
+    name: "kavel-mcp",
+    version: "0.1.0",
+});
+function toolLine(t) {
+    return `- **${t.title}** (\`${t.slug}\`) — ${t.desc} Model: ${t.model}. Input: ${t.needsPhoto ? "a photo" : "a text prompt"}. Open: ${toolUrl(t)}`;
+}
+// ── Tool 1: browse / find a Kavel generator ────────────────────────────────
+server.registerTool("list_kavel_tools", {
+    title: "List Kavel AI photo/video tools",
+    description: "Browse or search Kavel's AI photo & video generators (hairstyle changer, figurine, pet portrait, wedding photo, 90s yearbook, dance video, HD photo converter, and more). Use `query` to match a goal like 'make my dog look royal' or 'turn my selfie into a figurine'. Each result includes the direct URL on www.kavel.ai to generate it.",
+    inputSchema: {
+        query: z
+            .string()
+            .optional()
+            .describe("Optional goal or keyword to match, e.g. 'wedding photo', 'dancing video'."),
+        hub: z
+            .enum(["image", "video"])
+            .optional()
+            .describe("Optional filter: only image tools or only video tools."),
+    },
+}, async ({ query, hub }) => {
+    let results = query ? searchTools(query) : KAVEL_TOOLS;
+    if (hub)
+        results = results.filter((t) => t.hub === hub);
+    if (results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No Kavel tool matched "${query}". Browse all tools at ${KAVEL_BASE_URL}/image and ${KAVEL_BASE_URL}/video`,
+                },
+            ],
+        };
+    }
+    const body = results.map(toolLine).join("\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Kavel AI generators (${results.length}):\n\n${body}\n\nAll tools: ${KAVEL_BASE_URL}`,
+            },
+        ],
+    };
+});
+// ── Tool 2: model-tuned prompt for a chosen tool ───────────────────────────
+server.registerTool("build_kavel_prompt", {
+    title: "Build a Kavel prompt",
+    description: "Get a model-tuned prompt for a specific Kavel tool. Returns Kavel's proven prompt recipe for that effect (tuned for its model), optionally customized with the user's details. Paste the result into the generator on the tool's page.",
+    inputSchema: {
+        tool: z
+            .string()
+            .describe("The tool slug from list_kavel_tools, e.g. 'ai-figurine-generator'."),
+        customization: z
+            .string()
+            .optional()
+            .describe("Optional extra details to weave in, e.g. 'make the figurine hold a skateboard' or 'red velvet dress'."),
+    },
+}, async ({ tool, customization }) => {
+    const t = findTool(tool);
+    if (!t) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Unknown tool "${tool}". Call list_kavel_tools to see valid slugs.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const prompt = customization
+        ? `${t.recipe} Additional details: ${customization.trim()}`
+        : t.recipe;
+    const tips = t.needsPhoto
+        ? "Upload a clear, well-lit photo where the subject fills the frame."
+        : "Describe the subject, style, and setting concretely.";
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Prompt for **${t.title}** (model ${t.model}):\n\n${prompt}\n\n` +
+                    `Tip: ${tips}\n` +
+                    `Generate here: ${toolUrl(t)}`,
+            },
+        ],
+    };
+});
+// ── Tool 3: open the generator to create it ────────────────────────────────
+server.registerTool("open_in_kavel", {
+    title: "Open a Kavel generator",
+    description: "Get the direct URL to a Kavel tool's generator page (on www.kavel.ai), pre-set to the right mode with a tuned prompt, so the user can generate the result. Free-tier models let users generate without paying.",
+    inputSchema: {
+        tool: z
+            .string()
+            .describe("The tool slug from list_kavel_tools, e.g. 'ai-wedding-photo-generator'."),
+    },
+}, async ({ tool }) => {
+    const t = findTool(tool);
+    if (!t) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Unknown tool "${tool}". Call list_kavel_tools to see valid slugs.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const steps = t.needsPhoto
+        ? `1. Open ${toolUrl(t)}\n2. Upload your photo.\n3. Generate (the page presets a tuned prompt — edit it if you like).`
+        : `1. Open ${toolUrl(t)}\n2. Type your prompt.\n3. Generate.`;
+    return {
+        content: [
+            {
+                type: "text",
+                text: `**${t.title}** — generate on Kavel:\n\n${steps}`,
+            },
+        ],
+    };
+});
+// ── Tool 4: list underlying models ─────────────────────────────────────────
+server.registerTool("list_kavel_models", {
+    title: "List Kavel models",
+    description: "List the AI models Kavel runs (image and video), what each is good at, and whether it has a free tier.",
+    inputSchema: {},
+}, async () => {
+    const body = KAVEL_MODELS.map((m) => `- **${m.name}** (\`${m.id}\`, ${m.mediaType}${m.freeTier ? ", free tier" : ""}) — ${m.summary}`).join("\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Kavel models:\n\n${body}\n\nTry them: ${KAVEL_BASE_URL}`,
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logs; stdout is the MCP transport.
+    console.error("kavel-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("kavel-mcp fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "kavel-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Kavel (www.kavel.ai) — discover Kavel's AI photo/video generators, get model-tuned prompts, and open the right tool to generate. Tools: AI Hairstyle Changer, Figurine, Pet Portrait, Wedding Photo, 90s Yearbook, Dance Video, HD Photo Converter, and more.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-image-generator",
+    "ai-video-generator",
+    "nano-banana",
+    "veo",
+    "image-to-image",
+    "prompt",
+    "kavel"
+  ],
+  "homepage": "https://www.kavel.ai",
+  "bugs": {
+    "url": "https://github.com/hanshs474/kavel-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hanshs474/kavel-mcp.git"
+  },
+  "license": "MIT",
+  "author": "Kavel (https://www.kavel.ai)",
+  "type": "module",
+  "bin": {
+    "kavel-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}