@kadoa/mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,20 +1,16 @@
 # Kadoa MCP Server
 
-Use [Kadoa](https://kadoa.com) from Claude Desktop, Cursor, Claude Code, and other MCP clients.
+Use [Kadoa](https://kadoa.com) from Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, and other MCP clients.
 
 ## Quick Start
 
 ### Claude Code
 
 ```bash
-claude mcp add --transport stdio kadoa -- npx -y @kadoa/mcp
+claude mcp add --transport stdio -e KADOA_API_KEY=tk-your_api_key kadoa -- npx -y @kadoa/mcp
 ```
 
-Set your API key:
-
-```bash
-export KADOA_API_KEY=tk-your_api_key
-```
+Add `-s user` to enable for all projects. If you have the [Kadoa CLI](https://www.npmjs.com/package/@kadoa/cli) installed, you can skip the `-e` flag — just run `kadoa login` and the MCP will use your saved key automatically.
 
 ### Claude Desktop
 
@@ -25,7 +21,7 @@ Add to `~/.config/Claude/claude_desktop_config.json`:
   "mcpServers": {
     "kadoa": {
       "command": "npx",
-      "args": ["-y", "kadoa-mcp"],
+      "args": ["-y", "@kadoa/mcp"],
       "env": {
         "KADOA_API_KEY": "tk-your_api_key"
       }
@@ -45,7 +41,46 @@ Add to `.cursor/mcp.json`:
   "mcpServers": {
     "kadoa": {
       "command": "npx",
-      "args": ["-y", "kadoa-mcp"],
+      "args": ["-y", "@kadoa/mcp"],
+      "env": {
+        "KADOA_API_KEY": "tk-your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+```bash
+codex mcp add kadoa -- npx -y @kadoa/mcp
+```
+
+Or add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.kadoa]
+command = "npx"
+args = ["-y", "@kadoa/mcp"]
+
+[mcp_servers.kadoa.env]
+KADOA_API_KEY = "tk-your_api_key"
+```
+
+### Gemini CLI
+
+```bash
+gemini mcp add -t stdio kadoa npx -- -y @kadoa/mcp
+```
+
+Or add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "kadoa": {
+      "command": "npx",
+      "args": ["-y", "@kadoa/mcp"],
       "env": {
         "KADOA_API_KEY": "tk-your_api_key"
       }
@@ -73,17 +108,67 @@ Get your API key from [kadoa.com/settings](https://kadoa.com/settings).
 
 ## Usage Examples
 
-Ask your AI assistant:
+Once the MCP server is configured, you can manage the full workflow lifecycle through natural conversation. Here are a few common operations shown as Claude Code sessions.
+
+### Create and run a workflow
+
+```
+> You: Create a workflow to extract product names, prices, and ratings
+        from https://example-shop.com/products
+
+Claude calls create_workflow and returns the workflow ID, proposed
+navigation steps, and data schema for your review.
 
-- "List my Kadoa workflows"
-- "Create a workflow to extract product prices from example.com"
-- "Run workflow abc123 and show me the results"
-- "Update the schema for workflow abc123 to include a rating field"
+> You: The schema looks good. Approve it and kick off a run.
+
+Claude calls approve_workflow to activate the workflow, then
+run_workflow to start extraction.
+
+> You: Is the run done? Show me the results.
+
+Claude checks the run status with get_workflow, then calls fetch_data
+to retrieve the extracted records and display them as a table.
+```
+
+### Update a workflow and re-run
+
+```
+> You: List my workflows.
+
+Claude calls list_workflows and shows all workflows with their
+current status (active, paused, draft, etc.).
+
+> You: Update wf_abc123 — add an "availability" field to the schema
+        and rename "cost" to "price".
+
+Claude calls update_workflow with the new schema, confirms the
+changes, and shows the updated field list.
+
+> You: Run it again with the new schema.
+
+Claude calls run_workflow and waits for completion, then fetches
+the latest data with fetch_data so you can verify the changes.
+```
+
+### Monitor and clean up
+
+```
+> You: Show me all active workflows and their last run results.
+
+Claude calls list_workflows, filters to active ones, then calls
+fetch_data for each to summarize the latest extraction results.
+
+> You: Delete the ones that haven't produced data in the last week.
+
+Claude identifies stale workflows from the results and calls
+delete_workflow for each, confirming before proceeding.
+```
 
 ## Troubleshooting
 
-**"KADOA_API_KEY environment variable required"**
-- Make sure `KADOA_API_KEY` is set in your MCP config or environment
+**"No API key found"**
+- Run `kadoa login` (requires `npm i -g @kadoa/cli`), or
+- Set `KADOA_API_KEY` in your MCP config or environment
 - API keys start with `tk-`
 
 **Claude says "I don't have access to Kadoa"**
@@ -99,6 +184,29 @@ bun run test       # Run tests
 bun run build      # Build for distribution
 ```
 
+### Connecting to local services
+
+To develop and test against a local Kadoa backend (instead of the production API), point the MCP at your local `public-api` service using the `KADOA_PUBLIC_API_URI` environment variable.
+
+**Prerequisites:** the `public-api` service must be running locally (default port `12380`). You also need a local API key — check your backend seed data or API key table.
+
+**Run the MCP server locally:**
+
+```bash
+KADOA_PUBLIC_API_URI=http://localhost:12380 KADOA_API_KEY=tk-your_local_api_key bun src/index.ts
+```
+
+**Add as a local MCP in Claude Code** (alongside the remote one):
+
+```bash
+claude mcp add --transport stdio \
+  -e KADOA_PUBLIC_API_URI=http://localhost:12380 \
+  -e KADOA_API_KEY=tk-your_local_api_key \
+  kadoa-local -- bun /path/to/kadoa-mcp/src/index.ts
+```
+
+This registers a `kadoa-local` server that coexists with the production `kadoa` server, so you can use both without conflicts (`mcp__kadoa__*` for prod, `mcp__kadoa-local__*` for local).
+
 ## License
 
 MIT

package/dist/index.js

@@ -34250,7 +34250,7 @@ class KadoaMcpServer {
       tools: [
         {
           name: "create_workflow",
-          description: "Create a new agentic navigation workflow. If entity and schema are provided, they guide the extraction. Otherwise, the AI agent auto-detects the schema from the page based on the prompt.",
+          description: "Create a new agentic navigation workflow. If entity and schema are provided, they guide the extraction. Otherwise, the AI agent auto-detects the schema from the page based on the prompt. The workflow runs asynchronously and may take several minutes. Do NOT poll or sleep-wait for completion. Instead, return the workflow ID to the user and let them check back later with get_workflow or fetch_data.",
           inputSchema: {
             type: "object",
             properties: {
@@ -34297,7 +34297,7 @@ class KadoaMcpServer {
                       ]
                     }
                   },
-                  required: ["name"]
+                  required: ["name", "example"]
                 },
                 description: "Extraction schema fields. If omitted, the AI agent auto-detects the schema."
               }
@@ -34340,7 +34340,7 @@ class KadoaMcpServer {
         },
         {
           name: "run_workflow",
-          description: "Run a workflow to extract fresh data",
+          description: "Run a workflow to extract fresh data. The run is asynchronous and may take several minutes. Do NOT poll or sleep-wait for completion. Return the workflow ID to the user and let them check status with get_workflow or fetch results later with fetch_data.",
           inputSchema: {
             type: "object",
             properties: {
@@ -34359,7 +34359,7 @@ class KadoaMcpServer {
         },
         {
           name: "fetch_data",
-          description: "Get extracted data from a workflow",
+          description: "Get extracted data from a workflow. Data is only available after the workflow run has completed (displayState is no longer RUNNING). Do NOT poll or sleep-wait for completion.",
           inputSchema: {
             type: "object",
             properties: {
@@ -34460,7 +34460,7 @@ class KadoaMcpServer {
                     isRequired: { type: "boolean" },
                     isUnique: { type: "boolean" }
                   },
-                  required: ["name"]
+                  required: ["name", "example"]
                 },
                 description: "New extraction schema fields"
               },
@@ -34662,8 +34662,7 @@ class KadoaMcpServer {
     console.error("Connected to Kadoa API");
   }
 }
-var isMainModule = typeof Bun !== "undefined" && import.meta.url === Bun.main || import.meta.url === `file://${process.argv[1]}`;
-if (isMainModule) {
+if (!process.env.VITEST && !process.env.BUN_TEST) {
   new KadoaMcpServer().run().catch((error2) => {
     console.error("Fatal error:", error2);
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadoa/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
   "type": "module",
   "main": "dist/index.js",
@@ -18,8 +18,10 @@
     "dev": "bun src/index.ts",
     "build": "bun build src/index.ts --outdir=dist --target=node && node -e \"const f='dist/index.js';require('fs').writeFileSync(f,require('fs').readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\"",
     "check-types": "tsc --noEmit",
-    "test": "bun test",
-    "test:unit": "bun test tests/unit --timeout=120000",
+    "test": "BUN_TEST=1 bun test",
+    "test:unit": "BUN_TEST=1 bun test tests/unit --timeout=120000",
+    "test:e2e": "BUN_TEST=1 bun test tests/e2e --timeout=600000",
+    "test:eval": "BUN_TEST=1 bun test tests/evals --timeout=300000",
     "prepublishOnly": "bun run check-types && bun run test:unit && bun run build"
   },
   "dependencies": {
@@ -27,14 +29,11 @@
     "@modelcontextprotocol/sdk": "^1.26.0"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.78.0",
     "@types/node": "^25.0.3",
     "bun-types": "^1.3.3",
     "typescript": "^5.9.3"
   },
   "keywords": ["kadoa", "mcp", "model-context-protocol", "web-scraping", "data-extraction"],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kadoa-org/kadoa-mcp.git"
-  }
+  "license": "MIT"
 }