@kolbo/mcp 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# @kolbo/mcp
+
+Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
+
+Generate images, videos, music, speech, and sound effects — all from natural language in your coding environment.
+
+## Quick Setup
+
+### 1. Get an API Key
+
+Create a key at [app.kolbo.ai](https://app.kolbo.ai) or via the [API](https://docs.kolbo.ai/developer-api).
+
+### 2. Add to Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "kolbo": {
+      "command": "npx",
+      "args": ["-y", "@kolbo/mcp"],
+      "env": {
+        "KOLBO_API_KEY": "kolbo_live_..."
+      }
+    }
+  }
+}
+```
+
+### 3. Use it
+
+Just ask Claude naturally:
+
+- *"Generate an image of a sunset over mountains"*
+- *"Create a 5-second video of waves crashing"*
+- *"Make a lo-fi hip hop beat"*
+- *"Convert this text to speech: Hello world"*
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `generate_image` | Generate images from text prompts |
+| `generate_video` | Generate videos from text |
+| `generate_video_from_image` | Animate an image into video |
+| `generate_music` | Generate music from descriptions |
+| `generate_speech` | Convert text to speech |
+| `generate_sound` | Generate sound effects |
+| `list_models` | Browse available AI models |
+| `check_credits` | Check credit balance |
+| `get_generation_status` | Check a generation's status |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `KOLBO_API_KEY` | Yes | Your Kolbo API key |
+| `KOLBO_API_URL` | No | Custom API URL (default: `https://api.kolbo.ai/api`) |
+
+## Links
+
+- [API Documentation](https://docs.kolbo.ai/developer-api)
+- [Kolbo AI Platform](https://kolbo.ai)
+- [Get API Key](https://app.kolbo.ai)

package/bin/kolbo-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/index.js');

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kolbo/mcp",
+  "version": "1.0.0",
+  "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
+  "main": "src/index.js",
+  "bin": {
+    "kolbo-mcp": "./bin/kolbo-mcp.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "kolbo",
+    "mcp",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "music-generation",
+    "text-to-speech",
+    "claude-code",
+    "claude-desktop",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicenathapong/kolbo-mcp"
+  },
+  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-mcp",
+  "author": "Kolbo AI <support@kolbo.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,47 @@
+/**
+ * Kolbo API HTTP client wrapper
+ */
+class KolboClient {
+  constructor() {
+    this.apiKey = process.env.KOLBO_API_KEY;
+    this.baseUrl = (process.env.KOLBO_API_URL || 'https://api.kolbo.ai/api').replace(/\/$/, '');
+
+    if (!this.apiKey) {
+      throw new Error('KOLBO_API_KEY environment variable is required');
+    }
+  }
+
+  async request(method, path, body = null) {
+    const url = `${this.baseUrl}${path}`;
+    const options = {
+      method,
+      headers: {
+        'X-API-Key': this.apiKey,
+        'Content-Type': 'application/json'
+      }
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+    const data = await response.json();
+
+    if (!response.ok || data.success === false) {
+      throw new Error(data.error || data.message || `API error: ${response.status}`);
+    }
+
+    return data;
+  }
+
+  async post(path, body) {
+    return this.request('POST', path, body);
+  }
+
+  async get(path) {
+    return this.request('GET', path);
+  }
+}
+
+module.exports = KolboClient;

package/src/index.js

@@ -0,0 +1,27 @@
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const KolboClient = require('./client');
+const { registerGenerateTools } = require('./tools/generate');
+const { registerModelTools } = require('./tools/models');
+
+async function main() {
+  const client = new KolboClient();
+
+  const server = new McpServer({
+    name: 'kolbo',
+    version: '1.0.0'
+  });
+
+  // Register all tools
+  registerGenerateTools(server, client);
+  registerModelTools(server, client);
+
+  // Start the server with stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(err => {
+  console.error('Failed to start Kolbo MCP server:', err);
+  process.exit(1);
+});

package/src/polling.js

@@ -0,0 +1,36 @@
+/**
+ * Poll a generation until it reaches a terminal state
+ */
+async function pollUntilDone(client, generationId, options = {}) {
+  const {
+    interval = 5000,
+    timeout = 300000 // 5 minutes default
+  } = options;
+
+  const startTime = Date.now();
+
+  while (true) {
+    if (Date.now() - startTime > timeout) {
+      throw new Error(`Generation ${generationId} timed out after ${timeout / 1000}s`);
+    }
+
+    const result = await client.get(`/v1/generate/${generationId}/status`);
+
+    if (result.state === 'completed') {
+      return result;
+    }
+
+    if (result.state === 'failed') {
+      throw new Error(result.error || 'Generation failed');
+    }
+
+    if (result.state === 'cancelled') {
+      throw new Error('Generation was cancelled');
+    }
+
+    // Wait before next poll
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+}
+
+module.exports = { pollUntilDone };

package/src/tools/generate.js

@@ -0,0 +1,224 @@
+const { pollUntilDone } = require('../polling');
+
+function registerGenerateTools(server, client) {
+  // ─── generate_image ────────────────────────────────────────
+  server.tool(
+    'generate_image',
+    'Generate image(s) from a text prompt using Kolbo AI. Returns the final image URL(s) when complete.',
+    {
+      prompt: { type: 'string', description: 'Text description of the image to generate' },
+      model: { type: 'string', description: 'Model identifier (e.g., "fal-ai/flux/schnell"). Use list_models to see available models. Omit for auto-selection.' },
+      aspect_ratio: { type: 'string', description: 'Aspect ratio (e.g., "1:1", "16:9", "9:16"). Default: "1:1"' },
+      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt for better results. Default: true' }
+    },
+    async ({ prompt, model, aspect_ratio, enhance_prompt }) => {
+      const gen = await client.post('/v1/generate/image', {
+        prompt, model, aspect_ratio, enhance_prompt
+      });
+
+      const result = await pollUntilDone(client, gen.generation_id, {
+        interval: (gen.poll_interval_hint || 3) * 1000,
+        timeout: 120000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result.urls,
+            model: result.result.model,
+            prompt_used: result.result.prompt_used
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_video ────────────────────────────────────────
+  server.tool(
+    'generate_video',
+    'Generate a video from a text prompt using Kolbo AI. Returns the final video URL when complete.',
+    {
+      prompt: { type: 'string', description: 'Text description of the video to generate' },
+      model: { type: 'string', description: 'Model identifier. Use list_models with type "video" to see options.' },
+      aspect_ratio: { type: 'string', description: 'Aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"' },
+      duration: { type: 'number', description: 'Duration in seconds (e.g., 5, 10). Default: 5' },
+      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt for better results. Default: true' }
+    },
+    async ({ prompt, model, aspect_ratio, duration, enhance_prompt }) => {
+      const gen = await client.post('/v1/generate/video', {
+        prompt, model, aspect_ratio, duration, enhance_prompt
+      });
+
+      const result = await pollUntilDone(client, gen.generation_id, {
+        interval: (gen.poll_interval_hint || 8) * 1000,
+        timeout: 300000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result.urls,
+            model: result.result.model,
+            duration: result.result.duration,
+            thumbnail_url: result.result.thumbnail_url,
+            prompt_used: result.result.prompt_used
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_video_from_image ─────────────────────────────
+  server.tool(
+    'generate_video_from_image',
+    'Animate an image into a video using Kolbo AI. Returns the final video URL when complete.',
+    {
+      image_url: { type: 'string', description: 'URL of the source image to animate' },
+      prompt: { type: 'string', description: 'Text description of the desired motion/animation' },
+      model: { type: 'string', description: 'Model identifier. Use list_models with type "video_from_image" to see options.' },
+      duration: { type: 'number', description: 'Duration in seconds (e.g., 5, 10). Default: 5' },
+      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' }
+    },
+    async ({ image_url, prompt, model, duration, enhance_prompt }) => {
+      const gen = await client.post('/v1/generate/video/from-image', {
+        image_url, prompt, model, duration, enhance_prompt
+      });
+
+      const result = await pollUntilDone(client, gen.generation_id, {
+        interval: (gen.poll_interval_hint || 8) * 1000,
+        timeout: 300000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result.urls,
+            model: result.result.model,
+            duration: result.result.duration,
+            thumbnail_url: result.result.thumbnail_url
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_music ────────────────────────────────────────
+  server.tool(
+    'generate_music',
+    'Generate music from a text description using Kolbo AI. Returns the final audio URL when complete.',
+    {
+      prompt: { type: 'string', description: 'Text description of the music to generate (e.g., "upbeat electronic dance track with synthesizers")' },
+      style: { type: 'string', description: 'Music style (e.g., "pop", "rock", "electronic", "jazz")' },
+      instrumental: { type: 'boolean', description: 'Generate instrumental only (no vocals). Default: false' },
+      lyrics: { type: 'string', description: 'Custom lyrics for the song' }
+    },
+    async ({ prompt, style, instrumental, lyrics }) => {
+      const gen = await client.post('/v1/generate/music', {
+        prompt, style, instrumental, lyrics
+      });
+
+      const result = await pollUntilDone(client, gen.generation_id, {
+        interval: (gen.poll_interval_hint || 8) * 1000,
+        timeout: 300000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result.urls,
+            title: result.result.title,
+            duration: result.result.duration,
+            lyrics: result.result.lyrics
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_speech ───────────────────────────────────────
+  server.tool(
+    'generate_speech',
+    'Convert text to speech using Kolbo AI. Returns the final audio URL when complete.',
+    {
+      text: { type: 'string', description: 'The text to convert to speech' },
+      voice: { type: 'string', description: 'Voice ID or name (e.g., "Rachel", "Adam"). Default: "Rachel"' },
+      language: { type: 'string', description: 'Language code (e.g., "en-US", "he-IL"). Default: "en-US"' }
+    },
+    async ({ text, voice, language }) => {
+      const gen = await client.post('/v1/generate/speech', {
+        text, voice, language
+      });
+
+      const result = await pollUntilDone(client, gen.generation_id, {
+        interval: (gen.poll_interval_hint || 5) * 1000,
+        timeout: 120000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result.urls,
+            voice: result.result.voice,
+            duration: result.result.duration
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_sound ────────────────────────────────────────
+  server.tool(
+    'generate_sound',
+    'Generate sound effects from a text description using Kolbo AI. Returns the final audio URL when complete.',
+    {
+      prompt: { type: 'string', description: 'Text description of the sound effect (e.g., "thunder clap with rain", "door creaking open")' },
+      duration: { type: 'number', description: 'Duration in seconds. Omit for auto duration.' }
+    },
+    async ({ prompt, duration }) => {
+      const gen = await client.post('/v1/generate/sound', {
+        prompt, duration
+      });
+
+      const result = await pollUntilDone(client, gen.generation_id, {
+        interval: (gen.poll_interval_hint || 5) * 1000,
+        timeout: 120000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result.urls,
+            duration: result.result.duration
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_generation_status ─────────────────────────────────
+  server.tool(
+    'get_generation_status',
+    'Check the status of a generation. Use this if a generation tool timed out or you need to check progress.',
+    {
+      generation_id: { type: 'string', description: 'The generation ID to check' }
+    },
+    async ({ generation_id }) => {
+      const result = await client.get(`/v1/generate/${generation_id}/status`);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerGenerateTools };

package/src/tools/models.js

@@ -0,0 +1,48 @@
+function registerModelTools(server, client) {
+  // ─── list_models ───────────────────────────────────────────
+  server.tool(
+    'list_models',
+    'List available AI models on Kolbo. Filter by type to find models for a specific generation type.',
+    {
+      type: {
+        type: 'string',
+        description: 'Filter by type: "image", "video", "video_from_image", "music", "speech", "sound". Omit for all models.'
+      }
+    },
+    async ({ type }) => {
+      const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
+      const result = await client.get(path);
+
+      // Format for readability
+      const summary = result.models.map(m =>
+        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}`
+      ).join('\n');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `Available models (${result.count}):\n\n${summary}\n\nUse the "identifier" value as the "model" parameter in generate tools.`
+        }]
+      };
+    }
+  );
+
+  // ─── check_credits ─────────────────────────────────────────
+  server.tool(
+    'check_credits',
+    'Check your remaining Kolbo credit balance.',
+    {},
+    async () => {
+      const result = await client.get('/v1/account/credits');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `Credit Balance:\n- Total: ${result.credits.total}\n- Plan credits: ${result.credits.plan_credits}\n- Credit pack: ${result.credits.credit_pack}\n- Redemption: ${result.credits.redemption}`
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerModelTools };