@kadoa/mcp 0.5.5 → 0.5.8-rc.1

package/README.md

@@ -85,6 +85,17 @@ Claude checks the run status with get_workflow, then calls fetch_data
 to retrieve the extracted records and display them as a table.
 ```
 
+### Create a workflow from a template
+
+```
+> You: Use my "Product Scraper" template to scrape https://example-shop.com.
+
+Claude calls list_templates to find the matching template, then
+create_workflow with `templateId` and `urls` only — the prompt and
+schema are inherited from the template version. Returns the workflow
+ID for follow-up with get_workflow or fetch_data.
+```
+
 ### Update a workflow and re-run
 
 ```
@@ -126,25 +137,90 @@ delete_workflow for each, confirming before proceeding.
 - Restart your MCP client
 - Re-authenticate via OAuth if prompted
 
-## Deploying the Remote Server
+## Releases
 
-The remote MCP server at `mcp.kadoa.com` runs as a Docker container on GKE, deployed from the `kadoa-backend` monorepo.
+This repo ships two surfaces, and a "release" usually touches both:
 
-**To deploy a new version:**
+- **npm package `@kadoa/mcp`** — stdio CLI users install locally (`npx @kadoa/mcp`). Cut by [Release Please](https://github.com/googleapis/release-please) from Conventional Commits on `main`.
+- **Hosted server at `mcp.kadoa.com`** — Docker container on GKE, built and deployed from the [`kadoa-backend`](https://github.com/kadoa-org/kadoa-backend) monorepo, which pins a specific `@kadoa/mcp` 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:
+Relevant files in `kadoa-backend`:
+- `infra/docker/mcp/Dockerfile.mcp-server` — image definition
+- `infra/docker/mcp/package.json` — pinned `@kadoa/mcp` version
+- `infra/cdk8s/mcp/charts/Server.ts` — k8s manifest source (prod chart only; the test deployment is provisioned ad hoc — see below)
+
+### Production release
+
+1. Merge PRs to `main` using Conventional Commits (`feat:`, `fix:`, etc.). Release Please opens/maintains a `chore(main): release mcp x.y.z` PR.
+2. Merge the release PR. The [`release-please.yml`](.github/workflows/release-please.yml) workflow tags, drafts a GitHub Release, and publishes to npm (`latest` dist-tag).
+3. In `kadoa-backend`, bump `infra/docker/mcp/package.json` `@kadoa/mcp` to the new version, run `bun install` to refresh `bun.lock`, open a PR.
+4. Merge to `main`. CI (`main-build-deploy.yml`) builds and pushes `europe-west3-docker.pkg.dev/oceanic-base-310208/kadoa-artifacts/mcp-server:<IMAGE_TAG>` (tag shown in the build summary).
+5. Trigger the **Deploy to Production** workflow ([`deploy-prod.yml`](https://github.com/kadoa-org/kadoa-backend/actions/workflows/deploy-prod.yml)) with:
    - **Target cluster:** `gcp`
    - **Deployment scope:** `mcp`
-   - **Image tag:** the tag from step 3 (shown in the build summary)
+   - **Image tag:** the tag from step 4
    - **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)
+### RC / test release
+
+Use this when you want to validate a change end-to-end against real clients (Claude Desktop, Cursor, ChatGPT) before promoting to `latest` / prod. The flow mirrors the prod one, but every step targets `rc` channels.
+
+There are two ways to consume an RC:
+
+- **Local stdio**: `npx @kadoa/mcp@rc` — installs from the `rc` dist-tag on npm. Good for quick sanity checks where the bug doesn't depend on the hosted OAuth flow.
+- **Hosted `mcp-server-test`**: a separate k8s deployment alongside prod in the same GKE cluster. Required when you need to validate the OAuth callback, Redis token store, multi-tenant session behavior, etc.
+
+#### Publish an RC to npm
+
+Manual — Release Please only cuts stable versions today.
+
+```bash
+# from a branch on kadoa-mcp
+bun install && bun run build
+# bump version to a prerelease, e.g. 0.5.7-rc.1
+npm version 0.5.7-rc.1 --no-git-tag-version
+npm publish --tag rc --access public
+```
+
+Verify: `npm view @kadoa/mcp dist-tags`. The `rc` tag should now point to your version. Existing tags today: `latest`, `rc`, `next`.
+
+Promote later with: `npm dist-tag add @kadoa/mcp@0.5.7 latest` (run **after** the matching stable version has been published the normal way).
+
+#### Deploy the RC to `mcp-server-test`
+
+1. In `kadoa-backend`, set `infra/docker/mcp/package.json` `@kadoa/mcp` to the RC version, `bun install`, push to a branch and merge to `main`. CI builds the `mcp-server:<IMAGE_TAG>` image as usual.
+2. Update the test deployment to the new image:
+
+   ```bash
+   gcloud container clusters get-credentials kadoa-prod \
+     --region=europe-west3 --project=oceanic-base-310208
+
+   kubectl set image deployment/mcp-server-test \
+     mcp-server=europe-west3-docker.pkg.dev/oceanic-base-310208/kadoa-artifacts/mcp-server:<IMAGE_TAG>
+   ```
+
+3. Port-forward to reach it (the test deployment has **no public ingress** by design):
+
+   ```bash
+   kubectl port-forward svc/mcp-server-test 3000:3000
+   ```
+
+4. Point your MCP client at `http://localhost:3000/mcp` and exercise the change.
+
+**Auth gotcha:** `auth.kadoa.com` enforces an `ALLOWED_CALLBACK_ORIGINS` allowlist (`app.kadoa.com`, `mcp.kadoa.com`, `kadoa.com`) plus a loopback bypass for `127.0.0.1` when `NODE_ENV !== production`. `localhost` is **not** treated the same as `127.0.0.1` by that check. The test pod is configured with `MCP_SERVER_URL=http://localhost:3000` so the port-forwarded session resolves correctly. If you change the local port, update the deployment env var too:
+
+```bash
+kubectl set env deployment/mcp-server-test MCP_SERVER_URL=http://localhost:<PORT>
+```
+
+#### Promotion checklist
+
+Before flipping `latest` / deploying to prod:
+
+- [ ] RC consumed locally (`npx @kadoa/mcp@rc`) — stdio tools work
+- [ ] RC consumed via `mcp-server-test` — OAuth login succeeds end-to-end
+- [ ] No new errors in the test pod's logs (`kubectl logs deployment/mcp-server-test -f`)
+- [ ] Release Please PR open with the stable version
 
 ## Development
 
@@ -169,6 +245,71 @@ KADOA_PUBLIC_API_URI=http://localhost:12380 bun run dev
 
 The server starts in HTTP mode. You authenticate via OAuth the same way as with the remote server.
 
+## Contributing
+
+A typical feature touches three repos — **`kadoa-backend` → `kadoa-sdks` → `kadoa-mcp`**. The same surgery on three layers; same operation, different audience above it.
+
+### Architecture
+
+| Layer | Repo / path | Role |
+|---|---|---|
+| Backend endpoint | `kadoa-backend/` | The HTTP API. Source of truth; the OpenAPI spec is generated from here. |
+| SDK low-level | `kadoa-sdks/sdks/node/src/generated/api/*` | Auto-generated axios client. Raw HTTP, typed from the OpenAPI spec. **Do not hand-edit.** |
+| SDK domain (high-level) | `kadoa-sdks/sdks/node/src/domains/<thing>/<thing>.service.ts` | Thin domain wrapper over the generated client. `client.<thing>.<action>(...)`. This is what callers use. |
+| CLI | `kadoa-cli/src/commands/<thing>.ts` | Commander action: flag parsing, spinner, table/json output. Calls SDK domain. |
+| MCP (this repo) | `kadoa-mcp/src/tools.ts` | Zod input schema + tool description tuned for LLMs. Calls SDK domain. |
+
+Mental model:
+- **SDK** = pure function over HTTP.
+- **CLI** = SDK + human UX (flags, table output).
+- **MCP** = SDK + LLM UX (zod schema, prose description).
+
+CLI and MCP both call **identical** SDK domain methods. A new feature added to the SDK is picked up by both clients for free — as long as we keep the layering honest.
+
+### Adding a new feature
+
+1. **Backend** (`kadoa-backend`)
+   - Add or modify the HTTP endpoint.
+   - Make sure the OpenAPI spec reflects the change (paths, request/response schemas).
+
+2. **SDK** (`kadoa-sdks`) — always do this **before** MCP/CLI work (the SDK-first rule). No bandaid `axios` calls in MCP.
+   - Regenerate the low-level client:
+     ```bash
+     bun kadoa-codegen fetch-spec -e https://api.kadoa.com/openapi -f
+     bun kadoa-codegen generate -e https://api.kadoa.com/openapi --fetch-latest -f
+     ```
+     (Swap the endpoint for `http://localhost:12380/openapi` when developing against a local backend.)
+   - Add or extend the domain service in `sdks/node/src/domains/<thing>/<thing>.service.ts`. Keep it typed, no `any`.
+   - Commit `specs/` separately from generated/domain code so the API diff is reviewable.
+   - Open a PR. On merge, a new `@kadoa/node-sdk` version is released.
+
+3. **MCP** (this repo)
+   - Bump `@kadoa/node-sdk` in `package.json` to the new version, `bun install`.
+   - Add the tool in `src/tools.ts`:
+     - Zod input schema (use coercion helpers in `src/coercion.ts` where needed — LLM clients sometimes send strings for numbers/bools).
+     - Description string written **for the LLM**: when to call it, what inputs mean, what the response shape is.
+     - Implementation calls `ctx.client.<thing>.<action>(...)` — never raw HTTP.
+   - Add a unit test under `tests/unit/`.
+   - Use a Conventional Commit message (`feat(mcp): ...`, `fix(mcp): ...`). Release Please will cut the next version on merge to `main`.
+
+4. **CLI** (`kadoa-cli`), if the feature is user-facing on the command line: mirror the MCP step in `src/commands/<thing>.ts`. Same SDK call, different UX.
+
+### Anti-patterns
+
+- ❌ Raw `axios` calls or hand-rolled HTTP in `src/tools.ts`. Always go through `ctx.client.<thing>`.
+- ❌ Putting tool-shaped logic (input validation, response shaping) in the MCP layer when the SDK should expose it. If two clients would need the same logic, it belongs in the SDK.
+- ❌ Editing files under `sdks/node/src/generated/` by hand. They get overwritten by `kadoa-codegen generate`.
+- ❌ Bundling a spec update and an SDK feature in the same commit — keep `specs/` PRs separate from domain-method PRs for clean review.
+
+### Where to find things in this repo
+
+- `src/tools.ts` — every MCP tool. Single file by design; search for the tool name.
+- `src/auth.ts` — OAuth flow, JWT verification, team selection.
+- `src/client.ts` — wires `@kadoa/node-sdk` per request, injects bearer token.
+- `src/http.ts` — Express server, transport adapter, session handling.
+- `src/redis-store.ts` — token store for the hosted server.
+- `tests/unit/` — bun tests; run with `bun run test`.
+
 ## License
 
 MIT

package/dist/index.js

@@ -14552,7 +14552,7 @@ function finalize(ctx, schema) {
     result.$schema = "http://json-schema.org/draft-07/schema#";
   } else if (ctx.target === "draft-04") {
     result.$schema = "http://json-schema.org/draft-04/schema#";
-  } else if (ctx.target === "openapi-3.0") {} else {}
+  } else if (ctx.target === "openapi-3.0") {}
   if (ctx.external?.uri) {
     const id = ctx.external.registry.get(schema)?.id;
     if (!id)
@@ -14817,7 +14817,7 @@ var formatMap, stringProcessor = (schema, ctx, _json, _params) => {
     if (val === undefined) {
       if (ctx.unrepresentable === "throw") {
         throw new Error("Literal `undefined` cannot be represented in JSON Schema");
-      } else {}
+      }
     } else if (typeof val === "bigint") {
       if (ctx.unrepresentable === "throw") {
         throw new Error("BigInt literals cannot be represented in JSON Schema");
@@ -44451,6 +44451,9 @@ function isNewerVersion(version1, version2) {
   }
   return false;
 }
+async function resolveBearerToken(provider) {
+  return typeof provider === "function" ? await provider() : provider;
+}
 function createValidationDomain(core2, rules) {
   return {
     rules,
@@ -44498,9 +44501,9 @@ function createClientDomains(params) {
   const dataFetcherService = new DataFetcherService(client.apis.workflows);
   const channelsService = new NotificationChannelsService(client.apis.notifications, userService);
   const settingsService = new NotificationSettingsService(client.apis.notifications);
-  const workflowsCoreService = new WorkflowsCoreService(client.apis.workflows);
   const schemasService = new SchemasService(client);
   const templatesService = new TemplatesService(client);
+  const workflowsCoreService = new WorkflowsCoreService(client.apis.workflows, templatesService);
   const variablesService = new VariablesService(client);
   const channelSetupService = new NotificationSetupService(channelsService, settingsService);
   const coreService = new ValidationCoreService(client);
@@ -48714,7 +48717,7 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     }));
     return channels;
   }
-}, PUBLIC_API_URI, WSS_API_URI, REALTIME_API_URI, SDK_VERSION = "0.32.0", SDK_NAME = "kadoa-node-sdk", SDK_LANGUAGE = "node", debug6, isDrainControlMessage = (message) => message.type === "control.draining", isRealtimeEvent = (message) => message.type !== "heartbeat" && message.type !== "control.draining", _Realtime = class _Realtime2 {
+}, PUBLIC_API_URI, WSS_API_URI, REALTIME_API_URI, SDK_VERSION = "0.34.0", SDK_NAME = "kadoa-node-sdk", SDK_LANGUAGE = "node", debug6, isDrainControlMessage = (message) => message.type === "control.draining", isRealtimeEvent = (message) => message.type !== "heartbeat" && message.type !== "control.draining", _Realtime = class _Realtime2 {
   constructor(config2) {
     this.drainingSockets = /* @__PURE__ */ new Set;
     this.lastHeartbeat = Date.now();
@@ -49117,6 +49120,54 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     }
     return version2;
   }
+  async linkWorkflows(templateId, body) {
+    debug7("Linking %d workflow(s) to template: %s", body.workflowIds?.length ?? 0, templateId);
+    try {
+      const response = await this.templatesApi.v4TemplatesTemplateIdLinkPost({
+        templateId,
+        linkWorkflowsBody: body
+      });
+      return response.data;
+    } catch (error48) {
+      if (KadoaHttpException.isInstance(error48)) {
+        const httpError = error48;
+        const conflicts = httpError.httpStatus === 409 ? httpError.responseBody?.conflicts : undefined;
+        if (conflicts) {
+          return {
+            error: true,
+            success: false,
+            linkedCount: 0,
+            workflowIds: [],
+            conflicts
+          };
+        }
+      }
+      throw error48;
+    }
+  }
+  async getLinkedWorkflows(templateId) {
+    debug7("Listing workflows linked to template: %s", templateId);
+    const response = await this.templatesApi.v4TemplatesTemplateIdWorkflowsGet({
+      templateId
+    });
+    return response.data.data ?? [];
+  }
+  async applyVersion(templateId, body) {
+    debug7("Applying template %s version %d to %d workflow(s)", templateId, body.targetVersion, body.workflowIds?.length ?? 0);
+    const response = await this.templatesApi.v4TemplatesTemplateIdApplyPost({
+      templateId,
+      applyTemplateUpdateBody: body
+    });
+    return response.data;
+  }
+  async unlinkWorkflows(templateId, body) {
+    debug7("Unlinking %d workflow(s) from template: %s", body.workflowIds?.length ?? 0, templateId);
+    const response = await this.templatesApi.v4TemplatesTemplateIdUnlinkPost({
+      templateId,
+      unlinkWorkflowsBody: body
+    });
+    return response.data;
+  }
   async listSchemas(templateId) {
     debug7("Listing schemas for template: %s", templateId);
     const response = await this.templatesApi.v4TemplatesTemplateIdSchemasGet({
@@ -49146,7 +49197,6 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     const response = await this.client.axiosInstance.get("/v5/user", {
       baseURL: this.client.baseUrl,
       headers: {
-        "x-api-key": this.client.apiKey,
         "Content-Type": "application/json"
       }
     });
@@ -49443,36 +49493,82 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     });
   }
 }, JobStateEnum, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES2, debug9, WorkflowsCoreService = class {
-  constructor(workflowsApi) {
+  constructor(workflowsApi, templatesService) {
     this.workflowsApi = workflowsApi;
+    this.templatesService = templatesService;
   }
   async create(input) {
     validateAdditionalData(input.additionalData);
-    if (!input.userPrompt) {
+    const isFromTemplate = input.templateId != null;
+    if (isFromTemplate) {
+      const conflicting = [];
+      if (input.userPrompt != null)
+        conflicting.push("userPrompt");
+      if (input.entity != null)
+        conflicting.push("entity");
+      if (input.fields != null)
+        conflicting.push("fields");
+      if (input.schemaId != null)
+        conflicting.push("schemaId");
+      if (input.monitoring != null)
+        conflicting.push("monitoring");
+      if (input.navigationMode != null)
+        conflicting.push("navigationMode");
+      if (conflicting.length > 0) {
+        throw new KadoaSdkException(`Fields are defined by the template and cannot be supplied when creating from a template: ${conflicting.join(", ")}`, {
+          code: "VALIDATION_ERROR",
+          details: { conflicting }
+        });
+      }
+    } else if (!input.userPrompt) {
       throw new KadoaSdkException("userPrompt is required to create a workflow", {
         code: "VALIDATION_ERROR",
         details: { urls: input.urls }
       });
     }
     const domainName = new URL(input.urls[0]).hostname;
-    const request = {
-      urls: input.urls,
-      name: input.name ?? domainName,
-      description: input.description,
-      userPrompt: input.userPrompt,
-      navigationMode: "agentic-navigation",
-      schemaId: input.schemaId,
-      ...input.entity != null && { entity: input.entity },
-      fields: input.fields,
-      bypassPreview: input.bypassPreview ?? true,
-      tags: input.tags,
-      interval: input.interval,
-      monitoring: input.monitoring,
-      location: input.location,
-      schedules: input.schedules,
-      additionalData: input.additionalData,
-      limit: input.limit
-    };
+    let request;
+    if (isFromTemplate) {
+      const templateId = input.templateId;
+      const templateVersion = input.templateVersion ?? await this.resolveLatestVersion(templateId);
+      request = {
+        urls: input.urls,
+        templateId,
+        templateVersion,
+        ...input.name != null && { name: input.name },
+        ...input.description != null && { description: input.description },
+        ...input.tags != null && { tags: input.tags },
+        ...input.interval != null && { interval: input.interval },
+        ...input.schedules != null && { schedules: input.schedules },
+        ...input.location != null && { location: input.location },
+        ...input.bypassPreview != null && {
+          bypassPreview: input.bypassPreview
+        },
+        ...input.additionalData != null && {
+          additionalData: input.additionalData
+        },
+        ...input.limit != null && { limit: input.limit }
+      };
+    } else {
+      request = {
+        urls: input.urls,
+        name: input.name ?? domainName,
+        description: input.description,
+        userPrompt: input.userPrompt,
+        navigationMode: "agentic-navigation",
+        schemaId: input.schemaId,
+        ...input.entity != null && { entity: input.entity },
+        fields: input.fields,
+        bypassPreview: input.bypassPreview ?? true,
+        tags: input.tags,
+        interval: input.interval,
+        monitoring: input.monitoring,
+        location: input.location,
+        schedules: input.schedules,
+        additionalData: input.additionalData,
+        limit: input.limit
+      };
+    }
     const response = await this.workflowsApi.v4WorkflowsPost({
       publicWorkflowCreateRequest: request
     });
@@ -49487,6 +49583,23 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     }
     return { id: workflowId };
   }
+  async resolveLatestVersion(templateId) {
+    if (!this.templatesService) {
+      throw new KadoaSdkException("TemplatesService is required to resolve a template's latest version. Pass `templateVersion` explicitly or construct WorkflowsCoreService with a TemplatesService.", {
+        code: "INTERNAL_ERROR",
+        details: { templateId }
+      });
+    }
+    const template = await this.templatesService.get(templateId);
+    const latest = template.latestVersion;
+    if (latest == null) {
+      throw new KadoaSdkException(`Template ${templateId} has no published versions; supply templateVersion explicitly or publish a version first.`, {
+        code: "VALIDATION_ERROR",
+        details: { templateId }
+      });
+    }
+    return latest;
+  }
   async get(id) {
     const response = await this.workflowsApi.v4WorkflowsWorkflowIdGet({
       workflowId: id
@@ -49645,12 +49758,15 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     const timeout2 = config2.timeout ?? 30000;
     const headers = createSdkHeaders();
     this._axiosInstance = createAxiosInstance({ timeout: timeout2, headers });
-    this._axiosInstance.interceptors.request.use((reqConfig) => {
+    this._axiosInstance.interceptors.request.use(async (reqConfig) => {
       if (this._bearerToken) {
+        const token = await resolveBearerToken(this._bearerToken);
         if (!reqConfig.headers["Authorization"]) {
-          reqConfig.headers["Authorization"] = `Bearer ${this._bearerToken}`;
+          reqConfig.headers["Authorization"] = `Bearer ${token}`;
         }
         delete reqConfig.headers["x-api-key"];
+      } else if (this._apiKey && !reqConfig.headers["x-api-key"]) {
+        reqConfig.headers["x-api-key"] = this._apiKey;
       }
       return reqConfig;
     });
@@ -49714,7 +49830,9 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     };
   }
   async listTeams(opts) {
-    const headers = opts?.bearerToken ? { Authorization: `Bearer ${opts.bearerToken}` } : undefined;
+    const headers = opts?.bearerToken ? {
+      Authorization: `Bearer ${await resolveBearerToken(opts.bearerToken)}`
+    } : undefined;
     const response = await this._axiosInstance.get("/v5/user", {
       baseURL: this._baseUrl,
       ...headers && { headers }
@@ -50848,7 +50966,7 @@ function registerTools(server, ctx) {
     urls: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string()).min(1)).optional().describe("Starting URLs for the workflow (array of strings). Also accepts a single URL string.")
   };
   const extractionInputShape = {
-    prompt: exports_external.string().describe('Natural language description of what to extract (e.g., "Extract product prices and names")'),
+    prompt: exports_external.string().optional().describe('Natural language description of what to extract (e.g., "Extract product prices and names"). Required unless templateId is provided.'),
     name: exports_external.string().optional().describe("Optional name for the workflow"),
     entity: exports_external.string().optional().describe("Entity name for extraction (e.g., 'Product', 'Job Posting')"),
     schema: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object(SchemaFieldShape))).optional().describe("Extraction schema fields. If omitted, the AI agent auto-detects the schema.")
@@ -50953,10 +51071,12 @@ function registerTools(server, ctx) {
 
 ` + "Create a data extraction workflow using agentic navigation. Supports one-time or scheduled runs. " + "If entity and schema are provided, they guide the extraction; otherwise the AI agent auto-detects the schema from the page. " + "The workflow runs asynchronously and may take several minutes. Do NOT poll or sleep-wait for completion. " + `Return the workflow ID to the user and let them check back later with get_workflow or fetch_data.
 
-` + "NOTE: This tool is for one-time or scheduled extraction ONLY. " + "For continuous real-time monitoring (watching a page for changes and alerting), use the create_realtime_monitor tool instead.",
+` + "PREFER TEMPLATES: If the user's request matches an existing template, instantiate it via `templateId` instead of writing a fresh prompt/schema. " + "Use `list_templates` to discover available templates and `get_template` to inspect schemas before deciding. " + "When `templateId` is set, only `urls` is required — `prompt`, `entity`, and `schema` must NOT be supplied; they are inherited from the template version.\n\n" + "NOTE: This tool is for one-time or scheduled extraction ONLY. " + "For continuous real-time monitoring (watching a page for changes and alerting), use the create_realtime_monitor tool instead.",
     inputSchema: strictSchema({
       ...extractionInputShape,
       ...urlInputShape,
+      templateId: exports_external.string().optional().describe("Instantiate this workflow from a published template. When set, only 'urls' is required — prompt/entity/schema must NOT be supplied; they are inherited from the template version, and the workflow's output conforms to the template's declared schema (field names are enforced, not drifted). Discover templates via list_templates."),
+      templateVersion: exports_external.preprocess(coerceNumber(), exports_external.number()).optional().describe("Specific published template version (integer) to instantiate. Defaults to the latest published version when templateId is set."),
       description: exports_external.string().max(500).optional().describe("Description of what this workflow does (max 500 characters)"),
       tags: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string())).optional().describe("Tags for organizing workflows"),
       limit: exports_external.preprocess(coerceNumber(), exports_external.number()).optional().describe("Maximum number of records to extract per run. Useful for limiting scope or cost control."),
@@ -50991,32 +51111,62 @@ function registerTools(server, ctx) {
     if (args.updateInterval === "CUSTOM" && (!args.schedules || args.schedules.length === 0)) {
       return errorResult("updateInterval='CUSTOM' requires at least one cron expression in the 'schedules' field (e.g. '0 8 * * 2' for Tuesdays at 8am UTC).");
     }
-    let builder = ctx.client.extract({
-      urls,
-      name: args.name || "Untitled Workflow",
-      userPrompt: args.prompt,
-      extraction: buildExtraction(args),
-      interval: args.updateInterval,
-      description: args.description,
-      schedules: args.schedules
-    });
     const n = args.notifications;
-    const hasNotifications = n && (n.email || n.webhook || n.slack || n.websocket);
-    if (hasNotifications) {
-      builder = builder.withNotifications({
-        events: ["workflow_data_change"],
-        channels: buildNotificationChannels(n)
+    const hasNotifications = !!(n && (n.email || n.webhook || n.slack || n.websocket));
+    let workflowId;
+    if (args.templateId) {
+      if (args.prompt || args.entity || args.schema) {
+        return errorResult("When 'templateId' is set, 'prompt', 'entity', and 'schema' must NOT be supplied — they are inherited from the template version.");
+      }
+      const { id } = await ctx.client.workflow.create({
+        urls,
+        name: args.name || "Untitled Workflow",
+        description: args.description,
+        interval: args.updateInterval,
+        schedules: args.schedules,
+        tags: args.tags && args.tags.length > 0 ? args.tags : undefined,
+        limit: args.limit,
+        templateId: args.templateId,
+        templateVersion: args.templateVersion
       });
-    }
-    const workflow = await builder.create();
-    const needsUpdate = args.limit !== undefined || args.tags && args.tags.length > 0;
-    if (needsUpdate) {
-      const updates = {};
-      if (args.limit !== undefined)
-        updates.limit = args.limit;
-      if (args.tags && args.tags.length > 0)
-        updates.tags = args.tags;
-      await ctx.client.workflow.update(workflow.workflowId, updates);
+      workflowId = id;
+      if (hasNotifications) {
+        await ctx.client.notification.configure({
+          workflowId,
+          events: ["workflow_data_change"],
+          channels: buildNotificationChannels(n)
+        });
+      }
+    } else {
+      if (!args.prompt) {
+        return errorResult("'prompt' is required unless 'templateId' is provided.");
+      }
+      let builder = ctx.client.extract({
+        urls,
+        name: args.name || "Untitled Workflow",
+        userPrompt: args.prompt,
+        extraction: buildExtraction(args),
+        interval: args.updateInterval,
+        description: args.description,
+        schedules: args.schedules
+      });
+      if (hasNotifications) {
+        builder = builder.withNotifications({
+          events: ["workflow_data_change"],
+          channels: buildNotificationChannels(n)
+        });
+      }
+      const workflow = await builder.create();
+      workflowId = workflow.workflowId;
+      const needsUpdate = args.limit !== undefined || args.tags && args.tags.length > 0;
+      if (needsUpdate) {
+        const updates = {};
+        if (args.limit !== undefined)
+          updates.limit = args.limit;
+        if (args.tags && args.tags.length > 0)
+          updates.tags = args.tags;
+        await ctx.client.workflow.update(workflowId, updates);
+      }
     }
     const enabledChannels = await describeNotifications(n);
     let message = "Workflow created successfully. The AI agent will start extracting data automatically.";
@@ -51026,8 +51176,8 @@ function registerTools(server, ctx) {
     message += " Use fetch_data to retrieve the latest extracted results.";
     return jsonResult({
       success: true,
-      workflowId: workflow.workflowId,
-      dashboardUrl: workflowDashboardUrl(workflow.workflowId),
+      workflowId,
+      dashboardUrl: workflowDashboardUrl(workflowId),
       message
     });
   }));
@@ -51889,10 +52039,14 @@ function registerTools(server, ctx) {
   const TemplateSchemaFieldShape = {
     name: exports_external.string().describe("Field name"),
     description: exports_external.string().optional().describe("Field description"),
-    fieldType: exports_external.string().optional().describe("Field type (e.g. SCHEMA)"),
+    fieldType: exports_external.string().optional().describe("Field type (e.g. SCHEMA, CLASSIFICATION)"),
     example: exports_external.string().optional().describe("Example value"),
     dataType: exports_external.string().optional().describe("Data type (STRING, NUMBER, DATE, LINK, etc.)"),
-    isKey: exports_external.preprocess(coerceBoolean(), exports_external.boolean()).optional().describe("Whether the field is a key field")
+    isKey: exports_external.preprocess(coerceBoolean(), exports_external.boolean()).optional().describe("Whether the field is a key field"),
+    categories: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object({
+      title: exports_external.string().describe("Short title/label of the category"),
+      definition: exports_external.string().describe("Full definition/description of the category")
+    }))).optional().describe("Predefined categories for a CLASSIFICATION field ({title, definition}[]). Required for fieldType=CLASSIFICATION; omitted otherwise.")
   };
   server.registerTool("create_template_version", {
     description: "Publish a new version of a template. Versions capture the full workflow config: prompt, schema, and notifications. All fields are optional — include only what this version should set.",
@@ -51902,13 +52056,41 @@ function registerTools(server, ctx) {
       schemaId: exports_external.string().optional().describe("Existing schema ID to reference (mutually exclusive with schemaFields)"),
       schemaFields: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object(TemplateSchemaFieldShape))).optional().describe("Inline schema fields to create a new schema (mutually exclusive with schemaId)"),
       schemaEntity: exports_external.string().optional().describe("Entity name for the inline schema"),
+      schemaValidationRules: exports_external.preprocess(coerceJson(), exports_external.record(exports_external.string(), exports_external.record(exports_external.string(), exports_external.unknown()))).optional().describe("Per-field schema validation rules, keyed by field name. Not inherited from prior versions — omitting this on a new version drops any rules the previous version had."),
       notifications: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object({
         eventType: exports_external.string().describe("Notification event type"),
         eventConfiguration: exports_external.preprocess(coerceJson(), exports_external.record(exports_external.string(), exports_external.unknown())).optional(),
         enabled: exports_external.preprocess(coerceBoolean(), exports_external.boolean()).optional(),
         channelIds: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.string())).optional(),
         channels: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object({ channelId: exports_external.string() }))).optional()
-      }))).optional().describe("Notification configuration for this version")
+      }))).optional().describe("Notification configuration for this version"),
+      frequency: exports_external.preprocess(coerceJson(), exports_external.object({
+        interval: exports_external.enum([
+          "ONLY_ONCE",
+          "EVERY_10_MINUTES",
+          "HALF_HOURLY",
+          "HOURLY",
+          "THREE_HOURLY",
+          "SIX_HOURLY",
+          "TWELVE_HOURLY",
+          "EIGHTEEN_HOURLY",
+          "DAILY",
+          "TWO_DAY",
+          "THREE_DAY",
+          "WEEKLY",
+          "BIWEEKLY",
+          "TRIWEEKLY",
+          "FOUR_WEEKS",
+          "MONTHLY",
+          "CUSTOM",
+          "REAL_TIME"
+        ]).optional().describe("Scheduling interval the template controls for linked workflows. Use CUSTOM with 'schedules' for cron."),
+        schedules: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object({
+          type: exports_external.enum(["repeat", "cron"]).describe("'repeat' (interval token) or 'cron' (cron expressions)"),
+          interval: exports_external.string().optional().describe("Repeat token (e.g. '1h', '1d') when type='repeat'"),
+          expressions: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string())).optional().describe("Cron expressions when type='cron' (e.g. '0 8 * * 2')")
+        }))).optional().describe("Schedule specs. Required when interval='CUSTOM'.")
+      })).optional().describe("Template-controlled scheduling for linked workflows ({interval, schedules}). Linked workflows inherit and cannot override this when set.")
     }),
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
   }, withErrorHandling("create_template_version", async (args) => {
@@ -51927,7 +52109,7 @@ function registerTools(server, ctx) {
       name: exports_external.string().optional().describe("Name for the new template (required if templateId is not set)"),
       description: exports_external.string().optional().describe("Description for the new template"),
       templateId: exports_external.string().optional().describe("Existing template ID to add a new version to (mutually exclusive with name)"),
-      includeParts: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.enum(["prompt", "schema", "notifications"])).optional()).describe("Which parts of the workflow config to include. Omit to include all. At least 1 required if provided.")
+      includeParts: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.enum(["prompt", "schema", "schemaValidationRules", "notifications", "frequency"])).optional()).describe("Which parts of the workflow config to include: prompt, schema, schemaValidationRules, notifications, frequency. Omit to include all. At least 1 required if provided.")
     }),
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
   }, withErrorHandling("save_workflow_as_template", async (args) => {
@@ -51954,6 +52136,83 @@ function registerTools(server, ctx) {
     const schemas4 = await ctx.client.template.listSchemas(args.templateId);
     return jsonResult({ schemas: schemas4, count: schemas4.length });
   }));
+  server.registerTool("link_template_to_workflows", {
+    description: "Link one or more EXISTING workflows to a template in a single call. " + "This is the bulk equivalent of creating a workflow with `templateId`: linked workflows adopt the template's configuration (prompt, schema, notifications) and stay in sync with it. " + "The template ENFORCES its schema on linked workflows — their extracted output conforms to the template's declared field names, so this is the way to make many workflows produce a consistent, canonical schema. " + "Use `list_templates`/`get_template` to find the template, and `list_workflows` to find the workflow IDs. " + "Set `force: true` to relink workflows already linked to a different template.",
+    inputSchema: strictSchema({
+      templateId: exports_external.string().describe("The template ID to link workflows to"),
+      workflowIds: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string()).min(1)).describe("Workflow IDs to link to the template (array of strings). Also accepts a single ID string."),
+      force: exports_external.preprocess(coerceBoolean(), exports_external.boolean()).optional().describe("If true, relink workflows that are already linked to another template. Defaults to false.")
+    }),
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
+  }, withErrorHandling("link_template_to_workflows", async (args) => {
+    const result = await ctx.client.template.linkWorkflows(args.templateId, {
+      workflowIds: args.workflowIds,
+      ...args.force != null && { force: args.force }
+    });
+    if (result.conflicts && result.conflicts.length > 0) {
+      const summary = result.conflicts.map((c) => `${c.workflowName || c.workflowId} (currently on "${c.templateName}")`).join(", ");
+      return jsonResult({
+        success: false,
+        conflicts: result.conflicts,
+        message: `Cannot link — ${result.conflicts.length} workflow(s) are already linked to another template: ${summary}. ` + "Re-run with force: true to move them to this template."
+      });
+    }
+    return jsonResult({
+      success: true,
+      linkedCount: result.linkedCount,
+      workflowIds: result.workflowIds,
+      message: `Linked ${result.linkedCount} workflow(s) to template ${args.templateId}. Linked workflows now follow the template's schema.`
+    });
+  }));
+  server.registerTool("apply_template_version", {
+    description: "Push a template version onto its linked workflows. Updates the given workflows to the template's `targetVersion`, applying the template-controlled parts (prompt, schema, validation rules, notifications, frequency). " + "Use this after publishing a new template version to bring linked workflows up to date (see list_template_workflows for which workflows are outdated). " + "Returns how many workflows were updated and which parts the template controls.",
+    inputSchema: strictSchema({
+      templateId: exports_external.string().describe("The template ID whose version to apply"),
+      targetVersion: exports_external.preprocess(coerceNumber(), exports_external.number()).describe("The template version number to apply to the workflows"),
+      workflowIds: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string()).min(1)).describe("Workflow IDs to update to the target version (array of strings). Also accepts a single ID string.")
+    }),
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
+  }, withErrorHandling("apply_template_version", async (args) => {
+    const result = await ctx.client.template.applyVersion(args.templateId, {
+      targetVersion: args.targetVersion,
+      workflowIds: args.workflowIds
+    });
+    return jsonResult({
+      success: true,
+      updatedCount: result.updatedCount,
+      workflowIds: result.workflowIds,
+      controlledParts: result.controlledParts,
+      message: `Applied template ${args.templateId} v${args.targetVersion} to ${result.updatedCount} workflow(s).`
+    });
+  }));
+  server.registerTool("list_template_workflows", {
+    description: "List the workflows linked to a template, with each workflow's pinned template version and an `isOutdated` flag (true when a newer template version exists). " + "Use this to verify which workflows are bound to a template and to find ones that need apply_template_version.",
+    inputSchema: strictSchema({
+      templateId: exports_external.string().describe("The template ID")
+    }),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  }, withErrorHandling("list_template_workflows", async (args) => {
+    const workflows = await ctx.client.template.getLinkedWorkflows(args.templateId);
+    return jsonResult({ workflows, count: workflows.length });
+  }));
+  server.registerTool("unlink_template_from_workflows", {
+    description: "Unlink one or more workflows from a template in a single call. " + "Unlinked workflows keep their current configuration but stop tracking the template (future template version changes no longer apply to them).",
+    inputSchema: strictSchema({
+      templateId: exports_external.string().describe("The template ID to unlink workflows from"),
+      workflowIds: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string()).min(1)).describe("Workflow IDs to unlink from the template (array of strings). Also accepts a single ID string.")
+    }),
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
+  }, withErrorHandling("unlink_template_from_workflows", async (args) => {
+    const result = await ctx.client.template.unlinkWorkflows(args.templateId, {
+      workflowIds: args.workflowIds
+    });
+    return jsonResult({
+      success: true,
+      unlinkedCount: result.unlinkedCount,
+      workflowIds: result.workflowIds,
+      message: `Unlinked ${result.unlinkedCount} workflow(s) from template ${args.templateId}.`
+    });
+  }));
 }
 var SchemaFieldShape, DASHBOARD_BASE_URL = "https://www.kadoa.com", WORKFLOW_AUDIT_WATCHED_KEYS;
 var init_tools = __esm(() => {
@@ -51987,7 +52246,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@kadoa/mcp",
-    version: "0.5.5",
+    version: "0.5.8-rc.1",
     description: "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
     type: "module",
     main: "dist/index.js",
@@ -52011,7 +52270,7 @@ var init_package = __esm(() => {
       prepublishOnly: "bun run check-types && bun run test:unit && bun run build"
     },
     dependencies: {
-      "@kadoa/node-sdk": "^0.32.0",
+      "@kadoa/node-sdk": "^0.34.0",
       "@modelcontextprotocol/sdk": "^1.26.0",
       express: "^5.2.1",
       ioredis: "^5.6.1",
@@ -57241,7 +57500,9 @@ function createServer(auth) {
       "Use list_changes and get_change to retrieve detected diffs from real-time monitoring workflows.",
       "",
       "Schema tips: Use descriptive field names and examples. Group related data under one entity.",
-      "The AI agent uses the schema + prompt to understand what to extract \u2014 a detailed prompt with a comprehensive schema produces better results than multiple simple workflows."
+      "The AI agent uses the schema + prompt to understand what to extract \u2014 a detailed prompt with a comprehensive schema produces better results than multiple simple workflows.",
+      "",
+      "Templates enforce their schema: a workflow created from a template (create_workflow with templateId) or linked to one (link_template_to_workflows) produces output whose field names conform to the template's declared schema. Use templates when you need many workflows to return a consistent, canonical set of fields \u2014 do NOT assume the extractor will drift field names away from a template's schema."
     ].join(`
 `)
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadoa/mcp",
-  "version": "0.5.5",
+  "version": "0.5.8-rc.1",
   "description": "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
   "type": "module",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
     "prepublishOnly": "bun run check-types && bun run test:unit && bun run build"
   },
   "dependencies": {
-    "@kadoa/node-sdk": "^0.32.0",
+    "@kadoa/node-sdk": "^0.34.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "express": "^5.2.1",
     "ioredis": "^5.6.1",