@axonity-ai/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axonity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @axonity-ai/mcp — Axonity Flow MCP connector
+
+A local [Model Context Protocol](https://modelcontextprotocol.io) server that lets
+an external agent (e.g. **Claude Code** on your laptop) read, draft, and update
+**workflows, agents, tools, skills, policies and reference docs** in your Axonity
+tenant — the same verbs the internal Builder team has, minus direct publish.
+
+It runs on your machine and talks to Axonity **only over the public REST API**,
+authenticated with a per-tenant **service token**. The backend re-enforces
+tenant + scope on every call, so the connector is not a trust boundary.
+
+## Setup
+
+1. **Mint a service token** in Axonity → **Settings → API tokens**. Copy it once
+   (it starts with `axs_`); you won't see it again. Use a **read-only** token if
+   you only want the agent to read.
+2. **Add the connector to Claude Code:**
+
+   ```bash
+   claude mcp add axonity \
+     --env AXONITY_TOKEN=axs_your_token_here \
+     --env AXONITY_API_URL=https://app.axonity.ai \
+     -- npx -y @axonity-ai/mcp
+   ```
+
+   `AXONITY_API_URL` is optional (defaults to the Axonity SaaS URL); set it if you
+   self-host.
+
+3. Ask Claude Code things like *"list my Axonity workflows"*, *"create a workflow
+   called Onboarding"*, or *"add a step to workflow X"*.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `axonity_conventions` | The authoring rules (drafts vs live, optimistic locking, per-entity fields). Read this first. |
+Each entity — **workflow, agent, tool, skill, policy, reference_doc** — gets the
+same five verbs:
+
+| Tool (per `<entity>`) | What it does |
+|------|--------------|
+| `list_<entity>s` | List the tenant's entities. |
+| `read_<entity>` | Read one by id (incl. its version — read before you update). |
+| `create_<entity>` | Create a new **draft**. |
+| `update_<entity>` | Update a draft (carries `expectedVersion`; 409 on a stale write). |
+| `request_publish_<entity>` | Ask for a draft to be published — creates a pending approval; never publishes. |
+
+Plus `apply_workflow_mutations` for structural workflow edits (add steps, connect
+edges) via mutation commands.
+
+Also:
+
+- **Personas** (agent-scoped, 1:1 with an agent): `read_agent_persona`,
+  `create_agent_persona`, `update_persona`.
+- **Connectors** (a tool of type `connector`): `create_connector`,
+  `update_connector` — `authConfig` must be placeholders only; a human fills real
+  secrets in Axonity.
+- **Attach memory to a target**: `attach_skill_to_agent`,
+  `attach_skill_to_workflow`, `attach_policy_to_agent`, `attach_reference_to_agent`.
+
+## Publishing
+
+The connector **never publishes directly**. `request_publish_*` creates a
+**pending approval** in Axonity; an admin approves it there, and only then does
+the draft go live. Rejecting it changes nothing.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build   # emits dist/
+```

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Thin HTTP client for the Axonity REST API.
+ *
+ * The connector talks to Axonity ONLY over the public REST API — no direct DB,
+ * no backend internals. Every request carries the service token as a bearer;
+ * the backend re-enforces tenant + scope, so this client is not a trust
+ * boundary. Failures are mapped to typed errors (see errors.ts).
+ */
+import type { AxonityConfig } from "./config.js";
+export type Json = Record<string, unknown>;
+export declare class AxonityClient {
+    private readonly config;
+    constructor(config: AxonityConfig);
+    private url;
+    /**
+     * Issue a request and return the parsed JSON body. Non-2xx responses are
+     * thrown as typed errors; a 204/empty body resolves to `undefined`.
+     */
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,70 @@
+/**
+ * Thin HTTP client for the Axonity REST API.
+ *
+ * The connector talks to Axonity ONLY over the public REST API — no direct DB,
+ * no backend internals. Every request carries the service token as a bearer;
+ * the backend re-enforces tenant + scope, so this client is not a trust
+ * boundary. Failures are mapped to typed errors (see errors.ts).
+ */
+import { AxonityApiError, errorForStatus } from "./errors.js";
+export class AxonityClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    url(path) {
+        return `${this.config.apiUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    }
+    /**
+     * Issue a request and return the parsed JSON body. Non-2xx responses are
+     * thrown as typed errors; a 204/empty body resolves to `undefined`.
+     */
+    async request(method, path, body) {
+        let resp;
+        try {
+            resp = await fetch(this.url(path), {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.config.token}`,
+                    ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (cause) {
+            // Network-level failure (DNS, connection refused, TLS) — not an HTTP status.
+            throw new AxonityApiError(`Could not reach the Axonity API at ${this.config.apiUrl}. ` +
+                "Check AXONITY_API_URL and your network.", 0, cause instanceof Error ? cause.message : String(cause));
+        }
+        const text = await resp.text();
+        const parsed = text ? safeJson(text) : undefined;
+        if (!resp.ok) {
+            const detail = parsed && typeof parsed === "object" && "detail" in parsed
+                ? parsed.detail
+                : parsed;
+            throw errorForStatus(resp.status, detail);
+        }
+        return parsed;
+    }
+    get(path) {
+        return this.request("GET", path);
+    }
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    put(path, body) {
+        return this.request("PUT", path, body);
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI9D,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAE9C,GAAG,CAAC,IAAY;QACtB,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;IAC5E,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CACX,MAAc,EACd,IAAY,EACZ,IAAc;QAEd,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;gBACjC,MAAM;gBACN,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;oBAC5C,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACtE;gBACD,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;aAC5D,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,6EAA6E;YAC7E,MAAM,IAAI,eAAe,CACvB,sCAAsC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI;gBAC1D,yCAAyC,EAC3C,CAAC,EACD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEjD,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,MAAM,GACV,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,QAAQ,IAAI,MAAM;gBACxD,CAAC,CAAE,MAA8B,CAAC,MAAM;gBACxC,CAAC,CAAC,MAAM,CAAC;YACb,MAAM,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAW,CAAC;IACrB,CAAC;IAED,GAAG,CAAc,IAAY;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,CAAc,IAAY,EAAE,IAAc;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,GAAG,CAAc,IAAY,EAAE,IAAc;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAc,IAAY,EAAE,IAAc;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAI,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Runtime configuration for the Axonity MCP connector.
+ *
+ * The connector authenticates to Axonity with a per-tenant SERVICE TOKEN
+ * (minted in Axonity → Settings → API tokens). The token fixes the tenant; the
+ * connector never chooses one. Values come from the environment so the token
+ * never lands in a config file the agent can read.
+ */
+export interface AxonityConfig {
+    /** Base URL of the Axonity API, e.g. https://app.axonity.ai (no trailing slash). */
+    apiUrl: string;
+    /** The service token (`axs_…`) presented as a bearer on every request. */
+    token: string;
+}
+/**
+ * Read configuration from the environment.
+ *
+ * - `AXONITY_TOKEN` (required): the `axs_…` service token.
+ * - `AXONITY_API_URL` (optional): defaults to the Axonity SaaS URL.
+ *
+ * Throws if the token is missing so the process fails fast at startup with a
+ * clear message rather than 401-ing on the first tool call.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): AxonityConfig;

package/dist/config.js

@@ -0,0 +1,28 @@
+/**
+ * Runtime configuration for the Axonity MCP connector.
+ *
+ * The connector authenticates to Axonity with a per-tenant SERVICE TOKEN
+ * (minted in Axonity → Settings → API tokens). The token fixes the tenant; the
+ * connector never chooses one. Values come from the environment so the token
+ * never lands in a config file the agent can read.
+ */
+const DEFAULT_API_URL = "https://app.axonity.ai";
+/**
+ * Read configuration from the environment.
+ *
+ * - `AXONITY_TOKEN` (required): the `axs_…` service token.
+ * - `AXONITY_API_URL` (optional): defaults to the Axonity SaaS URL.
+ *
+ * Throws if the token is missing so the process fails fast at startup with a
+ * clear message rather than 401-ing on the first tool call.
+ */
+export function loadConfig(env = process.env) {
+    const token = env.AXONITY_TOKEN?.trim();
+    if (!token) {
+        throw new Error("AXONITY_TOKEN is not set. Mint a service token in Axonity " +
+            "(Settings → API tokens) and pass it as the AXONITY_TOKEN environment variable.");
+    }
+    const apiUrl = (env.AXONITY_API_URL?.trim() || DEFAULT_API_URL).replace(/\/+$/, "");
+    return { apiUrl, token };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC;IACxC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,4DAA4D;YAC1D,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,eAAe,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpF,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Typed errors for the Axonity MCP connector.
+ *
+ * Every REST failure is mapped to one of these so tool handlers can return a
+ * clean, actionable message to the agent — never a raw stack trace or an
+ * opaque status code.
+ */
+export declare class AxonityApiError extends Error {
+    /** HTTP status that produced this error. */
+    readonly status: number;
+    /** Server-provided detail, when present. */
+    readonly detail?: unknown | undefined;
+    constructor(message: string, 
+    /** HTTP status that produced this error. */
+    status: number, 
+    /** Server-provided detail, when present. */
+    detail?: unknown | undefined);
+}
+/** 409 — the entity was modified since the agent read it. Re-read and retry. */
+export declare class VersionConflictError extends AxonityApiError {
+    constructor(detail?: unknown);
+}
+/** 401 — the service token is missing, unknown, or revoked. */
+export declare class AuthError extends AxonityApiError {
+    constructor(detail?: unknown);
+}
+/** 403 — the token lacks the scope for this action (e.g. read-only on a write). */
+export declare class ForbiddenError extends AxonityApiError {
+    constructor(detail?: unknown);
+}
+/**
+ * Map an HTTP response to the right error type. `detail` is the parsed body
+ * (FastAPI returns `{ detail: … }`), passed through for context.
+ */
+export declare function errorForStatus(status: number, detail?: unknown): AxonityApiError;

package/dist/errors.js

@@ -0,0 +1,62 @@
+/**
+ * Typed errors for the Axonity MCP connector.
+ *
+ * Every REST failure is mapped to one of these so tool handlers can return a
+ * clean, actionable message to the agent — never a raw stack trace or an
+ * opaque status code.
+ */
+export class AxonityApiError extends Error {
+    status;
+    detail;
+    constructor(message, 
+    /** HTTP status that produced this error. */
+    status, 
+    /** Server-provided detail, when present. */
+    detail) {
+        super(message);
+        this.status = status;
+        this.detail = detail;
+        this.name = "AxonityApiError";
+    }
+}
+/** 409 — the entity was modified since the agent read it. Re-read and retry. */
+export class VersionConflictError extends AxonityApiError {
+    constructor(detail) {
+        super("Version conflict: the entity changed since you read it. Read it again to " +
+            "get the current version, then re-apply your change.", 409, detail);
+        this.name = "VersionConflictError";
+    }
+}
+/** 401 — the service token is missing, unknown, or revoked. */
+export class AuthError extends AxonityApiError {
+    constructor(detail) {
+        super("Authentication failed (401): the service token is missing, invalid, or revoked. " +
+            "Check AXONITY_TOKEN, or mint a new token in Axonity → Settings → API tokens.", 401, detail);
+        this.name = "AuthError";
+    }
+}
+/** 403 — the token lacks the scope for this action (e.g. read-only on a write). */
+export class ForbiddenError extends AxonityApiError {
+    constructor(detail) {
+        super("Forbidden (403): this service token is not allowed to perform that action. " +
+            "A read-only token cannot create, update, or request-publish.", 403, detail);
+        this.name = "ForbiddenError";
+    }
+}
+/**
+ * Map an HTTP response to the right error type. `detail` is the parsed body
+ * (FastAPI returns `{ detail: … }`), passed through for context.
+ */
+export function errorForStatus(status, detail) {
+    switch (status) {
+        case 401:
+            return new AuthError(detail);
+        case 403:
+            return new ForbiddenError(detail);
+        case 409:
+            return new VersionConflictError(detail);
+        default:
+            return new AxonityApiError(`Axonity API request failed (${status}).`, status, detail);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAI7B;IAEA;IALX,YACE,OAAe;IACf,4CAA4C;IACnC,MAAc;IACvB,4CAA4C;IACnC,MAAgB;QAEzB,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,WAAM,GAAN,MAAM,CAAQ;QAEd,WAAM,GAAN,MAAM,CAAU;QAGzB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,OAAO,oBAAqB,SAAQ,eAAe;IACvD,YAAY,MAAgB;QAC1B,KAAK,CACH,2EAA2E;YACzE,qDAAqD,EACvD,GAAG,EACH,MAAM,CACP,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,SAAU,SAAQ,eAAe;IAC5C,YAAY,MAAgB;QAC1B,KAAK,CACH,kFAAkF;YAChF,8EAA8E,EAChF,GAAG,EACH,MAAM,CACP,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,OAAO,cAAe,SAAQ,eAAe;IACjD,YAAY,MAAgB;QAC1B,KAAK,CACH,6EAA6E;YAC3E,8DAA8D,EAChE,GAAG,EACH,MAAM,CACP,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,MAAgB;IAC7D,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,GAAG;YACN,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;QAC/B,KAAK,GAAG;YACN,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QACpC,KAAK,GAAG;YACN,OAAO,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC1C;YACE,OAAO,IAAI,eAAe,CACxB,+BAA+B,MAAM,IAAI,EACzC,MAAM,EACN,MAAM,CACP,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Axonity Flow — MCP connector (epic #652 / C4).
+ *
+ * A local stdio MCP server that lets an external agent (e.g. Claude Code) read,
+ * draft, and update workflows, agents and tools in an Axonity tenant. Add it to
+ * your client with:
+ *
+ *   claude mcp add axonity -- npx -y @axonity-ai/mcp
+ *
+ * with AXONITY_TOKEN (a service token minted in Axonity → Settings → API tokens)
+ * and, if self-hosting, AXONITY_API_URL in the environment.
+ *
+ * It talks to Axonity ONLY over the public REST API; the backend re-enforces
+ * tenant + scope on every call. Publishing is human-approved and lands in a
+ * later slice (C3) — this connector never publishes directly.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AxonityClient } from "./client.js";
+export declare function buildServer(client: AxonityClient): McpServer;

package/dist/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Axonity Flow — MCP connector (epic #652 / C4).
+ *
+ * A local stdio MCP server that lets an external agent (e.g. Claude Code) read,
+ * draft, and update workflows, agents and tools in an Axonity tenant. Add it to
+ * your client with:
+ *
+ *   claude mcp add axonity -- npx -y @axonity-ai/mcp
+ *
+ * with AXONITY_TOKEN (a service token minted in Axonity → Settings → API tokens)
+ * and, if self-hosting, AXONITY_API_URL in the environment.
+ *
+ * It talks to Axonity ONLY over the public REST API; the backend re-enforces
+ * tenant + scope on every call. Publishing is human-approved and lands in a
+ * later slice (C3) — this connector never publishes directly.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AxonityClient } from "./client.js";
+import { loadConfig } from "./config.js";
+import { registerConventions } from "./tools/conventions.js";
+import { registerAttachTools, registerConnectorTools, registerPersonaTools, } from "./tools/extras.js";
+import { registerEntityTools } from "./tools/register.js";
+import { registerWorkflowMutations } from "./tools/workflowMutations.js";
+/**
+ * The entities the connector covers. Core entities (C4) plus memory
+ * entities (C5) — skills, policies, reference docs — which have the same
+ * draft→publish lifecycle via #443's unified versioning.
+ */
+const ENTITIES = [
+    {
+        singular: "workflow",
+        basePath: "/api/v1/workflows",
+        updateMethod: "PATCH",
+        label: "workflows (business processes)",
+    },
+    {
+        singular: "agent",
+        basePath: "/api/v1/agents",
+        updateMethod: "PUT",
+        label: "agents",
+    },
+    {
+        singular: "tool",
+        basePath: "/api/v1/tools",
+        updateMethod: "PUT",
+        label: "tools (functions, connectors, validators, evaluators)",
+    },
+    {
+        singular: "skill",
+        basePath: "/api/v1/skills",
+        updateMethod: "PUT",
+        label: "skills (reusable know-how for agents)",
+    },
+    {
+        singular: "policy",
+        basePath: "/api/v1/policies",
+        updateMethod: "PUT",
+        label: "policies (rules and guardrails for agents)",
+    },
+    {
+        singular: "reference_doc",
+        basePath: "/api/v1/reference-docs",
+        updateMethod: "PUT",
+        label: "reference docs (background knowledge for agents)",
+    },
+];
+export function buildServer(client) {
+    const server = new McpServer({ name: "axonity", version: "0.1.0" });
+    registerConventions(server);
+    for (const def of ENTITIES) {
+        registerEntityTools(server, client, def);
+    }
+    registerWorkflowMutations(server, client);
+    registerPersonaTools(server, client);
+    registerConnectorTools(server, client);
+    registerAttachTools(server, client);
+    return server;
+}
+async function main() {
+    const config = loadConfig();
+    const client = new AxonityClient(config);
+    const server = buildServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr — stdout is the MCP channel and must stay clean.
+    console.error(`Axonity MCP connector ready (${config.apiUrl}).`);
+}
+// Only run when executed directly (not when imported by tests).
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((err) => {
+        console.error("Axonity MCP connector failed to start:", err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/tools/conventions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `axonity_conventions` guidance tool.
+ *
+ * An external agent needs the same authoring rules the internal Builder team
+ * carries, or its drafts will be low quality. This is a static conventions
+ * reference for the MLP; a single-sourced `discover_<entity>_operations` tool
+ * backed by the platform's own discovery contract is a planned refinement
+ * (epic #652 C4 — "prefer a thin backend read endpoint").
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerConventions(server: McpServer): void;

package/dist/tools/conventions.js

@@ -0,0 +1,52 @@
+/**
+ * The `axonity_conventions` guidance tool.
+ *
+ * An external agent needs the same authoring rules the internal Builder team
+ * carries, or its drafts will be low quality. This is a static conventions
+ * reference for the MLP; a single-sourced `discover_<entity>_operations` tool
+ * backed by the platform's own discovery contract is a planned refinement
+ * (epic #652 C4 — "prefer a thin backend read endpoint").
+ */
+const CONVENTIONS = `# Authoring conventions for Axonity entities
+
+Read this before creating or updating anything.
+
+## Drafts, not live
+- \`create_*\` and \`update_*\` produce a DRAFT. The live runtime is unaffected
+  until a human publishes it in Axonity. You cannot publish directly.
+- \`request_publish_*\` does NOT publish — it creates a pending approval a human
+  approves in Axonity. Use it when a draft is ready; then tell the user to
+  approve it in their Axonity approvals inbox.
+
+## Optimistic locking (always read-then-write)
+- Before \`update_*\`, call \`read_*\` and use the \`version\` you get as
+  \`expectedVersion\`. If the update returns a 409 conflict, someone else changed
+  it — read again and re-apply your change onto the new version.
+
+## Field shape
+- All fields are camelCase JSON (e.g. \`capabilityTier\`, not \`capability_tier\`).
+- \`update_*\` is a partial change for agents/tools and a partial patch for
+  workflows: send only the fields you are changing.
+- The backend validates fields; a 422 error tells you exactly which field is wrong.
+
+## Per entity
+- **workflow**: \`create_workflow\` makes a stub (name, description). Build its
+  steps/edges with \`apply_workflow_mutations\` (a list of mutation commands) —
+  the workflow document is edited through commands, never by replacing it wholesale.
+- **agent**: fields include name, avatar, capabilityTier, creativityTier,
+  learningMode, permissions, delegationTargetIds, toolIds, systemToolIds, status.
+- **tool**: fields include name, description, type
+  ("function" | "connector" | "validator" | "evaluator"), inputSchema,
+  outputSchema, implementation, authConfig, status. For a connector, set
+  \`type: "connector"\`; NEVER put real credentials in authConfig — use
+  placeholders and let a human fill secrets in the Axonity tool editor.
+
+## Tenant
+- Your token fixes the tenant. You cannot act across tenants; never send a
+  tenant id in a body.
+`;
+export function registerConventions(server) {
+    server.tool("axonity_conventions", "Read the authoring conventions (drafts vs live, optimistic locking, field " +
+        "shapes per entity). Call this before creating or updating entities.", {}, async () => ({ content: [{ type: "text", text: CONVENTIONS }] }));
+}
+//# sourceMappingURL=conventions.js.map

package/dist/tools/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/tools/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCnB,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,4EAA4E;QAC1E,qEAAqE,EACvE,EAAE,EACF,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAC1E,CAAC;AACJ,CAAC"}

package/dist/tools/extras.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Secondary MCP tools (epic #652 C5): personas (agent-scoped), connectors
+ * (a tool subtype), and attaching memory to a target.
+ *
+ * These use routes with shapes that don't fit the generic entity registrar:
+ * personas are 1:1 with an agent (no standalone list), connectors are a tool
+ * with `type: "connector"` and MUST NOT carry real credentials, and attach is a
+ * path-only link.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AxonityClient } from "../client.js";
+export declare function registerPersonaTools(server: McpServer, client: AxonityClient): void;
+export declare function registerConnectorTools(server: McpServer, client: AxonityClient): void;
+export declare function registerAttachTools(server: McpServer, client: AxonityClient): void;

package/dist/tools/extras.js

@@ -0,0 +1,81 @@
+/**
+ * Secondary MCP tools (epic #652 C5): personas (agent-scoped), connectors
+ * (a tool subtype), and attaching memory to a target.
+ *
+ * These use routes with shapes that don't fit the generic entity registrar:
+ * personas are 1:1 with an agent (no standalone list), connectors are a tool
+ * with `type: "connector"` and MUST NOT carry real credentials, and attach is a
+ * path-only link.
+ */
+import { z } from "zod";
+import { guard, jsonResult } from "./result.js";
+/** A value is a safe placeholder if it's empty or a `{{ … }}` template. */
+function isPlaceholder(value) {
+    if (value === "" || value === null || value === undefined)
+        return true;
+    return typeof value === "string" && /^\s*\{\{.*\}\}\s*$/.test(value);
+}
+export function registerPersonaTools(server, client) {
+    server.tool("read_agent_persona", "Read an agent's persona (voice/character). A persona is 1:1 with an agent — " +
+        "there is no standalone persona list.", { agentId: z.string().describe("The agent's id.") }, async ({ agentId }) => guard(async () => jsonResult(await client.get(`/api/v1/agents/${agentId}/persona`))));
+    server.tool("create_agent_persona", "Create an agent's persona. Pass name, characterText and optional status.", {
+        agentId: z.string().describe("The agent's id."),
+        fields: z
+            .record(z.unknown())
+            .describe('Persona fields, e.g. { "name": "…", "characterText": "…" }.'),
+    }, async ({ agentId, fields }) => guard(async () => jsonResult(await client.post(`/api/v1/agents/${agentId}/persona`, fields))));
+    server.tool("update_persona", "Update a persona by its id (read the agent's persona first for its version).", {
+        personaId: z.string().describe("The persona's id."),
+        expectedVersion: z
+            .number()
+            .int()
+            .describe("The version you last read — 409 if stale."),
+        fields: z.record(z.unknown()).describe("The fields to change (camelCase)."),
+    }, async ({ personaId, expectedVersion, fields }) => guard(async () => jsonResult(await client.put(`/api/v1/personas/${personaId}`, {
+        expectedVersion,
+        ...fields,
+    }))));
+}
+export function registerConnectorTools(server, client) {
+    const authGuard = (fields) => {
+        const authConfig = fields.authConfig;
+        if (authConfig && !Object.values(authConfig).every(isPlaceholder)) {
+            throw new Error("authConfig must contain only placeholders (empty or {{ … }}). Never put " +
+                "real credentials in a connector — a human fills secrets in the Axonity " +
+                "tool editor.");
+        }
+    };
+    server.tool("create_connector", "Create a connector draft (a tool of type 'connector'). Do NOT put real " +
+        "credentials in authConfig — use placeholders; a human fills secrets in Axonity.", {
+        fields: z
+            .record(z.unknown())
+            .describe("Connector fields (name, description, implementation, authConfig)."),
+    }, async ({ fields }) => guard(async () => {
+        authGuard(fields);
+        return jsonResult(await client.post("/api/v1/tools", { type: "connector", ...fields }));
+    }));
+    server.tool("update_connector", "Update a connector draft (a tool of type 'connector'). Read it first for its " +
+        "version; keep authConfig as placeholders only.", {
+        id: z.string().describe("The connector (tool) id."),
+        expectedVersion: z.number().int().describe("Version last read — 409 if stale."),
+        fields: z.record(z.unknown()).describe("Fields to change (camelCase)."),
+    }, async ({ id, expectedVersion, fields }) => guard(async () => {
+        authGuard(fields);
+        return jsonResult(await client.put(`/api/v1/tools/${id}`, {
+            expectedVersion,
+            type: "connector",
+            ...fields,
+        }));
+    }));
+}
+export function registerAttachTools(server, client) {
+    const attach = (name, description, path, firstArg, secondArg) => server.tool(name, description, {
+        [firstArg]: z.string(),
+        [secondArg]: z.string(),
+    }, async (args) => guard(async () => jsonResult(await client.post(path(args[firstArg], args[secondArg])))));
+    attach("attach_skill_to_agent", "Scope a skill to an agent so the agent uses it.", (agentId, skillId) => `/api/v1/agents/${agentId}/skills-v2/${skillId}`, "agentId", "skillId");
+    attach("attach_skill_to_workflow", "Scope a skill to a workflow.", (workflowId, skillId) => `/api/v1/workflows/${workflowId}/skills-v2/${skillId}`, "workflowId", "skillId");
+    attach("attach_policy_to_agent", "Scope a policy to an agent.", (agentId, policyId) => `/api/v1/agents/${agentId}/policies/${policyId}`, "agentId", "policyId");
+    attach("attach_reference_to_agent", "Scope a reference doc to an agent.", (agentId, refId) => `/api/v1/agents/${agentId}/reference-docs/${refId}`, "agentId", "refId");
+}
+//# sourceMappingURL=extras.js.map

package/dist/tools/extras.js.map

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

package/dist/tools/register.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Registers the read/draft/update MCP tools for one Axonity entity type.
+ *
+ * Every entity (workflow, agent, tool) gets the same verbs the internal
+ * Builder team has, minus direct publish:
+ *   list_<entity>   — GET  /api/v1/<entity>s
+ *   read_<entity>   — GET  /api/v1/<entity>s/{id}
+ *   create_<entity> — POST /api/v1/<entity>s              (a new draft)
+ *   update_<entity> — PUT|PATCH /api/v1/<entity>s/{id}    (read-then-write)
+ *
+ * The connector stays thin: entity fields pass through as JSON and the backend
+ * validates them (422 surfaces the field detail). Updates carry `expectedVersion`
+ * so a stale write 409s rather than clobbering — the agent re-reads and retries.
+ *
+ * `request_publish_*` never publishes — it creates a pending approval a human
+ * decides in Axonity (epic #652 C3).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AxonityClient } from "../client.js";
+export interface EntityDef {
+    /** Singular tool noun, e.g. "workflow". */
+    singular: string;
+    /** REST collection path, e.g. "/api/v1/workflows". */
+    basePath: string;
+    /** HTTP verb the update route uses (workflows PATCH; agents/tools PUT). */
+    updateMethod: "PUT" | "PATCH";
+    /** One-line human description of the entity, for the tool docs. */
+    label: string;
+}
+export declare function registerEntityTools(server: McpServer, client: AxonityClient, def: EntityDef): void;

package/dist/tools/register.js

@@ -0,0 +1,66 @@
+/**
+ * Registers the read/draft/update MCP tools for one Axonity entity type.
+ *
+ * Every entity (workflow, agent, tool) gets the same verbs the internal
+ * Builder team has, minus direct publish:
+ *   list_<entity>   — GET  /api/v1/<entity>s
+ *   read_<entity>   — GET  /api/v1/<entity>s/{id}
+ *   create_<entity> — POST /api/v1/<entity>s              (a new draft)
+ *   update_<entity> — PUT|PATCH /api/v1/<entity>s/{id}    (read-then-write)
+ *
+ * The connector stays thin: entity fields pass through as JSON and the backend
+ * validates them (422 surfaces the field detail). Updates carry `expectedVersion`
+ * so a stale write 409s rather than clobbering — the agent re-reads and retries.
+ *
+ * `request_publish_*` never publishes — it creates a pending approval a human
+ * decides in Axonity (epic #652 C3).
+ */
+import { z } from "zod";
+import { guard, jsonResult } from "./result.js";
+export function registerEntityTools(server, client, def) {
+    const { singular, basePath, updateMethod, label } = def;
+    server.tool(`list_${singular}s`, `List all ${label} in your Axonity tenant (id, name, status, version).`, {}, async () => guard(async () => jsonResult(await client.get(basePath))));
+    server.tool(`read_${singular}`, `Read one ${singular} by id, including its current draft and version. ` +
+        `Read before you update — you need the current version.`, { id: z.string().describe(`The ${singular}'s id.`) }, async ({ id }) => guard(async () => jsonResult(await client.get(`${basePath}/${id}`))));
+    server.tool(`create_${singular}`, `Create a new ${singular} draft. Pass the entity's fields (camelCase) in ` +
+        `\`fields\`; the backend validates them. Returns the created ${singular} ` +
+        `with its id and version.`, {
+        fields: z
+            .record(z.unknown())
+            .describe(`The ${singular}'s fields as a JSON object (camelCase keys), e.g. ` +
+            `{ "name": "…", "description": "…" }.`),
+    }, async ({ fields }) => guard(async () => jsonResult(await client.post(basePath, fields))));
+    server.tool(`update_${singular}`, `Update a ${singular} draft. Read it first to get \`expectedVersion\`; on a ` +
+        `409 conflict, read again and retry. Pass only the fields you are ` +
+        `changing (camelCase) in \`fields\`.`, {
+        id: z.string().describe(`The ${singular}'s id.`),
+        expectedVersion: z
+            .number()
+            .int()
+            .describe("The version you last read — rejected with 409 if stale."),
+        fields: z
+            .record(z.unknown())
+            .describe(`The fields to change, as a JSON object (camelCase keys).`),
+    }, async ({ id, expectedVersion, fields }) => guard(async () => {
+        const body = { expectedVersion, ...fields };
+        const path = `${basePath}/${id}`;
+        const data = updateMethod === "PUT"
+            ? await client.put(path, body)
+            : await client.patch(path, body);
+        return jsonResult(data);
+    }));
+    server.tool(`request_publish_${singular}`, `Request that a ${singular} be published. This does NOT publish it — it ` +
+        `creates a pending approval a human approves in Axonity. Returns the ` +
+        `pending approval (with its readiness).`, {
+        id: z.string().describe(`The ${singular}'s id.`),
+        changeSummary: z
+            .string()
+            .optional()
+            .describe("A short note for the approver on what changed and why."),
+    }, async ({ id, changeSummary }) => guard(async () => jsonResult(await client.post("/api/v1/publish-approvals", {
+        entityType: singular,
+        entityId: id,
+        ...(changeSummary ? { changeSummary } : {}),
+    }))));
+}
+//# sourceMappingURL=register.js.map

package/dist/tools/register.js.map

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

package/dist/tools/result.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared MCP tool-result helpers: turn API data into a text result, map errors
+ * to a clean error result, and guard a handler so nothing throws out of a tool.
+ */
+/** A tool result carrying a JSON payload as pretty text. */
+export declare function jsonResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** A tool result flagged as an error, with a clean message. */
+export declare function errorResult(err: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/** Wrap a handler so any thrown error becomes a clean tool error. */
+export declare function guard(fn: () => Promise<ReturnType<typeof jsonResult>>): Promise<ReturnType<typeof jsonResult> | ReturnType<typeof errorResult>>;

package/dist/tools/result.js

@@ -0,0 +1,30 @@
+/**
+ * Shared MCP tool-result helpers: turn API data into a text result, map errors
+ * to a clean error result, and guard a handler so nothing throws out of a tool.
+ */
+import { AxonityApiError } from "../errors.js";
+/** A tool result carrying a JSON payload as pretty text. */
+export function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+/** A tool result flagged as an error, with a clean message. */
+export function errorResult(err) {
+    const message = err instanceof AxonityApiError
+        ? err.message
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/** Wrap a handler so any thrown error becomes a clean tool error. */
+export async function guard(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+//# sourceMappingURL=result.js.map

package/dist/tools/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/tools/result.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,4DAA4D;AAC5D,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,OAAO,GACX,GAAG,YAAY,eAAe;QAC5B,CAAC,CAAC,GAAG,CAAC,OAAO;QACb,CAAC,CAAC,GAAG,YAAY,KAAK;YACpB,CAAC,CAAC,GAAG,CAAC,OAAO;YACb,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAChF,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,EAAgD;IAEhD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/tools/workflowMutations.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `apply_workflow_mutations` — structural edits to a workflow document.
+ *
+ * A workflow's steps and edges are edited through mutation COMMANDS (the same
+ * backend-authoritative model the Studio uses), never by replacing the whole
+ * document. The backend applies and validates the commands and returns the new
+ * authoritative document + version.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AxonityClient } from "../client.js";
+export declare function registerWorkflowMutations(server: McpServer, client: AxonityClient): void;

package/dist/tools/workflowMutations.js

@@ -0,0 +1,45 @@
+/**
+ * `apply_workflow_mutations` — structural edits to a workflow document.
+ *
+ * A workflow's steps and edges are edited through mutation COMMANDS (the same
+ * backend-authoritative model the Studio uses), never by replacing the whole
+ * document. The backend applies and validates the commands and returns the new
+ * authoritative document + version.
+ */
+import { z } from "zod";
+import { AxonityApiError } from "../errors.js";
+export function registerWorkflowMutations(server, client) {
+    server.tool("apply_workflow_mutations", "Apply structural mutation commands to a workflow draft (add/remove steps, " +
+        "connect edges, set conditions). Read the workflow first for its version. " +
+        "Returns the new authoritative document + version. On a 409 conflict, " +
+        "re-read and retry.", {
+        id: z.string().describe("The workflow's id."),
+        expectedVersion: z
+            .number()
+            .int()
+            .describe("The version you last read — rejected with 409 if stale."),
+        mutations: z
+            .array(z.record(z.unknown()))
+            .describe("A list of mutation commands, each a JSON object with a command name " +
+            "and its arguments (camelCase)."),
+    }, async ({ id, expectedVersion, mutations }) => {
+        try {
+            const data = await client.post(`/api/v1/workflows/${id}/mutations`, {
+                expectedVersion,
+                mutations,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof AxonityApiError
+                ? err.message
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            return { content: [{ type: "text", text: message }], isError: true };
+        }
+    });
+}
+//# sourceMappingURL=workflowMutations.js.map

package/dist/tools/workflowMutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflowMutations.js","sourceRoot":"","sources":["../../src/tools/workflowMutations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,UAAU,yBAAyB,CACvC,MAAiB,EACjB,MAAqB;IAErB,MAAM,CAAC,IAAI,CACT,0BAA0B,EAC1B,4EAA4E;QAC1E,2EAA2E;QAC3E,uEAAuE;QACvE,oBAAoB,EACtB;QACE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QAC7C,eAAe,EAAE,CAAC;aACf,MAAM,EAAE;aACR,GAAG,EAAE;aACL,QAAQ,CAAC,yDAAyD,CAAC;QACtE,SAAS,EAAE,CAAC;aACT,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;aAC5B,QAAQ,CACP,sEAAsE;YACpE,gCAAgC,CACnC;KACJ,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,eAAe,EAAE,SAAS,EAAE,EAAE,EAAE;QAC3C,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,YAAY,EAAE;gBAClE,eAAe;gBACf,SAAS;aACV,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;aAC1E,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GACX,GAAG,YAAY,eAAe;gBAC5B,CAAC,CAAC,GAAG,CAAC,OAAO;gBACb,CAAC,CAAC,GAAG,YAAY,KAAK;oBACpB,CAAC,CAAC,GAAG,CAAC,OAAO;oBACb,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAChF,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@axonity-ai/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for Axonity Flow — lets an external agent (e.g. Claude Code) read, draft, and update workflows, agents and tools in an Axonity tenant.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AxonityAI/axonity-mcp.git"
+  },
+  "homepage": "https://github.com/AxonityAI/axonity-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/AxonityAI/axonity-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "axonity",
+    "claude",
+    "agent"
+  ],
+  "type": "module",
+  "bin": {
+    "axonity-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}