@kadoa/mcp 0.2.3 → 0.2.5-rc.1

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
 
@@ -105,6 +144,8 @@ Get your API key from [kadoa.com/settings](https://kadoa.com/settings).
 | `delete_workflow` | Delete a workflow |
 | `approve_workflow` | Approve and activate a workflow |
 | `update_workflow` | Update workflow configuration and schema |
+| `team_list` | List all teams you belong to and see which is active |
+| `team_switch` | Switch the active team by name or ID |
 
 ## Usage Examples
 
@@ -175,6 +216,26 @@ delete_workflow for each, confirming before proceeding.
 - Verify the MCP server is configured correctly
 - Restart your MCP client
 
+## Deploying the Remote Server
+
+The remote MCP server at `mcp.kadoa.com` runs as a Docker container on GKE, deployed from the `kadoa-backend` monorepo.
+
+**To deploy a new version:**
+
+1. Publish a new `@kadoa/mcp` version to npm (`npm publish`)
+2. In `kadoa-backend`, update `infra/docker/mcp/package.json` to the new version and run `bun install` to regenerate the lockfile
+3. Merge to `main` — the CI pipeline (`main-build-deploy.yml`) builds and pushes the Docker image automatically
+4. Trigger the **Deploy to Production** workflow (`deploy-prod.yml`) with:
+   - **Target cluster:** `gcp`
+   - **Deployment scope:** `mcp`
+   - **Image tag:** the tag from step 3 (shown in the build summary)
+   - **Method:** `kubectl`
+
+Infrastructure files in `kadoa-backend`:
+- `infra/docker/mcp/Dockerfile.mcp-server` — Docker image definition
+- `infra/docker/mcp/package.json` — pinned `@kadoa/mcp` version
+- `infra/cdk8s/mcp/` — Kubernetes manifests (cdk8s)
+
 ## Development
 
 ```bash

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"),
@@ -53172,7 +53301,7 @@ async function exchangeSupabaseCode(code, codeVerifier) {
   const data = await res.json();
   return data.access_token;
 }
-async function resolveApiKey2(supabaseJwt) {
+async function fetchUserTeams(supabaseJwt) {
   const kadoaApiUrl = process.env.KADOA_PUBLIC_API_URI || "https://api.kadoa.com";
   const userRes = await fetch(`${kadoaApiUrl}/v4/user`, {
     headers: { Authorization: `Bearer ${supabaseJwt}` }
@@ -53185,7 +53314,14 @@ async function resolveApiKey2(supabaseJwt) {
   if (!userData.teams?.length) {
     throw new Error("User has no teams");
   }
-  const teamId = userData.teams[0].id;
+  return userData.teams.map((t) => ({
+    id: t.id,
+    name: t.name,
+    memberRole: t.memberRole
+  }));
+}
+async function resolveTeamApiKey(supabaseJwt, teamId) {
+  const kadoaApiUrl = process.env.KADOA_PUBLIC_API_URI || "https://api.kadoa.com";
   const keyRes = await fetch(`${kadoaApiUrl}/v4/team/${teamId}/api-key`, {
     headers: { Authorization: `Bearer ${supabaseJwt}` }
   });
@@ -53325,21 +53461,20 @@ class KadoaOAuthProvider {
     pendingAuths.delete(state);
     try {
       const supabaseJwt = await exchangeSupabaseCode(code, pending.supabaseCodeVerifier);
-      const apiKey = await resolveApiKey2(supabaseJwt);
-      const mcpCode = randomToken();
-      authCodes.set(mcpCode, {
-        apiKey,
-        codeChallenge: pending.params.codeChallenge,
-        clientId: pending.client.client_id,
-        redirectUri: pending.params.redirectUri,
-        expiresAt: Date.now() + 10 * 60 * 1000
-      });
-      const redirectUrl = new URL(pending.params.redirectUri);
-      redirectUrl.searchParams.set("code", mcpCode);
-      if (pending.params.state) {
-        redirectUrl.searchParams.set("state", pending.params.state);
+      const teams = await fetchUserTeams(supabaseJwt);
+      if (teams.length === 1) {
+        const apiKey = await resolveTeamApiKey(supabaseJwt, teams[0].id);
+        this.completeAuthFlow(pending, apiKey, res);
+        return;
       }
-      res.redirect(redirectUrl.toString());
+      const selectionToken = randomToken();
+      pendingTeamSelections.set(selectionToken, {
+        supabaseJwt,
+        teams,
+        pending,
+        expiresAt: Date.now() + TEAM_SELECTION_TTL
+      });
+      res.type("html").send(renderTeamSelectionPage(teams, selectionToken));
     } catch (error48) {
       console.error("Auth callback error:", error48);
       const redirectUrl = new URL(pending.params.redirectUri);
@@ -53351,14 +53486,180 @@ class KadoaOAuthProvider {
       res.redirect(redirectUrl.toString());
     }
   }
+  async handleTeamSelection(req, res) {
+    const { token, teamId } = req.body;
+    if (!token || !teamId) {
+      res.status(400).send("Missing token or teamId");
+      return;
+    }
+    const entry = pendingTeamSelections.get(token);
+    if (!entry) {
+      res.status(400).send("Unknown or expired team selection token");
+      return;
+    }
+    if (entry.expiresAt < Date.now()) {
+      pendingTeamSelections.delete(token);
+      res.status(400).send("Team selection expired — please log in again");
+      return;
+    }
+    if (!entry.teams.some((t) => t.id === teamId)) {
+      res.status(403).send("Invalid team selection");
+      return;
+    }
+    pendingTeamSelections.delete(token);
+    try {
+      const apiKey = await resolveTeamApiKey(entry.supabaseJwt, teamId);
+      this.completeAuthFlow(entry.pending, apiKey, res);
+    } catch (error48) {
+      console.error("Team selection error:", error48);
+      const redirectUrl = new URL(entry.pending.params.redirectUri);
+      redirectUrl.searchParams.set("error", "server_error");
+      redirectUrl.searchParams.set("error_description", error48 instanceof Error ? error48.message : "Failed to resolve team API key");
+      if (entry.pending.params.state) {
+        redirectUrl.searchParams.set("state", entry.pending.params.state);
+      }
+      res.redirect(redirectUrl.toString());
+    }
+  }
+  completeAuthFlow(pending, apiKey, res) {
+    const mcpCode = randomToken();
+    authCodes.set(mcpCode, {
+      apiKey,
+      codeChallenge: pending.params.codeChallenge,
+      clientId: pending.client.client_id,
+      redirectUri: pending.params.redirectUri,
+      expiresAt: Date.now() + 10 * 60 * 1000
+    });
+    const redirectUrl = new URL(pending.params.redirectUri);
+    redirectUrl.searchParams.set("code", mcpCode);
+    if (pending.params.state) {
+      redirectUrl.searchParams.set("state", pending.params.state);
+    }
+    res.redirect(redirectUrl.toString());
+  }
 }
-var clients, pendingAuths, authCodes, accessTokens, refreshTokens, ACCESS_TOKEN_TTL = 3600, kadoaClientsStore;
+function renderTeamSelectionPage(teams, selectionToken) {
+  const teamButtons = teams.map((t) => `
+      <button type="submit" name="teamId" value="${t.id}" class="team-btn">
+        <span class="team-name">${escapeHtml(t.name)}</span>
+        ${t.memberRole ? `<span class="team-role">${escapeHtml(t.memberRole.toLowerCase())}</span>` : ""}
+      </button>`).join(`
+`);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Select Team - Kadoa</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      background: #0a0a0f;
+      color: #e4e4e7;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+
+    .container {
+      width: 100%;
+      max-width: 420px;
+      padding: 2rem;
+    }
+
+    .logo {
+      text-align: center;
+      margin-bottom: 2rem;
+    }
+
+    .logo svg {
+      width: 40px;
+      height: 40px;
+    }
+
+    h1 {
+      font-size: 1.25rem;
+      font-weight: 600;
+      text-align: center;
+      margin-bottom: 0.5rem;
+      color: #fafafa;
+    }
+
+    .subtitle {
+      text-align: center;
+      color: #71717a;
+      font-size: 0.875rem;
+      margin-bottom: 1.5rem;
+    }
+
+    .team-btn {
+      width: 100%;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0.875rem 1rem;
+      margin-bottom: 0.5rem;
+      background: #18181b;
+      border: 1px solid #27272a;
+      border-radius: 8px;
+      color: #fafafa;
+      font-size: 0.9375rem;
+      cursor: pointer;
+      transition: background 0.15s, border-color 0.15s;
+    }
+
+    .team-btn:hover {
+      background: #1f1f23;
+      border-color: #3f3f46;
+    }
+
+    .team-btn:active {
+      background: #27272a;
+    }
+
+    .team-name { font-weight: 500; }
+
+    .team-role {
+      font-size: 0.75rem;
+      color: #71717a;
+      text-transform: capitalize;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="logo">
+      <svg viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <rect width="40" height="40" rx="8" fill="#6d28d9"/>
+        <text x="50%" y="54%" dominant-baseline="middle" text-anchor="middle"
+              fill="white" font-family="sans-serif" font-size="20" font-weight="700">K</text>
+      </svg>
+    </div>
+    <h1>Select a team</h1>
+    <p class="subtitle">Choose which team to connect with this MCP session</p>
+    <form method="POST" action="/team-select">
+      <input type="hidden" name="token" value="${selectionToken}" />
+      ${teamButtons}
+    </form>
+  </div>
+</body>
+</html>`;
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+var clients, pendingAuths, pendingTeamSelections, authCodes, accessTokens, refreshTokens, TEAM_SELECTION_TTL, ACCESS_TOKEN_TTL = 3600, kadoaClientsStore;
 var init_auth2 = __esm(() => {
   clients = new Map;
   pendingAuths = new Map;
+  pendingTeamSelections = new Map;
   authCodes = new Map;
   accessTokens = new Map;
   refreshTokens = new Map;
+  TEAM_SELECTION_TTL = 10 * 60 * 1000;
   kadoaClientsStore = {
     getClient(clientId) {
       return clients.get(clientId);
@@ -53382,7 +53683,8 @@ __export(exports_http, {
   startHttpServer: () => startHttpServer
 });
 import { randomUUID as randomUUID2 } from "node:crypto";
-function resolveApiKey3(req) {
+import express8 from "express";
+function resolveApiKey2(req) {
   return req.auth?.extra?.apiKey;
 }
 async function startHttpServer() {
@@ -53401,13 +53703,16 @@ async function startHttpServer() {
   app.get("/auth/callback", (req, res) => {
     provider.handleAuthCallback(req, res);
   });
+  app.post("/team-select", express8.urlencoded({ extended: false }), (req, res) => {
+    provider.handleTeamSelection(req, res);
+  });
   app.get("/health", (_req, res) => {
     res.json({ status: "ok", sessions: Object.keys(sessions).length });
   });
   const bearerAuth = requireBearerAuth({ verifier: provider });
   app.post("/mcp", bearerAuth, async (req, res) => {
     const sessionId = req.headers["mcp-session-id"];
-    const apiKey = resolveApiKey3(req);
+    const apiKey = resolveApiKey2(req);
     if (!apiKey) {
       res.status(401).json({
         jsonrpc: "2.0",
@@ -53464,7 +53769,7 @@ async function startHttpServer() {
   });
   app.get("/mcp", bearerAuth, async (req, res) => {
     const sessionId = req.headers["mcp-session-id"];
-    const apiKey = resolveApiKey3(req);
+    const apiKey = resolveApiKey2(req);
     if (!apiKey) {
       res.status(401).send("Unauthorized: Bearer token required");
       return;
@@ -53481,7 +53786,7 @@ async function startHttpServer() {
   });
   app.delete("/mcp", bearerAuth, async (req, res) => {
     const sessionId = req.headers["mcp-session-id"];
-    const apiKey = resolveApiKey3(req);
+    const apiKey = resolveApiKey2(req);
     if (!apiKey) {
       res.status(401).send("Unauthorized: Bearer token required");
       return;
@@ -53530,6 +53835,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 +53857,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.5-rc.1",
   "description": "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
   "type": "module",
   "main": "dist/index.js",
@@ -39,6 +39,12 @@
     "bun-types": "^1.3.3",
     "typescript": "^5.9.3"
   },
-  "keywords": ["kadoa", "mcp", "model-context-protocol", "web-scraping", "data-extraction"],
+  "keywords": [
+    "kadoa",
+    "mcp",
+    "model-context-protocol",
+    "web-scraping",
+    "data-extraction"
+  ],
   "license": "MIT"
 }