@kadoa/mcp 0.2.3 → 0.2.4

package/README.md

@@ -1,8 +1,47 @@
 # Kadoa MCP Server
 
-Use [Kadoa](https://kadoa.com) from Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, and other MCP clients.
+Use [Kadoa](https://kadoa.com) from ChatGPT, Claude.ai, Claude Code, Cursor, and other MCP clients.
 
-## Quick Start
+## Remote Server (no install needed)
+
+A hosted MCP server is available at `https://mcp.kadoa.com/mcp`. Connect from any MCP client — no local install, no API key config. You sign in with your Kadoa account via OAuth.
+
+### ChatGPT
+
+1. Go to **Settings → Connectors → Add MCP server**
+2. Enter the URL: `https://mcp.kadoa.com/mcp`
+3. Choose OAuth authentication and sign in with your Kadoa account (Google)
+
+### Claude.ai
+
+1. Go to **Settings → Connectors → Add custom MCP**
+2. Enter the URL: `https://mcp.kadoa.com/mcp`
+3. Sign in with your Kadoa account via OAuth
+
+### Cursor (Remote)
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "kadoa": {
+      "type": "http",
+      "url": "https://mcp.kadoa.com/mcp"
+    }
+  }
+}
+```
+
+### Any MCP Client
+
+Point your client to `https://mcp.kadoa.com/mcp` with OAuth authentication.
+
+---
+
+## Local Setup (stdio)
+
+If you prefer to run the MCP server locally (e.g., for development or to use your own API key), install via npx:
 
 ### Claude Code
 

package/dist/index.js

@@ -48922,21 +48922,26 @@ var init_dist2 = __esm(() => {
 });
 
 // src/client.ts
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
-function loadApiKeyFromConfig() {
+function getConfigPath() {
   const home = process.env.HOME || homedir();
-  const configFile = join(home, ".kadoa", "config.json");
+  return join(home, ".kadoa", "config.json");
+}
+function loadConfig() {
+  const configFile = getConfigPath();
   if (!existsSync(configFile))
-    return;
+    return {};
   try {
-    const config2 = JSON.parse(readFileSync(configFile, "utf-8"));
-    return config2.apiKey;
+    return JSON.parse(readFileSync(configFile, "utf-8"));
   } catch {
-    return;
+    return {};
   }
 }
+function loadApiKeyFromConfig() {
+  return loadConfig().apiKey;
+}
 function resolveApiKey(apiKey) {
   const key = apiKey || process.env.KADOA_API_KEY || loadApiKeyFromConfig();
   if (!key) {
@@ -48951,6 +48956,33 @@ var init_client = __esm(() => {
   init_dist2();
 });
 
+// src/client.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+function getConfigPath2() {
+  const home = process.env.HOME || homedir2();
+  return join2(home, ".kadoa", "config.json");
+}
+function loadConfig2() {
+  const configFile = getConfigPath2();
+  if (!existsSync2(configFile))
+    return {};
+  try {
+    return JSON.parse(readFileSync2(configFile, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function saveConfig(config2) {
+  const configFile = getConfigPath2();
+  mkdirSync2(dirname2(configFile), { recursive: true });
+  writeFileSync2(configFile, JSON.stringify(config2, null, 2), "utf-8");
+}
+var init_client2 = __esm(() => {
+  init_dist2();
+});
+
 // src/tools.ts
 function jsonResult(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
@@ -48961,13 +48993,59 @@ function errorResult(message) {
     isError: true
   };
 }
+function classifyError(error48) {
+  if (KadoaSdkException.isInstance(error48)) {
+    const code = error48.code;
+    if (KadoaHttpException.isInstance(error48)) {
+      const status = error48.httpStatus ? ` (HTTP ${error48.httpStatus})` : "";
+      switch (code) {
+        case "AUTH_ERROR":
+          return `Authentication failed${status}. Your Kadoa API key may be invalid or expired. Please check your KADOA_API_KEY or re-authenticate.`;
+        case "NOT_FOUND":
+          return `Not found${status}. The workflow may have been deleted or the ID is incorrect.`;
+        case "RATE_LIMITED":
+          return `Rate limit exceeded${status}. Please wait a moment and try again.`;
+        case "NETWORK_ERROR":
+          return `Unable to reach the Kadoa API${status}. Check your network connection.`;
+        case "TIMEOUT":
+          return `Request timed out${status}. Please try again.`;
+        case "VALIDATION_ERROR":
+        case "BAD_REQUEST":
+          return error48.message;
+        default:
+          return `Kadoa API error${status}. Please try again later.`;
+      }
+    }
+    switch (code) {
+      case "AUTH_ERROR":
+        return "Authentication failed. Your Kadoa API key may be invalid or expired. Please check your KADOA_API_KEY or re-authenticate.";
+      case "NOT_FOUND":
+        return "Not found. The workflow may have been deleted or the ID is incorrect.";
+      case "RATE_LIMITED":
+        return "Rate limit exceeded. Please wait a moment and try again.";
+      case "NETWORK_ERROR":
+        return "Unable to reach the Kadoa API. Check your network connection.";
+      case "TIMEOUT":
+        return "Request timed out. Please try again.";
+      case "VALIDATION_ERROR":
+      case "BAD_REQUEST":
+        return error48.message;
+      default:
+        return error48.message;
+    }
+  }
+  if (error48 instanceof Error) {
+    return error48.message;
+  }
+  return "Unknown error";
+}
 function withErrorHandling(name, handler) {
   return async (...args) => {
     try {
       return await handler(...args);
     } catch (error48) {
-      const message = error48 instanceof Error ? error48.message : "Unknown error";
-      console.error(`[Tool Error] ${name}:`, message);
+      const message = classifyError(error48);
+      console.error(`[Tool Error] ${name}:`, error48);
       return errorResult(message);
     }
   };
@@ -49143,10 +49221,61 @@ function registerTools(server, client) {
       workflow: result
     });
   }));
+  server.registerTool("team_list", {
+    description: "List all teams the current user belongs to, showing which team is currently active",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  }, withErrorHandling("team_list", async () => {
+    const response = await client.axiosInstance.get("/v5/user", {
+      baseURL: client.baseUrl,
+      headers: { "x-api-key": client.apiKey }
+    });
+    const teams = response.data?.teams ?? [];
+    const config2 = loadConfig2();
+    const activeTeamId = config2.teamId ?? teams[0]?.id;
+    return jsonResult({
+      teams: teams.map((t) => ({
+        id: t.id,
+        name: t.name,
+        role: t.role,
+        active: t.id === activeTeamId
+      })),
+      activeTeamId
+    });
+  }));
+  server.registerTool("team_switch", {
+    description: "Switch the active team by name or ID. After switching, all subsequent API calls will use the new team context.",
+    inputSchema: {
+      teamIdentifier: exports_external.string().describe("Team name or team ID to switch to")
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
+  }, withErrorHandling("team_switch", async (args) => {
+    const response = await client.axiosInstance.get("/v5/user", {
+      baseURL: client.baseUrl,
+      headers: { "x-api-key": client.apiKey }
+    });
+    const teams = response.data?.teams ?? [];
+    const identifier = args.teamIdentifier;
+    const match = teams.find((t) => t.id === identifier || t.name.toLowerCase() === identifier.toLowerCase());
+    if (!match) {
+      return errorResult(`Team not found: "${identifier}". Available teams: ${teams.map((t) => t.name).join(", ")}`);
+    }
+    const config2 = loadConfig2();
+    config2.teamId = match.id;
+    config2.teamName = match.name;
+    saveConfig(config2);
+    return jsonResult({
+      success: true,
+      teamId: match.id,
+      teamName: match.name
+    });
+  }));
 }
 var SchemaFieldShape;
 var init_tools = __esm(() => {
   init_zod();
+  init_dist2();
+  init_client2();
   SchemaFieldShape = {
     name: exports_external.string().describe("Field name"),
     description: exports_external.string().optional().describe("What this field contains"),
@@ -53530,6 +53659,17 @@ function createServer(apiKey) {
   server.server.onerror = (error48) => console.error("[MCP Error]", error48);
   return server;
 }
+async function validateApiKey() {
+  const client = createKadoaClient();
+  try {
+    await client.workflow.list({ limit: 1 });
+  } catch (error48) {
+    if (KadoaSdkException.isInstance(error48) && error48.code === "AUTH_ERROR") {
+      console.error("Kadoa MCP: Invalid API key. Check KADOA_API_KEY or run 'kadoa login'.");
+      process.exit(1);
+    }
+  }
+}
 var init_src = __esm(async () => {
   init_mcp();
   init_stdio2();
@@ -53541,6 +53681,7 @@ var init_src = __esm(async () => {
       const { startHttpServer: startHttpServer2 } = await init_http2().then(() => exports_http);
       await startHttpServer2();
     } else {
+      await validateApiKey();
       const server = createServer();
       const transport = new StdioServerTransport;
       await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadoa/mcp",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
   "type": "module",
   "main": "dist/index.js",