@kadoa/mcp 0.5.7 → 0.5.8

package/README.md

@@ -137,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
 
@@ -180,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

@@ -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,
@@ -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.33.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"
       }
     });
@@ -49708,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;
     });
@@ -49777,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 }
@@ -51020,7 +51075,7 @@ function registerTools(server, ctx) {
     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. Discover templates via list_templates."),
+      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"),
@@ -51984,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.",
@@ -51997,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) => {
@@ -52022,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) => {
@@ -52049,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(() => {
@@ -52082,7 +52246,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@kadoa/mcp",
-    version: "0.5.7",
+    version: "0.5.8",
     description: "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
     type: "module",
     main: "dist/index.js",
@@ -52106,7 +52270,7 @@ var init_package = __esm(() => {
       prepublishOnly: "bun run check-types && bun run test:unit && bun run build"
     },
     dependencies: {
-      "@kadoa/node-sdk": "^0.33.0",
+      "@kadoa/node-sdk": "^0.34.0",
       "@modelcontextprotocol/sdk": "^1.26.0",
       express: "^5.2.1",
       ioredis: "^5.6.1",
@@ -57336,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.7",
+  "version": "0.5.8",
   "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.33.0",
+    "@kadoa/node-sdk": "^0.34.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "express": "^5.2.1",
     "ioredis": "^5.6.1",