@kadoa/mcp 0.1.2 → 0.2.0

package/README.md

@@ -1,30 +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
 
-Add for the current project:
-
-```bash
-claude mcp add --transport stdio kadoa -- npx -y @kadoa/mcp
-```
-
-Or add for all projects:
-
-```bash
-claude mcp add --transport stdio -s user kadoa -- npx -y @kadoa/mcp
-```
-
-Set your API key:
-
 ```bash
-export KADOA_API_KEY=tk-your_api_key
+claude mcp add --transport stdio -e KADOA_API_KEY=tk-your_api_key kadoa -- npx -y @kadoa/mcp
 ```
 
-Or if you have the [Kadoa CLI](https://www.npmjs.com/package/@kadoa/cli) installed, just run `kadoa login` and the MCP will use your saved key automatically.
+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
 
@@ -64,6 +50,45 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
+### 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"
+      }
+    }
+  }
+}
+```
+
 ## Get Your API Key
 
 Get your API key from [kadoa.com/settings](https://kadoa.com/settings).
@@ -83,12 +108,61 @@ 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.
 
-- "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"
+### 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.
+
+> 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
 
@@ -110,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