@axonity-ai/mcp 0.6.0 → 0.8.0

package/dist/tools/authoringSpec.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The building blocks of this deploy, read from the server instead of restated
+ * here.
+ *
+ * `apply_workflow_mutations` used to name all 22 command types in its own
+ * description. That list was correct only by maintenance, and it had already
+ * been wrong in the dangerous direction once: it advertised three operations
+ * the API rejected with a 422 (#32, axonity-flow#802). A conformance test then
+ * pinned the prose to the schema — the right fix for a list you keep, and still
+ * a list you keep.
+ *
+ * `GET /workflows/operations` (axonity-flow#802 B4) removes the list instead of
+ * guarding it. It is generated from the engine's mutation registry — the same
+ * source the mutations route validates against — so a command this tool reports
+ * is a command the API accepts, by construction rather than by agreement. A new
+ * server operation becomes discoverable with no change in this repository,
+ * which is the acceptance criterion #8 was filed for.
+ *
+ * axonity-flow#961 S1 extends that property to three more lists that had no
+ * route at all, and it is the same story each time: `conventions.ts` named nine
+ * step types where seven validate — `loop` and `for_each` both answer
+ * `step_invalid_type` — because a list nobody could read is a list that drifts.
+ * So the response now carries four generated lists, and this connector names
+ * none of them:
+ *   - `operations`         — the mutation commands, as before.
+ *   - `triggerTypes`       — every value a trigger's `typeId` may hold.
+ *   - `stepTypes`          — every value a step's `type` may hold, INCLUDING the
+ *     ones an author may not write, each with the reason and what to write
+ *     instead. Omitting those would read as "does not exist".
+ *   - `scheduleRuleKinds`  — the shapes a schedule rule takes, each with a
+ *     working example the backend round-trips through its own parser on every
+ *     read, so a published example cannot rot.
+ *
+ * axonity-flow#964 adds three more, and they are the ones that bite quietly.
+ * A value's type is not carried by the same KEY everywhere, and the three
+ * vocabularies behind those keys are not interchangeable:
+ *   - `parameterTypes`   — a trigger parameter's / workflow constant's `type`.
+ *     Knows `boolean` and `constant`.
+ *   - `outputKinds`      — a step output's / input's `kind`. Narrower, and a
+ *     DIFFERENT KEY. Spells the same idea `yes-no`, not `boolean`.
+ *   - `schemaFieldKinds` — the canonical builder's vocabulary, inside a field's
+ *     `schema`. Widest and newest; where a `schema` is present it wins.
+ * Writing `kind` on a trigger parameter is not a 422 — it is a key nothing
+ * reads, so the value falls back to text and the run binds the wrong shape.
+ * That is the failure this connector shipped once (axonity-mcp#47) by reading
+ * the field off the model that DECLARES it rather than the code that READS it.
+ *
+ * `rulesVersion` is a content hash over all four: same hash, nothing to
+ * re-fetch. It is what makes "read the spec at the start of each authoring
+ * task" cheap enough to actually do.
+ *
+ * **Cost.** The full catalog is ~20 KB — the payload schemas are the bulk of it,
+ * and `add_step` alone is 3 KB. Handing that to an agent that wanted to know
+ * which commands exist is the mistake #33 was filed about: a default that is
+ * correct but unaffordable produces the shortcut, not the careful read. So the
+ * payload SCHEMAS are what the index drops, per command, on request. The three
+ * vocabulary lists are small and are the answer to "what may I write at all",
+ * so they always ride along — trimming them would recreate the gap this closed.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AxonityClient } from "../client.js";
+/**
+ * Project the catalog to what was asked for, keeping the envelope.
+ *
+ * Exported for testing. `types` is matched against the server's own `type`
+ * values with NO local list to check them against — an unknown name comes back
+ * in `unknownTypes` rather than being rejected here, because the connector is
+ * not the authority on what exists. That is the whole point of reading the
+ * catalogue.
+ *
+ * Only `operations` is ever projected. The envelope is spread through on both
+ * paths, so `triggerTypes` / `stepTypes` / `scheduleRuleKinds` — and anything
+ * the backend adds next to them — survive unread and unnamed here.
+ */
+export declare function projectCatalog(response: unknown, types?: string[]): unknown;
+export declare function registerAuthoringSpecTools(server: McpServer, client: AxonityClient): void;

package/dist/tools/authoringSpec.js

@@ -0,0 +1,169 @@
+/**
+ * The building blocks of this deploy, read from the server instead of restated
+ * here.
+ *
+ * `apply_workflow_mutations` used to name all 22 command types in its own
+ * description. That list was correct only by maintenance, and it had already
+ * been wrong in the dangerous direction once: it advertised three operations
+ * the API rejected with a 422 (#32, axonity-flow#802). A conformance test then
+ * pinned the prose to the schema — the right fix for a list you keep, and still
+ * a list you keep.
+ *
+ * `GET /workflows/operations` (axonity-flow#802 B4) removes the list instead of
+ * guarding it. It is generated from the engine's mutation registry — the same
+ * source the mutations route validates against — so a command this tool reports
+ * is a command the API accepts, by construction rather than by agreement. A new
+ * server operation becomes discoverable with no change in this repository,
+ * which is the acceptance criterion #8 was filed for.
+ *
+ * axonity-flow#961 S1 extends that property to three more lists that had no
+ * route at all, and it is the same story each time: `conventions.ts` named nine
+ * step types where seven validate — `loop` and `for_each` both answer
+ * `step_invalid_type` — because a list nobody could read is a list that drifts.
+ * So the response now carries four generated lists, and this connector names
+ * none of them:
+ *   - `operations`         — the mutation commands, as before.
+ *   - `triggerTypes`       — every value a trigger's `typeId` may hold.
+ *   - `stepTypes`          — every value a step's `type` may hold, INCLUDING the
+ *     ones an author may not write, each with the reason and what to write
+ *     instead. Omitting those would read as "does not exist".
+ *   - `scheduleRuleKinds`  — the shapes a schedule rule takes, each with a
+ *     working example the backend round-trips through its own parser on every
+ *     read, so a published example cannot rot.
+ *
+ * axonity-flow#964 adds three more, and they are the ones that bite quietly.
+ * A value's type is not carried by the same KEY everywhere, and the three
+ * vocabularies behind those keys are not interchangeable:
+ *   - `parameterTypes`   — a trigger parameter's / workflow constant's `type`.
+ *     Knows `boolean` and `constant`.
+ *   - `outputKinds`      — a step output's / input's `kind`. Narrower, and a
+ *     DIFFERENT KEY. Spells the same idea `yes-no`, not `boolean`.
+ *   - `schemaFieldKinds` — the canonical builder's vocabulary, inside a field's
+ *     `schema`. Widest and newest; where a `schema` is present it wins.
+ * Writing `kind` on a trigger parameter is not a 422 — it is a key nothing
+ * reads, so the value falls back to text and the run binds the wrong shape.
+ * That is the failure this connector shipped once (axonity-mcp#47) by reading
+ * the field off the model that DECLARES it rather than the code that READS it.
+ *
+ * `rulesVersion` is a content hash over all four: same hash, nothing to
+ * re-fetch. It is what makes "read the spec at the start of each authoring
+ * task" cheap enough to actually do.
+ *
+ * **Cost.** The full catalog is ~20 KB — the payload schemas are the bulk of it,
+ * and `add_step` alone is 3 KB. Handing that to an agent that wanted to know
+ * which commands exist is the mistake #33 was filed about: a default that is
+ * correct but unaffordable produces the shortcut, not the careful read. So the
+ * payload SCHEMAS are what the index drops, per command, on request. The three
+ * vocabulary lists are small and are the answer to "what may I write at all",
+ * so they always ride along — trimming them would recreate the gap this closed.
+ */
+import { z } from "zod";
+import { guard, jsonResult } from "./result.js";
+/**
+ * Project the catalog to what was asked for, keeping the envelope.
+ *
+ * Exported for testing. `types` is matched against the server's own `type`
+ * values with NO local list to check them against — an unknown name comes back
+ * in `unknownTypes` rather than being rejected here, because the connector is
+ * not the authority on what exists. That is the whole point of reading the
+ * catalogue.
+ *
+ * Only `operations` is ever projected. The envelope is spread through on both
+ * paths, so `triggerTypes` / `stepTypes` / `scheduleRuleKinds` — and anything
+ * the backend adds next to them — survive unread and unnamed here.
+ */
+export function projectCatalog(response, types) {
+    if (typeof response !== "object" || response === null || Array.isArray(response)) {
+        return response;
+    }
+    const source = response;
+    if (!Array.isArray(source.operations))
+        return response;
+    const rows = source.operations;
+    const wanted = types && types.length > 0 ? new Set(types) : undefined;
+    if (wanted) {
+        const present = new Set(rows.map((row) => (typeof row.type === "string" ? row.type : "")));
+        const unknownTypes = [...wanted].filter((t) => !present.has(t));
+        return {
+            ...source,
+            operations: rows.filter((row) => typeof row.type === "string" && wanted.has(row.type)),
+            ...(unknownTypes.length > 0
+                ? {
+                    unknownTypes,
+                    // Not an error: this deploy's catalogue is the authority, and a
+                    // name it does not carry is simply not a command here.
+                    unknownTypesNote: "This backend's catalogue has no such operation. Call again " +
+                        "without `types` to see what it does have.",
+                }
+                : {}),
+        };
+    }
+    return {
+        ...source,
+        operations: rows.map((row) => ({ type: row.type, description: row.description })),
+        // Say what was dropped and how to get it — the omission a reader cannot see
+        // is the same trap as the cost it avoids. Note this names `operations`
+        // only: the vocabulary lists beside it are returned in full.
+        schemasOmitted: "`operations` is an index (type + description) — its payload schemas are " +
+            'omitted. Pass `types: ["add_step", …]` for the live payload schema of ' +
+            "the commands you are about to write; the full catalogue is ~20 KB and " +
+            "is rarely what you need. Everything else in this response is complete.",
+    };
+}
+export function registerAuthoringSpecTools(server, client) {
+    server.tool("get_workflow_authoring_spec", "Everything THIS Axonity deploy can be built from, read live from the " +
+        "server — not a list this connector keeps. Read it at the start of an " +
+        "authoring task, before `apply_workflow_mutations`. Seven lists come back:" +
+        "\n- `operations` — the mutation commands, with their payload schemas." +
+        "\n- `triggerTypes` — every value a trigger's `typeId` may hold. " +
+        "`category: true` marks a broad category id rather than a concrete type; " +
+        "both validate, but reach for the concrete one." +
+        "\n- `stepTypes` — every value a step's `type` may hold. Types you may " +
+        "NOT author are listed too, with `authorable: false` and a `reason` " +
+        "saying how to express that intention instead — so reaching for one gets " +
+        "you an answer rather than a `step_invalid_type`." +
+        "\n- `scheduleRuleKinds` — the shapes a schedule rule takes, each with a " +
+        "working `example` to copy and the sentence it `describes`. Every example " +
+        "is round-tripped through the platform's own parser as it is served, so " +
+        "it is one this deploy demonstrably accepts." +
+        "\n\nAND THREE VOCABULARIES FOR A VALUE'S TYPE, which are NOT " +
+        "interchangeable and are not even read from the same key. Check which one " +
+        "applies before you write it:" +
+        "\n- `parameterTypes` — what a TRIGGER PARAMETER or a WORKFLOW CONSTANT " +
+        "may hold, in its `type` field. This is the key the platform reads on " +
+        "those two shapes; `kind` is not. It is also the only one of the three " +
+        "that knows `constant`." +
+        "\n- `outputKinds` — what a step OUTPUT or INPUT may hold, in its `kind` " +
+        "field. Narrower, a different key, and it spells the yes/no idea " +
+        "differently from `parameterTypes`." +
+        "\n- `schemaFieldKinds` — the canonical builder's vocabulary, used inside " +
+        "a field's `schema`. Widest and newest; where a `schema` object is " +
+        "present it WINS over the `type` or `kind` beside it." +
+        "\n\nGetting this wrong is silent. A `kind` written on a trigger " +
+        "parameter is not a 422 — it is a key nothing reads, so the value falls " +
+        "back to text and everything downstream binds the wrong shape. Read the " +
+        "list that matches the shape you are writing." +
+        "\n\nBy default `operations` is an INDEX: each command's `type` and " +
+        "one-line `description`. Pass `types` to get the live `payloadSchema` for " +
+        "the commands you are about to write — the full catalogue with every " +
+        "schema is ~20 KB, which is rarely what you need. The other six lists " +
+        "are always returned complete. " +
+        "\n\n`rulesVersion` is a content hash over all of them: while it is " +
+        "unchanged there is nothing to re-fetch. Re-read the spec when it changes, " +
+        "or when a mutation fails with a 422 that suggests your idea of a command " +
+        "is out of date. " +
+        "\n\nAnything missing here is something this backend will reject. Each " +
+        "list is generated from the same registry that ENFORCES it — the handler " +
+        "table, the trigger-type constants, the validator's own step-type set, " +
+        "the schedule-rule specs — so the answer and the enforcement cannot " +
+        "disagree. That is why neither this connector's guide nor its tool " +
+        "descriptions name any of these values.", {
+        types: z
+            .array(z.string())
+            .optional()
+            .describe('Command types to return in full, e.g. ["add_step", "add_edge"]. ' +
+            "Omit for the index. A name this deploy does not have comes back " +
+            "under `unknownTypes` rather than as an error."),
+    }, async ({ types }) => guard(async () => jsonResult(projectCatalog(await client.get("/api/v1/workflows/operations"), types))));
+}
+//# sourceMappingURL=authoringSpec.js.map

package/dist/tools/authoringSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoringSpec.js","sourceRoot":"","sources":["../../src/tools/authoringSpec.ts"],"names":[],"mappings":"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"}

package/dist/tools/company.d.ts

@@ -3,8 +3,11 @@
  * streams, org structure). Unlike the other authored entities it is a
  * SINGLETON: one per tenant, addressed at `/api/v1/company` with no id, so it
  * has no list / create / delete / restore / discard routes. It is
- * version-controlled like the memory entities, and edited as a whole document
- * (a full-document PUT under optimistic locking), not field-by-field.
+ * version-controlled like the memory entities, and editable two ways: command
+ * mutations (`apply_company_mutation`, preferred — the backend validates each
+ * and threads the version) or a whole-document PUT (`update_company`). Workflow
+ * has had both for a long time; company was whole-document-only here even
+ * though `POST /api/v1/company/mutations` existed.
  *
  * Publishing: company is currently NOT a publish-approval entity type on the
  * backend, so there is no request_publish_company — a company change is

package/dist/tools/company.js

@@ -3,8 +3,11 @@
  * streams, org structure). Unlike the other authored entities it is a
  * SINGLETON: one per tenant, addressed at `/api/v1/company` with no id, so it
  * has no list / create / delete / restore / discard routes. It is
