@wootsup/mcp 0.1.0-rc.1

package/dist/modules/apimapper/types.d.ts

@@ -0,0 +1,111 @@
+export interface Connection {
+    id: string;
+    name: string;
+    source: string;
+    description?: string | null;
+    endpoint?: string;
+    method?: string;
+    auth_type?: string;
+    credential_id?: string | null;
+    items_path?: string | null;
+    cache_ttl?: string | number;
+    headers?: Array<{
+        name: string;
+        value: string;
+    }>;
+    body?: string | null;
+    params?: Array<{
+        name: string;
+        value: string;
+    }>;
+    default_params?: Array<{
+        name: string;
+        value: string;
+    }>;
+    fields?: unknown[];
+    endpoints?: Array<{
+        id?: string;
+        name?: string;
+        endpoint?: string;
+        method?: string;
+    }>;
+    template_fields?: Record<string, unknown>;
+    origin_hash?: string;
+    origin_id?: string | null;
+}
+export interface Credential {
+    id: string;
+    name: string;
+    auth_type: string;
+    oauth_provider?: string | null;
+    oauth_token_expires_at?: string | null;
+    provider?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface FlowNode {
+    id: string;
+    type: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    data?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+export interface FlowEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    [k: string]: unknown;
+}
+export interface Flow {
+    id: string;
+    name: string;
+    description?: string | null;
+    source?: string;
+    is_compiled?: boolean;
+    node_count?: number;
+    node_types?: string[];
+    connection_ids?: string[];
+    nodes?: FlowNode[];
+    edges?: FlowEdge[];
+    viewport?: {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    version?: number;
+    updated_at?: string;
+    created_at?: string;
+}
+export interface LibraryItem {
+    id: string;
+    slug?: string;
+    name: string;
+    category?: string;
+    provider?: string;
+    description?: string;
+    is_activated?: boolean;
+    logo_svg?: string;
+    logo_hex?: string;
+}
+export interface NodeSnapshot {
+    id: string;
+    flow_id?: string;
+    node_id?: string;
+    type?: string;
+    item_count?: number;
+    created_at?: string;
+}
+export interface LicenseStatus {
+    status: string;
+    tier?: string;
+    expires_at?: string | null;
+    beta_channel?: boolean;
+    features?: Record<string, unknown>;
+    activation_count?: number;
+    max_activations?: number;
+}

package/dist/modules/apimapper/types.js

@@ -0,0 +1,14 @@
+// src/modules/apimapper/types.ts — Canonical wire-format types for API Mapper REST.
+//
+// Important: API Mapper backend uses MIXED case conventions on the wire:
+//   - Connection wire format = **snake_case** (auth_type, credential_id, cache_ttl, items_path).
+//     Verified: admin-ui/src/api/wordpress.ts uses keysToSnakeCase before POST/PUT,
+//     ConnectionHandler.php:18 header comment "returned in snake_case".
+//   - Credential wire format = snake_case (auth_type, auth_data, oauth_provider)
+//   - Graph wire format      = camelCase (targetNodeId, forceRefresh)
+//   - Library wire format    = snake_case (extra_fields, library_connection)
+//   - LocalSource wire fmt   = camelCase (contentType) with "platform/type" id ("wordpress/posts")
+//
+// These types reflect the actual REST contract verified against the PHP controllers.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/modules/apimapper/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/apimapper/types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,EAAE;AACF,yEAAyE;AACzE,iGAAiG;AACjG,oFAAoF;AACpF,wEAAwE;AACxE,iFAAiF;AACjF,sEAAsE;AACtE,6EAA6E;AAC7E,mGAAmG;AACnG,EAAE;AACF,qFAAqF"}

package/dist/modules/apimapper/use-profile.d.ts

@@ -0,0 +1,34 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Keychain } from "../../auth/keychain.js";
+import type { Profile, ProfileStore } from "../../auth/profiles.js";
+interface ToolRegistrar {
+    registerTool(name: string, config: unknown, handler: unknown): void;
+}
+export interface IdentityProbeResult {
+    plugin_version: string;
+    plugin_hash: string;
+    capabilities: string[];
+    site_url: string;
+}
+export type ProbeIdentityFn = (profile: Profile, token: string) => Promise<IdentityProbeResult>;
+export interface UseProfileDeps {
+    store: ProfileStore;
+    keychain: Keychain;
+    /**
+     * Identity probe — calls the site's /identity endpoint and returns the
+     * normalised payload. Injected so tests can stub network calls and so the
+     * real impl can swap Platform clients.
+     */
+    probeIdentity?: ProbeIdentityFn;
+}
+/**
+ * Default identity probe — builds a Platform client from the profile + token
+ * and hits /identity. Returns the normalised IdentityProbeResult shape.
+ *
+ * The endpoint contract (see src/modules/admin-wordpress/.../IdentityController):
+ *   { plugin_version: string, plugin_hash: string, capabilities: string[],
+ *     site_url: string }
+ */
+export declare function defaultProbeIdentity(profile: Profile, token: string): Promise<IdentityProbeResult>;
+export declare function registerUseProfileTool(server: ToolRegistrar | McpServer, deps: UseProfileDeps): void;
+export {};

package/dist/modules/apimapper/use-profile.js

@@ -0,0 +1,176 @@
+// src/modules/apimapper/use-profile.ts — Phase 5.3.
+//
+// Single MCP tool `apimapper_use_profile`. Switches the active profile in the
+// ProfileStore, then (unless `noProbe: true`) probes the site's /identity
+// endpoint to confirm reachability + plugin install + signature.
+//
+// Plugin-hash drift between the stored `lastVerifiedIdentity.plugin_hash` and
+// the live probe response is a soft warning (returned in `warnings[]`) — the
+// activation still succeeds and the stored hash is refreshed. A network
+// failure during probe IS a hard error and the active pointer does NOT move.
+//
+// Dependencies (store/keychain/probe) are injected for testability — the
+// real wire-through happens in src/index.ts where the server is constructed.
+import { z } from "zod";
+import { formatResult, readOnly } from "@getimo/mcp-toolkit";
+import { createPlatform, } from "../../platform/index.js";
+import { createPlatformClient } from "./client.js";
+// ── Real probe (used in production) ──────────────────────────────────────
+/**
+ * Default identity probe — builds a Platform client from the profile + token
+ * and hits /identity. Returns the normalised IdentityProbeResult shape.
+ *
+ * The endpoint contract (see src/modules/admin-wordpress/.../IdentityController):
+ *   { plugin_version: string, plugin_hash: string, capabilities: string[],
+ *     site_url: string }
+ */
+export async function defaultProbeIdentity(profile, token) {
+    const platform = createPlatform({
+        kind: profile.platform,
+        baseUrl: profile.siteUrl,
+        token,
+    });
+    const client = createPlatformClient(platform);
+    const r = await client.request("identity");
+    if (!r.success) {
+        throw new Error(r.error ?? "identity probe failed");
+    }
+    return normaliseIdentity(r.data);
+}
+function normaliseIdentity(data) {
+    if (!data || typeof data !== "object") {
+        throw new Error("identity response missing object body");
+    }
+    const o = data;
+    const plugin_version = typeof o.plugin_version === "string" ? o.plugin_version : "";
+    const plugin_hash = typeof o.plugin_hash === "string" ? o.plugin_hash : "";
+    const site_url = typeof o.site_url === "string" ? o.site_url : "";
+    const caps = Array.isArray(o.capabilities)
+        ? o.capabilities.filter((c) => typeof c === "string")
+        : [];
+    if (!plugin_version || !plugin_hash) {
+        throw new Error("identity response missing required fields");
+    }
+    return {
+        plugin_version,
+        plugin_hash,
+        site_url,
+        capabilities: caps,
+    };
+}
+// ── Tool registrar ───────────────────────────────────────────────────────
+export function registerUseProfileTool(server, deps) {
+    const probe = deps.probeIdentity ?? defaultProbeIdentity;
+    // Cast through ToolRegistrar so tests can pass a minimal stub but the real
+    // McpServer also satisfies the interface.
+    const registrar = server;
+    registrar.registerTool("apimapper_use_profile", {
+        title: "Switch Active Profile",
+        description: "Activate a configured site profile and probe its identity endpoint to confirm " +
+            "the site is reachable and the plugin signature matches. Plugin-hash drift is " +
+            "returned as a warning (not an error). Use `noProbe: true` to skip the network " +
+            "probe for offline activation." +
+            "\n\nExample:\n  apimapper_use_profile({ name: 'dev-wp', noProbe: false })",
+        inputSchema: {
+            name: z
+                .string()
+                .min(1)
+                .describe('Profile name to activate (e.g., "dev-wp", "client-x-prod"). Use apimapper_list_profiles to discover.'),
+            noProbe: z
+                .boolean()
+                .default(false)
+                .describe("Skip the live /identity probe. Use for offline activation when the site is unreachable."),
+        },
+        annotations: readOnly(),
+    }, async (args) => {
+        const { name, noProbe = false } = args;
+        // ── 1. Profile lookup ────────────────────────────────────────────
+        const profile = await deps.store.get(name);
+        if (!profile) {
+            return formatResult({
+                error: `Profile "${name}" not found`,
+                context: { name },
+                hint: "Use apimapper_list_profiles to see configured profiles, or " +
+                    "run the setup CLI to add a new one.",
+            }, true);
+        }
+        // ── 2. Token lookup ──────────────────────────────────────────────
+        const token = await deps.keychain.get(profile.keychainRef);
+        if (!token) {
+            return formatResult({
+                error: `Token missing from keychain for profile "${name}" (ref: ${profile.keychainRef})`,
+                context: { name, keychainRef: profile.keychainRef },
+                hint: "The profile metadata exists but the underlying token is gone. " +
+                    "Re-run the setup CLI to recreate the keychain entry.",
+            }, true);
+        }
+        // ── 3. Offline path ─────────────────────────────────────────────
+        if (noProbe) {
+            await deps.store.setActive(name);
+            return formatResult({
+                activated: true,
+                profile: {
+                    name: profile.name,
+                    siteUrl: profile.siteUrl,
+                    platform: profile.platform,
+                },
+                noProbe: true,
+                warnings: [
+                    "Identity probe skipped (noProbe=true). Plugin reachability not verified.",
+                ],
+            }, false, { maxChars: 2500 });
+        }
+        // ── 4. Probe identity ───────────────────────────────────────────
+        let identity;
+        try {
+            identity = await probe(profile, token);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return formatResult({
+                error: `Identity probe failed for "${name}": ${msg}`,
+                context: { name, siteUrl: profile.siteUrl, platform: profile.platform },
+                hint: "Verify the site is reachable and the plugin is installed/active. " +
+                    "Use `noProbe: true` to switch profile without probing.",
+            }, true);
+        }
+        // ── 5. Hash-match check ────────────────────────────────────────
+        const storedHash = profile.lastVerifiedIdentity?.plugin_hash;
+        const warnings = [];
+        let hashMatch = true;
+        if (storedHash && storedHash !== identity.plugin_hash) {
+            hashMatch = false;
+            warnings.push(`Plugin hash drift: stored=${storedHash} live=${identity.plugin_hash}. ` +
+                "Plugin was reinstalled / upgraded / tampered with since last activation. " +
+                "Stored hash has been refreshed.");
+        }
+        // ── 6. Persist refreshed identity + setActive ──────────────────
+        await deps.store.update(name, {
+            lastVerifiedIdentity: {
+                plugin_version: identity.plugin_version,
+                plugin_hash: identity.plugin_hash,
+                capabilities: identity.capabilities,
+            },
+        });
+        await deps.store.setActive(name);
+        const payload = {
+            activated: true,
+            profile: {
+                name: profile.name,
+                siteUrl: profile.siteUrl,
+                platform: profile.platform,
+            },
+            identity: {
+                plugin_version: identity.plugin_version,
+                plugin_hash: identity.plugin_hash,
+                capabilities: identity.capabilities,
+                site_url: identity.site_url,
+            },
+            hashMatch,
+        };
+        if (warnings.length > 0)
+            payload.warnings = warnings;
+        return formatResult(payload, false, { maxChars: 3000 });
+    });
+}
+//# sourceMappingURL=use-profile.js.map

package/dist/modules/apimapper/use-profile.js.map

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

package/dist/modules/apimapper/workflows.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerWorkflowTools(server: McpServer): void;

package/dist/modules/apimapper/workflows.js

@@ -0,0 +1,301 @@
+import { z } from "zod";
+import { formatResult, creating, mutating } from "@getimo/mcp-toolkit";
+import { request, hintFor } from "./client.js";
+import { buildFlowGraph } from "./graph-builder.js";
+import { normalizeMergeStrategy } from "./normalizers.js";
+const SourceSpec = z.object({
+    connection: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
+    endpoint: z.string().optional().describe('Endpoint id (e.g., "Scheduled Events")'),
+    template_fields: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Template field values (e.g., {"user_uri":"...","spreadsheet_id":"..."})'),
+    items_path: z.string().optional().describe("Override items_path"),
+    label: z.string().optional().describe("Display label for the source node"),
+});
+const MergeSpec = z.object({
+    strategy: z.enum(["join", "concat", "append"]).describe('Merge strategy ("append" alias for "concat")'),
+    joinKey: z.string().optional().describe("Left-side join key field (required for strategy=join)"),
+    joinKeyRight: z.string().optional().describe("Right-side join key field (defaults to joinKey)"),
+    joinType: z.enum(["left", "inner"]).default("left").describe("Join type"),
+});
+const TransformSpec = z.object({
+    expression: z.string().default("[*]").describe('JMESPath expression (e.g., "[*]" or "[*].{title:name,id:id}")'),
+});
+const OutputSpec = z.object({
+    type: z.enum(["yootheme", "shortcode"]).default("yootheme").describe("Output type"),
+    name: z.string().min(1).describe("Source name shown in YOOtheme dropdown"),
+    slug: z.string().optional().describe('Source slug (auto-generated if omitted)'),
+});
+export function registerWorkflowTools(server) {
+    // ── apimapper_flow_setup_with_sources ──────────────────────────────
+    server.registerTool("apimapper_flow_setup_with_sources", {
+        title: "Setup Multi-Source Flow (Composite)",
+        description: "Compose a complete flow from connections in one call. Sequence: " +
+            "(1) build graph via buildFlowGraph() — pure function, deterministic layout. " +
+            "(2) POST /flows (creates row). " +
+            "(3) POST /flows/{id}/compile (publishes to YOOtheme). " +
+            "Returns flow_id + per-step status. On partial failure, returns cleanup hint." +
+            "\n\nExample:\n  apimapper_flow_setup_with_sources({ name: 'Pexels + IG Gallery', sources: [{ connection: 'con_pexels' }, { connection: 'con_instagram' }], merge: { strategy: 'concat' }, output: { type: 'yootheme', name: 'Gallery' } })",
+        inputSchema: {
+            name: z.string().min(1).describe('Flow name (appears in YOOtheme dropdown)'),
+            description: z.string().optional().describe("Optional description"),
+            sources: z.array(SourceSpec).min(1).describe("1..N source connections"),
+            merge: MergeSpec.optional().describe("Merge config — required if sources.length >= 2"),
+            transform: TransformSpec.optional().describe("Optional Transform node"),
+            output: OutputSpec.describe("Output node config"),
+            compile: z.boolean().default(true).describe("Compile after save (= publish to YOOtheme)"),
+        },
+        annotations: creating(),
+    }, async ({ name, description, sources, merge, transform, output, compile }) => {
+        // Validate via buildFlowGraph (it throws on invalid combos)
+        let graph;
+        try {
+            graph = buildFlowGraph({
+                sources,
+                merge: merge,
+                transform: transform,
+                output: output,
+            });
+        }
+        catch (e) {
+            return formatResult({
+                error: e instanceof Error ? e.message : String(e),
+                context: { source_count: sources.length, has_merge: !!merge },
+                hint: "Check the validation rules in buildFlowGraph — typically missing merge for multi-source, or missing joinKey for strategy=join.",
+            }, true);
+        }
+        // Step 1: create
+        const createR = await request("/flows", {
+            method: "POST",
+            body: JSON.stringify({
+                name,
+                description,
+                nodes: graph.nodes,
+                edges: graph.edges,
+                viewport: graph.viewport,
+            }),
+        });
+        if (!createR.success || !createR.data?.id) {
+            return formatResult({
+                error: createR.error || "create returned no flow id",
+                status: createR.status,
+                errorCode: createR.errorCode,
+                context: { name, stage: "create" },
+                hint: hintFor(createR.errorCode),
+            }, true);
+        }
+        const flowId = createR.data.id;
+        const steps = [`1. Flow created: ${flowId}`];
+        // Step 2: compile (optional)
+        let compiled = false;
+        let compileError;
+        if (compile) {
+            const compileR = await request(`/flows/${encodeURIComponent(flowId)}/compile`, { method: "POST" });
+            if (!compileR.success) {
+                compileError = compileR.error;
+                steps.push(`2. Compile FAILED: ${compileR.error}`);
+            }
+            else {
+                const dataObj = compileR.data && typeof compileR.data === "object" ? compileR.data : {};
+                const errors = Array.isArray(dataObj.errors) ? dataObj.errors : [];
+                const flow = dataObj.flow ?? dataObj;
+                if (errors.length > 0 || flow.is_compiled === false) {
+                    compileError = `compile errors: ${JSON.stringify(errors)}`;
+                    steps.push("2. Compile FAILED with validation errors");
+                }
+                else {
+                    compiled = true;
+                    steps.push("2. Compiled — flow visible in YOOtheme dropdown");
+                }
+            }
+        }
+        if (compile && !compiled) {
+            return formatResult({
+                partial_success: true,
+                flow_id: flowId,
+                compiled: false,
+                compile_error: compileError,
+                steps,
+                next_action: "investigate_compile_error",
+                cleanup: `Call apimapper_flow_delete with id="${flowId}" + confirm=true to roll back the orphan, OR fix node config and call apimapper_flow_compile again.`,
+                hint: "Compile errors usually mean missing joinKey, invalid JMESPath, or missing connection. Use apimapper_flow_get to inspect node data.",
+            }, true);
+        }
+        return formatResult({
+            created: true,
+            flow_id: flowId,
+            name: createR.data.name,
+            compiled,
+            source_count: sources.length,
+            merge_strategy: merge ? normalizeMergeStrategy(merge.strategy) : null,
+            steps,
+            next: compiled
+                ? "Use apimapper_graph_preview to test items, or bind in YOOtheme Builder."
+                : "Call apimapper_flow_compile to publish.",
+        }, false, { maxChars: 3000 });
+    });
+    // ── apimapper_flow_change_merge_strategy ───────────────────────────
+    server.registerTool("apimapper_flow_change_merge_strategy", {
+        title: "Change Flow Merge Strategy (Composite)",
+        description: "Toggle a flow's merge-node strategy and re-compile. Preserves joinKey/joinKeyRight " +
+            "across switches — works around a known UI bug where the strategy toggle wipes joinKey. " +
+            "See ~/Projekte/getimo/40-Plans/active/2026-05-18-mcp-apimapper-rest-full-coverage-design.md." +
+            "\n\nExample:\n  apimapper_flow_change_merge_strategy({ flow_id: 'flow_Z2fLg70M84', strategy: 'join', joinKey: 'id' })",
+        inputSchema: {
+            flow_id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
+            strategy: z.enum(["join", "concat", "append"]).describe("New merge strategy"),
+            joinKey: z.string().optional().describe("Left-side join key (required for strategy=join)"),
+            joinKeyRight: z.string().optional().describe("Right-side join key (defaults to joinKey)"),
+            joinType: z.enum(["left", "inner"]).optional().describe("Join type override"),
+            compile: z.boolean().default(true).describe("Compile after save"),
+        },
+        annotations: mutating(),
+    }, async ({ flow_id, strategy, joinKey, joinKeyRight, joinType, compile }) => {
+        const getR = await request(`/flows/${encodeURIComponent(flow_id)}`);
+        if (!getR.success || !getR.data) {
+            return formatResult({
+                error: getR.error || "flow not found",
+                status: getR.status,
+                errorCode: getR.errorCode,
+                context: { flow_id, stage: "fetch" },
+                hint: hintFor(getR.errorCode),
+            }, true);
+        }
+        const flow = getR.data;
+        if (!Array.isArray(flow.nodes)) {
+            return formatResult({
+                error: "flow.nodes is not an array",
+                context: { flow_id, type: typeof flow.nodes },
+                hint: "Flow data shape unexpected. Use apimapper_flow_get to inspect.",
+            }, true);
+        }
+        const mergeNode = flow.nodes.find((n) => n.type === "merge");
+        if (!mergeNode) {
+            return formatResult({
+                error: "no merge node in flow",
+                context: { flow_id, node_types: flow.nodes.map((n) => n.type) },
+                hint: "This flow has no merge node — strategy change not applicable.",
+            }, true);
+        }
+        const compiledStrategy = normalizeMergeStrategy(strategy);
+        const oldData = (mergeNode.data || {});
+        const newData = {
+            ...oldData,
+            strategy: compiledStrategy,
+            label: `Merge: ${compiledStrategy === "concat" ? "Concat" : "Join"}`,
+        };
+        if (compiledStrategy === "join") {
+            newData.joinKey = joinKey || oldData.joinKey || "";
+            newData.joinKeyRight = joinKeyRight || oldData.joinKeyRight;
+            if (joinType)
+                newData.joinType = joinType;
+            if (!newData.joinKey) {
+                return formatResult({
+                    error: "joinKey required for strategy=join (and not present on existing node)",
+                    context: { flow_id, existing_data: oldData },
+                    hint: "Pass joinKey explicitly.",
+                }, true);
+            }
+        }
+        mergeNode.data = newData;
+        const putR = await request(`/flows/${encodeURIComponent(flow_id)}`, {
+            method: "PUT",
+            body: JSON.stringify({ nodes: flow.nodes }),
+        });
+        if (!putR.success) {
+            return formatResult({
+                error: putR.error,
+                status: putR.status,
+                errorCode: putR.errorCode,
+                context: { flow_id, stage: "update" },
+                hint: hintFor(putR.errorCode),
+            }, true);
+        }
+        let compiled = false;
+        let compileError;
+        if (compile) {
+            const compileR = await request(`/flows/${encodeURIComponent(flow_id)}/compile`, { method: "POST" });
+            if (compileR.success)
+                compiled = true;
+            else
+                compileError = compileR.error;
+        }
+        if (compile && !compiled) {
+            return formatResult({
+                partial_success: true,
+                flow_id,
+                strategy: compiledStrategy,
+                joinKey: newData.joinKey,
+                joinKeyRight: newData.joinKeyRight,
+                compiled: false,
+                compile_error: compileError,
+                next_action: "investigate_compile_error_or_revert",
+                cleanup: "Option A: fix the merge config (e.g., correct joinKey field name) and call apimapper_flow_compile. " +
+                    "Option B: revert via apimapper_flow_change_merge_strategy back to the previous strategy. " +
+                    "The flow PUT succeeded — node data is updated but the flow won't appear in YOOtheme until compile passes.",
+                hint: "Compile errors usually mean wrong joinKey field name. Use apimapper_flow_get to inspect node data.",
+            }, true);
+        }
+        return formatResult({
+            updated: true,
+            flow_id,
+            strategy: compiledStrategy,
+            joinKey: newData.joinKey,
+            joinKeyRight: newData.joinKeyRight,
+            compiled,
+            compile_error: compileError,
+        }, false, { maxChars: 2500 });
+    });
+    // ── apimapper_flow_full_recompile_publish ──────────────────────────
+    server.registerTool("apimapper_flow_full_recompile_publish", {
+        title: "Full Recompile + Cache Clear (Composite)",
+        description: "Compile a flow + invalidate admin cache in one call. Use after upstream API changes " +
+            "to ensure the flow + schema are fresh. Each step's success is surfaced separately " +
+            "— a cache-clear failure does NOT silently downgrade compile success." +
+            "\n\nExample:\n  apimapper_flow_full_recompile_publish({ flow_id: 'flow_Z2fLg70M84' })",
+        inputSchema: {
+            flow_id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
+        },
+        annotations: mutating(),
+    }, async ({ flow_id }) => {
+        const steps = [];
+        const errors = [];
+        // Stage 1: compile
+        const compileR = await request(`/flows/${encodeURIComponent(flow_id)}/compile`, { method: "POST" });
+        if (!compileR.success) {
+            return formatResult({
+                error: compileR.error,
+                status: compileR.status,
+                errorCode: compileR.errorCode,
+                context: { flow_id, stage: "compile" },
+                hint: hintFor(compileR.errorCode),
+            }, true);
+        }
+        steps.push("1. Flow compiled");
+        // Stage 2: cache invalidate (admin cache — admin-ui + render cache)
+        const cacheR = await request("/cache/admin/invalidate", {
+            method: "POST",
+            body: JSON.stringify({ scope: "flow", id: flow_id }),
+        });
+        if (cacheR.success) {
+            steps.push("2. Admin cache invalidated");
+        }
+        else {
+            errors.push({ stage: "cache", error: cacheR.error || "unknown" });
+            steps.push(`2. Admin cache invalidation FAILED: ${cacheR.error}`);
+        }
+        const ok = errors.length === 0;
+        return formatResult({
+            ok,
+            partial: !ok,
+            flow_id,
+            steps,
+            errors: ok ? undefined : errors,
+            next: ok
+                ? "Flow is fresh in both admin + render layers. YOOtheme schema cache is NOT cleared by this tool — clear it via the YOOtheme MCP (yootheme_clear_cache) if needed."
+                : "Compile succeeded but cache step had issues. Manually call apimapper_cache_invalidate scope=all if downstream still sees stale data.",
+        }, ok, { maxChars: 2500 });
+    });
+}
+//# sourceMappingURL=workflows.js.map