klamdo-mcp 1.0.0 → 1.1.0

package/src/index.ts

@@ -1,360 +1,45 @@
 #!/usr/bin/env node
 /**
- * Klamdo MCP Server
+ * Klamdo MCP Server — stdio transport (for Claude Desktop local use)
  *
- * Exposes Klamdo's AI content generation to Claude Desktop and other
- * MCP-compatible clients. Lets AI assistants generate identity-locked
- * 4K images and 5-second vertical videos on behalf of the user.
- *
- * Setup:
- *   1. Create a Klamdo account at https://klamdo.app
- *   2. Get your API key from your profile page
- *   3. Add to Claude Desktop config:
- *      { "mcpServers": { "klamdo": { "command": "npx", "args": ["klamdo-mcp"], "env": { "KLAMDO_API_KEY": "<your-key>" } } } }
+ * Setup in Claude Desktop config:
+ * {
+ *   "mcpServers": {
+ *     "klamdo": {
+ *       "command": "npx",
+ *       "args": ["klamdo-mcp"],
+ *       "env": { "KLAMDO_API_KEY": "<your-key-from-klamdo.app/profile>" }
+ *     }
+ *   }
+ * }
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ErrorCode,
-  ListResourcesRequestSchema,
-  ListToolsRequestSchema,
-  McpError,
-  ReadResourceRequestSchema
-} from "@modelcontextprotocol/sdk/types.js";
+import { registerHandlers } from "./tools.js";
 
-const BASE_URL = process.env.KLAMDO_BASE_URL ?? "https://klamdo.app";
 const API_KEY = process.env.KLAMDO_API_KEY ?? "";
 
 if (!API_KEY) {
   process.stderr.write(
-    "[klamdo-mcp] Warning: KLAMDO_API_KEY is not set. All API calls will fail. " +
-    "Set it in your MCP client config.\n"
+    "[klamdo-mcp] Warning: KLAMDO_API_KEY is not set. Set it in your MCP client config.\n"
   );
 }
 
-async function klamdo<T>(path: string, body?: Record<string, unknown>): Promise<T> {
-  const res = await fetch(`${BASE_URL}/api/mcp${path}`, {
-    method: body ? "POST" : "GET",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${API_KEY}`
-    },
-    body: body ? JSON.stringify(body) : undefined
-  });
-
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new McpError(
-      ErrorCode.InternalError,
-      `Klamdo API error ${res.status}: ${text.slice(0, 200)}`
-    );
-  }
-
-  return res.json() as Promise<T>;
-}
-
-// ── Tool definitions ─────────────────────────────────────────────────────────
-
-const TOOLS = [
-  {
-    name: "generate_image",
-    description:
-      "Generate a 4K identity-locked image using the user's reference photo on Klamdo. " +
-      "Returns a job ID — use check_job to poll for the result. Costs 3 credits.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        prompt: {
-          type: "string",
-          description:
-            "Describe the content you want to generate. Be specific about setting, mood, style, and purpose. " +
-            "Example: 'A confident coach standing in a modern co-working space, window light, suited, holding a coffee, editorial style'"
-        },
-        aspectRatio: {
-          type: "string",
-          enum: ["1:1", "16:9", "9:16"],
-          description: "Output aspect ratio. Default: 1:1 (square, social-optimized).",
-          default: "1:1"
-        }
-      },
-      required: ["prompt"]
-    }
-  },
-  {
-    name: "generate_video",
-    description:
-      "Generate a 5-second vertical identity-locked video from the user's reference photo on Klamdo. " +
-      "Returns a job ID — use check_job to poll for the result. Aspect ratio is locked to 9:16. Costs 6 credits.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        prompt: {
-          type: "string",
-          description:
-            "Describe the video content. Include motion cues for best results. " +
-            "Example: 'A confident entrepreneur walking through a city street, slow zoom, cinematic lighting'"
-        }
-      },
-      required: ["prompt"]
-    }
-  },
-  {
-    name: "check_job",
-    description:
-      "Check the status of a Klamdo generation job. Returns status and download URLs when complete.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        jobId: {
-          type: "string",
-          description: "The job ID returned from generate_image or generate_video"
-        }
-      },
-      required: ["jobId"]
-    }
-  },
-  {
-    name: "get_account",
-    description: "Get current Klamdo account status: credit balance, plan, and recent jobs.",
-    inputSchema: {
-      type: "object",
-      properties: {}
-    }
-  },
-  {
-    name: "list_jobs",
-    description: "List recent Klamdo generation jobs for this account.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        limit: {
-          type: "number",
-          description: "Maximum jobs to return (default: 10, max: 50)",
-          default: 10
-        }
-      }
-    }
-  }
-];
-
-// ── MCP Server ───────────────────────────────────────────────────────────────
-
-const server = new Server(
-  { name: "klamdo", version: "1.0.0" },
-  { capabilities: { tools: {}, resources: {} } }
-);
-
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-  const input = (args ?? {}) as Record<string, unknown>;
-
-  try {
-    switch (name) {
-      case "generate_image": {
-        const result = await klamdo<{ jobId: string; status: string; creditsReserved: number }>("/jobs", {
-          prompt: input.prompt,
-          mode: "image",
-          aspectRatio: input.aspectRatio ?? "4:5"
-        });
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Image generation started.\n\nJob ID: ${result.jobId}\nStatus: ${result.status}\nCredits reserved: ${result.creditsReserved}\n\nUse check_job("${result.jobId}") to get the result. Images typically complete in 30–90 seconds.`
-            }
-          ]
-        };
-      }
-
-      case "generate_video": {
-        const result = await klamdo<{ jobId: string; status: string; creditsReserved: number }>("/jobs", {
-          prompt: input.prompt,
-          mode: "video",
-          aspectRatio: "9:16"
-        });
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Video generation started.\n\nJob ID: ${result.jobId}\nStatus: ${result.status}\nCredits reserved: ${result.creditsReserved}\n\nUse check_job("${result.jobId}") to get the result. Videos typically complete in 2–5 minutes.`
-            }
-          ]
-        };
-      }
-
-      case "check_job": {
-        const jobId = String(input.jobId ?? "");
-        if (!jobId) throw new McpError(ErrorCode.InvalidParams, "jobId is required");
-
-        const result = await klamdo<{
-          status: string;
-          assets: Array<{ kind: string; url: string }>;
-          errorMessage?: string;
-          caption?: string;
-        }>(`/jobs/${jobId}`);
-
-        if (result.status === "completed") {
-          const imageAsset = result.assets.find((a) => a.kind === "image");
-          const videoAsset = result.assets.find((a) => a.kind === "video");
-          const lines = [
-            `Job ${jobId} — Completed ✓`,
-            "",
-            imageAsset ? `Image URL: ${imageAsset.url}` : null,
-            videoAsset ? `Video URL: ${videoAsset.url}` : null,
-            result.caption ? `\nSuggested caption:\n${result.caption}` : null,
-            "",
-            `Share page: ${BASE_URL}/share/${jobId}`
-          ].filter(Boolean);
-          return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-
-        if (result.status === "failed") {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Job ${jobId} failed: ${result.errorMessage ?? "Unknown error"}. Credits have been refunded.`
-              }
-            ]
-          };
-        }
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Job ${jobId} is still running (status: ${result.status}). Check again in 15–30 seconds.`
-            }
-          ]
-        };
-      }
-
-      case "get_account": {
-        const result = await klamdo<{
-          name: string;
-          email: string;
-          availableCredits: number;
-          planTier: string;
-          freeSampleEligible: boolean;
-        }>("/account");
-        return {
-          content: [
-            {
-              type: "text",
-              text: [
-                `Klamdo Account: ${result.name} (${result.email})`,
-                `Plan: ${result.planTier}`,
-                `Credits: ${result.availableCredits}`,
-                result.freeSampleEligible ? "Free sample: available" : ""
-              ].filter(Boolean).join("\n")
-            }
-          ]
-        };
-      }
-
-      case "list_jobs": {
-        const limit = Math.min(Number(input.limit ?? 10), 50);
-        const result = await klamdo<{ jobs: Array<{ id: string; status: string; mode: string; prompt: string; createdAt: string }> }>(`/jobs?limit=${limit}`);
-        const lines = result.jobs.map(
-          (j) => `[${j.status}] ${j.id} — ${j.mode} — "${j.prompt.slice(0, 60)}" (${j.createdAt.slice(0, 10)})`
-        );
-        return {
-          content: [
-            {
-              type: "text",
-              text: lines.length ? lines.join("\n") : "No jobs found."
-            }
-          ]
-        };
-      }
-
-      default:
-        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
-    }
-  } catch (err) {
-    if (err instanceof McpError) throw err;
-    throw new McpError(
-      ErrorCode.InternalError,
-      err instanceof Error ? err.message : String(err)
-    );
-  }
-});
-
-// Resources: expose the API docs as a readable resource
-server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-  resources: [
-    {
-      uri: "klamdo://docs",
-      name: "Klamdo API Documentation",
-      description: "How to use Klamdo's MCP tools and what each parameter does",
-      mimeType: "text/plain"
-    }
-  ]
-}));
-
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  if (request.params.uri === "klamdo://docs") {
-    return {
-      contents: [
-        {
-          uri: "klamdo://docs",
-          mimeType: "text/plain",
-          text: `# Klamdo MCP Server
-
-Klamdo generates identity-locked 4K images and 5-second vertical videos for coaches and creator-founders.
-
-## Tools
-
-### generate_image
-Generate a 4K image from the user's reference photo. Costs 3 credits.
-- prompt (required): Describe the content, setting, mood, and style
-- aspectRatio (optional): "1:1" | "16:9" | "9:16" — default "1:1"
-
-### generate_video
-Generate a 5-second 9:16 vertical video. Costs 6 credits.
-- prompt (required): Describe the video content with motion cues
-
-### check_job
-Poll a generation job for results.
-- jobId (required): Job ID from generate_image or generate_video
-
-### get_account
-Get account status: credits, plan tier, free sample eligibility.
-
-### list_jobs
-List recent jobs.
-- limit (optional): Number of jobs to return (default 10, max 50)
-
-## Pricing
-- $19.99/month for 120 credits
-- 3 credits per 4K image (~40/mo)
-- 6 credits per 5-sec video (~20/mo)
-- Free sample on first sign-up
-
-## Links
-- Sign up: https://klamdo.app/sign-up
-- Pricing: https://klamdo.app/pricing
-`
-        }
-      ]
-    };
-  }
-  throw new McpError(ErrorCode.InvalidRequest, `Resource not found: ${request.params.uri}`);
-});
+async function main() {
+  const server = new Server(
+    { name: "klamdo", version: "1.1.0" },
+    { capabilities: { tools: {}, resources: {} } }
+  );
 
-// ── Start ────────────────────────────────────────────────────────────────────
+  registerHandlers(server, () => API_KEY);
 
-async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  process.stderr.write("[klamdo-mcp] Klamdo MCP server running on stdio\n");
+  process.stderr.write("[klamdo-mcp] Running via stdio\n");
 }
 
 main().catch((err) => {
-  process.stderr.write(`[klamdo-mcp] Fatal error: ${err}\n`);
+  process.stderr.write(`[klamdo-mcp] Fatal: ${err}\n`);
   process.exit(1);
 });

package/src/tools.ts

@@ -0,0 +1,283 @@
+/**
+ * Shared tool definitions and implementations for both stdio and HTTP transports.
+ * The apiKey is per-request in HTTP mode, per-process in stdio mode.
+ */
+
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+
+export const BASE_URL = process.env.KLAMDO_BASE_URL ?? "https://klamdo.app";
+
+export async function klamdo<T>(
+  path: string,
+  apiKey: string,
+  body?: Record<string, unknown>
+): Promise<T> {
+  const res = await fetch(`${BASE_URL}/api/mcp${path}`, {
+    method: body ? "POST" : "GET",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: body ? JSON.stringify(body) : undefined
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    if (res.status === 401) {
+      throw new McpError(
+        ErrorCode.InvalidRequest,
+        "Invalid API key. Get your key at https://klamdo.app/profile"
+      );
+    }
+    throw new McpError(
+      ErrorCode.InternalError,
+      `Klamdo API error ${res.status}: ${text.slice(0, 200)}`
+    );
+  }
+
+  return res.json() as Promise<T>;
+}
+
+export const TOOLS = [
+  {
+    name: "generate_image",
+    description:
+      "Generate a 4K identity-locked image using the user's reference photo on Klamdo. " +
+      "Returns a job ID — use check_job to poll for the result. Costs 3 credits.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: {
+          type: "string",
+          description:
+            "Describe the content you want to generate. Be specific about setting, mood, style, and purpose."
+        },
+        aspectRatio: {
+          type: "string",
+          enum: ["1:1", "16:9", "9:16"],
+          description: "Output aspect ratio. Default: 1:1 (square).",
+          default: "1:1"
+        }
+      },
+      required: ["prompt"]
+    }
+  },
+  {
+    name: "generate_video",
+    description:
+      "Generate a 5-second vertical identity-locked video from the user's reference photo on Klamdo. " +
+      "Returns a job ID — use check_job to poll. Aspect ratio locked to 9:16. Costs 6 credits.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: {
+          type: "string",
+          description: "Describe the video content with motion cues for best results."
+        }
+      },
+      required: ["prompt"]
+    }
+  },
+  {
+    name: "check_job",
+    description: "Check the status of a Klamdo generation job. Returns status and download URLs when complete.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        jobId: { type: "string", description: "The job ID returned from generate_image or generate_video" }
+      },
+      required: ["jobId"]
+    }
+  },
+  {
+    name: "get_account",
+    description: "Get current Klamdo account status: credit balance, plan, and free sample eligibility.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "list_jobs",
+    description: "List recent Klamdo generation jobs for this account.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Maximum jobs to return (default: 10, max: 50)", default: 10 }
+      }
+    }
+  }
+];
+
+export function registerHandlers(server: Server, getApiKey: () => string) {
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const input = (args ?? {}) as Record<string, unknown>;
+    const apiKey = getApiKey();
+
+    if (!apiKey) {
+      throw new McpError(
+        ErrorCode.InvalidRequest,
+        "No API key provided. Set KLAMDO_API_KEY or pass it via Authorization header."
+      );
+    }
+
+    try {
+      switch (name) {
+        case "generate_image": {
+          const result = await klamdo<{ jobId: string; status: string; creditsReserved: number }>(
+            "/jobs",
+            apiKey,
+            { prompt: input.prompt, mode: "image", aspectRatio: input.aspectRatio ?? "1:1" }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Image generation started.\n\nJob ID: ${result.jobId}\nStatus: ${result.status}\nCredits reserved: ${result.creditsReserved}\n\nUse check_job("${result.jobId}") to get the result. Images typically complete in 30–90 seconds.`
+              }
+            ]
+          };
+        }
+
+        case "generate_video": {
+          const result = await klamdo<{ jobId: string; status: string; creditsReserved: number }>(
+            "/jobs",
+            apiKey,
+            { prompt: input.prompt, mode: "video", aspectRatio: "9:16" }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Video generation started.\n\nJob ID: ${result.jobId}\nStatus: ${result.status}\nCredits reserved: ${result.creditsReserved}\n\nUse check_job("${result.jobId}") to get the result. Videos typically complete in 2–5 minutes.`
+              }
+            ]
+          };
+        }
+
+        case "check_job": {
+          const jobId = String(input.jobId ?? "");
+          if (!jobId) throw new McpError(ErrorCode.InvalidParams, "jobId is required");
+
+          const result = await klamdo<{
+            status: string;
+            assets: Array<{ kind: string; url: string }>;
+            errorMessage?: string;
+            caption?: string;
+          }>(`/jobs/${jobId}`, apiKey);
+
+          if (result.status === "completed") {
+            const imageAsset = result.assets.find((a) => a.kind === "image");
+            const videoAsset = result.assets.find((a) => a.kind === "video");
+            const lines = [
+              `Job ${jobId} — Completed ✓`,
+              "",
+              imageAsset ? `Image URL: ${imageAsset.url}` : null,
+              videoAsset ? `Video URL: ${videoAsset.url}` : null,
+              result.caption ? `\nSuggested caption:\n${result.caption}` : null,
+              "",
+              `Share page: ${BASE_URL}/share/${jobId}`
+            ].filter(Boolean);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+          }
+
+          if (result.status === "failed") {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Job ${jobId} failed: ${result.errorMessage ?? "Unknown error"}. Credits have been refunded.`
+                }
+              ]
+            };
+          }
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Job ${jobId} is still running (status: ${result.status}). Check again in 15–30 seconds.`
+              }
+            ]
+          };
+        }
+
+        case "get_account": {
+          const result = await klamdo<{
+            name: string;
+            email: string;
+            availableCredits: number;
+            planTier: string;
+            freeSampleEligible: boolean;
+          }>("/account", apiKey);
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `Klamdo Account: ${result.name} (${result.email})`,
+                  `Plan: ${result.planTier}`,
+                  `Credits: ${result.availableCredits}`,
+                  result.freeSampleEligible ? "Free sample: available" : ""
+                ].filter(Boolean).join("\n")
+              }
+            ]
+          };
+        }
+
+        case "list_jobs": {
+          const limit = Math.min(Number(input.limit ?? 10), 50);
+          const result = await klamdo<{
+            jobs: Array<{ id: string; status: string; mode: string; prompt: string; createdAt: string }>;
+          }>(`/jobs?limit=${limit}`, apiKey);
+          const lines = result.jobs.map(
+            (j) => `[${j.status}] ${j.id} — ${j.mode} — "${j.prompt.slice(0, 60)}" (${j.createdAt.slice(0, 10)})`
+          );
+          return {
+            content: [{ type: "text", text: lines.length ? lines.join("\n") : "No jobs found." }]
+          };
+        }
+
+        default:
+          throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+      }
+    } catch (err) {
+      if (err instanceof McpError) throw err;
+      throw new McpError(ErrorCode.InternalError, err instanceof Error ? err.message : String(err));
+    }
+  });
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+      {
+        uri: "klamdo://docs",
+        name: "Klamdo API Documentation",
+        description: "How to use Klamdo's MCP tools",
+        mimeType: "text/plain"
+      }
+    ]
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri === "klamdo://docs") {
+      return {
+        contents: [
+          {
+            uri: "klamdo://docs",
+            mimeType: "text/plain",
+            text: `# Klamdo MCP Server\n\nTools: generate_image, generate_video, check_job, get_account, list_jobs\n\nGet your API key at https://klamdo.app/profile\nPricing: $19.99/mo for 120 credits (3/image, 6/video)\n`
+          }
+        ]
+      };
+    }
+    throw new McpError(ErrorCode.InvalidRequest, `Resource not found: ${request.params.uri}`);
+  });
+}