- * version-controlled like the memory entities, and edited as a whole document
- * (a full-document PUT under optimistic locking), not field-by-field.
+ * version-controlled like the memory entities, and editable two ways: command
+ * mutations (`apply_company_mutation`, preferred — the backend validates each
+ * and threads the version) or a whole-document PUT (`update_company`). Workflow
+ * has had both for a long time; company was whole-document-only here even
+ * though `POST /api/v1/company/mutations` existed.
  *
  * Publishing: company is currently NOT a publish-approval entity type on the
  * backend, so there is no request_publish_company — a company change is
@@ -17,6 +20,29 @@ export function registerCompanyTools(server, client) {
     server.tool("read_company", "Read this tenant's company document (its current draft and version). There " +
         "is one company per tenant — no id. Read it before you update, to get the " +
         "version for optimistic locking.", {}, async () => guard(async () => jsonResult(await client.get("/api/v1/company"))));
+    server.tool("create_company_from_template", "Create this tenant's company document from a template — how a tenant that " +
+        "has none gets one. Pick the template with list_templates({ kind: " +
+        "\"all\" }) and read it with read_template first: the template decides the " +
+        "value stream, the stages and the capabilities that everything else in " +
+        "the tenant will hang off. " +
+        "\n\nThis is a WRITE on the singleton every workflow refers to. Run " +
+        "read_company first — if one already exists, instantiating over it is " +
+        "almost never what you meant, and update_company or " +
+        "apply_company_mutation is. Like every other write here it produces a " +
+        "DRAFT; a human publishes it.", {
+        templateId: z.string().describe("The template's id, from list_templates."),
+        companyName: z
+            .string()
+            .optional()
+            .describe("Name for the new company. Omit to take the template's own."),
+        confirm: z
+            .literal(true)
+            .describe("Must be true. Acknowledges this creates the tenant's company " +
+            "document from a template — check read_company first."),
+    }, async ({ templateId, companyName }) => guard(async () => jsonResult(await client.post("/api/v1/company/from-template", {
+        templateId,
+        ...(companyName ? { companyName } : {}),
+    }))));
     server.tool("read_company_published", "Read the LIVE published company document — what the runtime uses, as opposed " +
         "to the draft read_company returns. Diff the two to see what a publish would change.", {}, async () => guard(async () => jsonResult(await client.get("/api/v1/company/published"))));
     server.tool("update_company", "Save the company draft as a WHOLE document (full-document PUT, not a field " +
@@ -52,6 +78,57 @@ export function registerCompanyTools(server, client) {
     }, async ({ versionId, expectedVersion }) => guard(async () => jsonResult(await client.post(`/api/v1/company/versions/${versionId}/restore`, {
         expectedVersion,
     }))));
+    server.tool("create_company_major_version", "Cut a new NAMED major version of the company document — \"Save As\" for " +
+        "the current draft, so a milestone is findable by name instead of by " +
+        "hunting through checkpoints. Takes no id (singleton). This does NOT " +
+        "publish: what is live stays live until a human approves a " +
+        "request_publish_company.", {
+        name: z
+            .string()
+            .min(1)
+            .max(255)
+            .describe('What to call this release, e.g. "Q3 operating model".'),
+        description: z
+            .string()
+            .optional()
+            .describe("A longer note on what this version represents."),
+    }, async ({ name, description }) => guard(async () => jsonResult(await client.post("/api/v1/company/versions", {
+        name,
+        ...(description ? { description } : {}),
+    }))));
+    server.tool("ensure_company_major_version", "Make sure the company document has a working draft major version, " +
+        "creating an unnamed one if it has none. IDEMPOTENT — safe to call before " +
+        "a run of edits; when one already exists nothing changes. Returns the " +
+        "draft's major version number and name.", {}, async () => guard(async () => jsonResult(await client.post("/api/v1/company/versions/ensure"))));
+    server.tool("apply_company_mutation", "Apply ONE structural command to the company document — the validated, " +
+        "version-safe way to change its layers, value streams, stages and " +
+        "capabilities, and to link workflows to them. Prefer this over " +
+        "update_company: that route is a whole-document PUT, which is the same " +
+        "reason apply_workflow_mutations is preferred for a workflow. Read the " +
+        "company first for its version. " +
+        "\n\nOne command per call — this route has no batch form, unlike the " +
+        "workflow one. Apply a sequence yourself, using the version each response " +
+        "returns as the next call's expectedVersion. " +
+        "\n\nWHICH COMMANDS EXIST is not listed here and this connector keeps no " +
+        "copy: unlike workflows, company has no catalogue route to read, so a " +
+        "wrong `type` is a 422 that names every value the route accepts. Read " +
+        "that error rather than guessing twice.", {
+        type: z
+            .string()
+            .describe("The command name. A value this deploy does not accept comes back as " +
+            "a 422 listing the ones it does."),
+        payload: z
+            .record(z.unknown())
+            .describe("The command's arguments (camelCase keys)."),
+        expectedVersion: z
+            .number()
+            .int()
+            .describe("The version you last read — rejected with 409 if stale."),
+    }, async ({ type, payload, expectedVersion }) => guard(async () => jsonResult(await client.post("/api/v1/company/mutations", {
+        type,
+        payload,
+        expectedVersion,
+    }))));
     server.tool("name_company_major_version", "Give one of the company document's major versions a name — label a release " +
         "so it is easy to find in history. Targets a MAJOR version by its integer " +
         "number (from list_company_versions), not a checkpoint or a versionId. Like " +

package/dist/tools/company.js.map

@@ -1 +1 @@
-{"version":3,"file":"company.js","sourceRoot":"","sources":["../../src/tools/company.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"company.js","sourceRoot":"","sources":["../../src/tools/company.ts"],"names":[],"mappings":"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"}

package/dist/tools/conventions.d.ts

@@ -12,6 +12,22 @@
  * and the enums quoted below to a vendored snapshot of that schema, so a drift
  * between this prose and the backend fails CI rather than misleading an agent.
  * Keep enum lists in this doc in step with what that test asserts.
+ *
+ * BETTER STILL, DO NOT QUOTE A LIST AT ALL. Four vocabularies used to live here
+ * and every one of them drifted: the mutation commands (#32/#44), and then the
+ * step types, trigger types and schedule-rule shapes — this guide named nine
+ * step types where seven validate. All four are now read from
+ * `get_workflow_authoring_spec`, generated by the backend from the registries
+ * that ENFORCE them, and this document states none of those LISTS. A pinned
+ * list fails CI when it drifts; a list you never wrote cannot. When you are
+ * about to write out a set of accepted values here, point at the spec instead —
+ * `test/conformance.test.ts` asserts the absence.
+ *
+ * Naming ONE value to state behaviour is a different thing and stays: that
+ * `typeId: "subprocess-invocation"` is what makes a workflow callable is not
+ * something the catalogue can say — it can only say the id exists. The line is
+ * the one #44 drew: a mention is guidance, an enumeration is a claim about what
+ * exists, and it is the claim that goes stale.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function registerConventions(server: McpServer): void;