@wootsup/mcp 0.1.0-rc.9 → 0.1.0

package/dist/modules/apimapper/token-baseline.harness.js

@@ -0,0 +1,291 @@
+// token-baseline.harness.ts — W3.0.C
+//
+// Deterministic, offline token-output measurement for the canonical API
+// Mapper tool-call sequence. The SAME harness is re-run after Welle 3 ships;
+// the before/after delta is what proves the ≥40% token-reduction goal, so
+// consistency between runs matters more than the absolute number.
+//
+// How it works:
+//   1. The caller passes the registered apimapper tools map (the live
+//      `registerTool` config + handler for every tool) and a `fetchResponder`
+//      that maps an upstream URL to a canned real-shape REST response.
+//   2. `runTokenBaseline` installs the responder as `globalThis.fetch`,
+//      replays the 8-call canonical sequence against the real tool handlers
+//      with canned real-shape inputs, sums the UTF-8 byte length of every
+//      result's `content[].text` block, and restores `globalThis.fetch`.
+//   3. It returns `{ sequence: [{ tool, bytes }], totalBytes }`.
+//
+// No network, no child process — the tool handlers run in-process and the
+// REST layer is the supplied responder. Given the same tools map and the
+// same responder, the result is byte-for-byte identical (determinism is
+// pinned by token-baseline.test.ts).
+/**
+ * The canonical 8-call walkthrough (the Maria mixed-feed flow): a fresh user
+ * discovers the install, activates a library template, inspects a connection,
+ * builds and validates a flow, then compiles it. Inputs are real-shape and
+ * fixed so the measurement is reproducible.
+ */
+export const CANONICAL_SEQUENCE = [
+    { tool: "apimapper_onboarding", args: {} },
+    { tool: "apimapper_library_list", args: { limit: 25 } },
+    {
+        tool: "apimapper_library_activate",
+        args: { id: "pexels", extra_fields: { api_key: "demo-key" } },
+    },
+    { tool: "apimapper_connection_list", args: {} },
+    { tool: "apimapper_connection_data", args: { id: "con_pexels", limit: 10 } },
+    {
+        tool: "apimapper_flow_create",
+        args: {
+            name: "Maria Mixed Feed",
+            nodes: [
+                {
+                    id: "src1",
+                    type: "source",
+                    position: { x: 0, y: 0 },
+                    data: { connectionId: "con_pexels" },
+                },
+                {
+                    id: "out1",
+                    type: "output-yootheme",
+                    position: { x: 300, y: 0 },
+                    data: { name: "Mixed Feed" },
+                },
+            ],
+            edges: [{ id: "e1", source: "src1", target: "out1" }],
+        },
+    },
+    {
+        tool: "apimapper_graph_validate",
+        args: {
+            nodes: [
+                {
+                    id: "src1",
+                    type: "source",
+                    position: { x: 0, y: 0 },
+                    data: { connectionId: "con_pexels" },
+                },
+                {
+                    id: "out1",
+                    type: "output-yootheme",
+                    position: { x: 300, y: 0 },
+                    data: { name: "Mixed Feed" },
+                },
+            ],
+            edges: [{ id: "e1", source: "src1", target: "out1" }],
+        },
+    },
+    { tool: "apimapper_flow_compile", args: { id: "flow_maria01" } },
+];
+/** The tool names the canonical sequence exercises, in call order. */
+export const CANONICAL_TOOLS = CANONICAL_SEQUENCE.map((s) => s.tool);
+// ── Canonical real-shape REST fixtures ──────────────────────────────────
+//
+// One fixture per upstream endpoint the canonical sequence touches. Shapes
+// mirror the actual PHP wire responses (the same shapes the per-module test
+// files assert against). Keeping them here — alongside the sequence — means
+// the determinism test and the scripts/token-baseline.mjs runner measure the
+// exact same byte budget; the responder is a single source of truth.
+// `provider` mirrors the real library.test.ts fixtures — the library_list
+// handler reads it for the client-side provider filter, so shipping it keeps
+// the measured shape faithful to the live PHP wire response.
+const LIBRARY_ITEMS = [
+    {
+        id: "pexels",
+        name: "Pexels",
+        provider: "pexels",
+        category: "media",
+        description: "Free stock photos and videos via the Pexels REST API.",
+        auth_type: "apikey",
+        popular: true,
+    },
+    {
+        id: "google-sheets",
+        name: "Google Sheets",
+        provider: "google",
+        category: "productivity",
+        description: "Read rows from a Google Sheets spreadsheet.",
+        auth_type: "oauth2_authcode",
+        popular: true,
+    },
+    {
+        id: "instagram",
+        name: "Instagram Graph",
+        provider: "instagram",
+        category: "social",
+        description: "Fetch media from an Instagram Business account.",
+        auth_type: "oauth2_authcode",
+        popular: false,
+    },
+];
+const CONNECTIONS = [
+    {
+        id: "con_pexels",
+        name: "Pexels — Curated",
+        source_type: "pexels",
+        status: "active",
+        credential_id: "cred_pexels1",
+    },
+];
+const PEXELS_ROWS = Array.from({ length: 10 }, (_, i) => ({
+    id: 1000 + i,
+    title: `Curated photo ${i + 1}`,
+    photographer: `Photographer ${i + 1}`,
+    image: { url: `https://images.pexels.com/photos/${1000 + i}/photo.jpg` },
+    width: 1920,
+    height: 1280,
+}));
+const FLOW_OBJECT = {
+    id: "flow_maria01",
+    name: "Maria Mixed Feed",
+    node_count: 2,
+    is_compiled: false,
+};
+/**
+ * Canonical fetch responder — routes an upstream URL to its real-shape
+ * fixture. Anything unmatched returns an empty-success envelope, which is the
+ * benign default for the optional sub-calls inside `apimapper_onboarding`.
+ */
+export function canonicalFetchResponder(url) {
+    if (url.includes("/library/popular")) {
+        return { body: { connections: LIBRARY_ITEMS.filter((i) => i.popular) } };
+    }
+    if (url.includes("/library/featured")) {
+        return { body: { connections: LIBRARY_ITEMS.slice(0, 2) } };
+    }
+    if (url.includes("/library/categories")) {
+        return {
+            body: {
+                categories: [
+                    { id: "media", name: "Media", count: 4 },
+                    { id: "social", name: "Social", count: 3 },
+                ],
+            },
+        };
+    }
+    if (url.includes("/library/pexels/activate")) {
+        return {
+            body: {
+                success: true,
+                connection: { id: "con_pexels", name: "Pexels", source_type: "pexels" },
+                reused: false,
+            },
+        };
+    }
+    if (url.includes("/library")) {
+        return { body: { connections: LIBRARY_ITEMS, total: LIBRARY_ITEMS.length } };
+    }
+    if (url.includes("/connections/con_pexels/data")) {
+        // Real backend returns the connection as an OBJECT, not a bare id —
+        // mirrors the {data, connection:{…}} envelope the connections.test.ts
+        // fixtures assert against, so the byte measurement stays realistic.
+        return {
+            body: {
+                data: PEXELS_ROWS,
+                connection: {
+                    id: "con_pexels",
+                    name: "Pexels — Curated",
+                    source_type: "pexels",
+                },
+            },
+        };
+    }
+    if (url.includes("/connections")) {
+        return { body: { connections: CONNECTIONS } };
+    }
+    if (url.includes("/flows/flow_maria01/compile")) {
+        return { body: { compiled: {}, flowId: "flow_maria01" } };
+    }
+    if (url.includes("/flows")) {
+        return { body: { success: true, flow: FLOW_OBJECT } };
+    }
+    if (url.includes("/graph/validate")) {
+        return {
+            body: { valid: true, warnings: [], nodeCount: 2, edgeCount: 1 },
+        };
+    }
+    if (url.includes("/health")) {
+        return {
+            body: { plugin_version: "2.0.7", api_version: "v1", status: "ok" },
+        };
+    }
+    if (url.includes("/license")) {
+        return { body: { tier: "pro", status: "active" } };
+    }
+    // Benign default for any onboarding sub-call without a dedicated fixture.
+    return { body: {} };
+}
+/**
+ * Matches the toolkit's embedded structured-meta marker — a trailing
+ * `\n\n<!-- structured-meta:<base64> -->` block appended by the
+ * `tableResult` / `detailResult` / … builders so `_meta.ui` survives
+ * `@ai-sdk/mcp`'s conversion (see @getimo/mcp-toolkit `embedStructuredMeta`).
+ * The `[A-Za-z0-9+/=]*` body is base64; `g` strips every occurrence.
+ */
+const STRUCTURED_META_MARKER = /\n\n<!-- structured-meta:[A-Za-z0-9+/=]*? -->/g;
+/**
+ * Strip every embedded structured-meta marker from a text block. What remains
+ * is the human/LLM-readable text a marker-aware host (the WootsUp Chat UI)
+ * presents after extracting the marker into a Rich Card.
+ */
+export function stripStructuredMeta(text) {
+    return text.replace(STRUCTURED_META_MARKER, "");
+}
+/**
+ * Sum the UTF-8 byte length of every text block in a tool result — both the
+ * raw bytes (`bytes`) and the marker-stripped, LLM-visible bytes
+ * (`visibleBytes`). The raw figure is the token-baseline metric; the visible
+ * figure is what a marker-stripping host actually feeds the model.
+ */
+function resultBytes(result) {
+    const blocks = Array.isArray(result.content) ? result.content : [];
+    let bytes = 0;
+    let visibleBytes = 0;
+    for (const block of blocks) {
+        if (typeof block.text === "string") {
+            bytes += Buffer.byteLength(block.text, "utf8");
+            visibleBytes += Buffer.byteLength(stripStructuredMeta(block.text), "utf8");
+        }
+    }
+    return { bytes, visibleBytes };
+}
+/**
+ * Replay the canonical sequence and measure total token output.
+ *
+ * @param tools          the registered apimapper tools map (name → tool)
+ * @param fetchResponder maps each upstream URL to a canned REST response
+ * @returns per-tool byte tally + `totalBytes` across the whole sequence
+ */
+export async function runTokenBaseline(tools, fetchResponder) {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async (input, init) => {
+        const url = String(input);
+        const canned = fetchResponder(url, init);
+        const body = typeof canned.body === "string"
+            ? canned.body
+            : JSON.stringify(canned.body);
+        return new Response(body, {
+            status: canned.status ?? 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    });
+    try {
+        const sequence = [];
+        for (const step of CANONICAL_SEQUENCE) {
+            const tool = tools[step.tool];
+            if (!tool) {
+                throw new Error(`token-baseline: tool "${step.tool}" is not registered`);
+            }
+            const result = await tool.handler(step.args);
+            const { bytes, visibleBytes } = resultBytes(result);
+            sequence.push({ tool: step.tool, bytes, visibleBytes });
+        }
+        const totalBytes = sequence.reduce((sum, e) => sum + e.bytes, 0);
+        const totalVisibleBytes = sequence.reduce((sum, e) => sum + e.visibleBytes, 0);
+        return { sequence, totalBytes, totalVisibleBytes };
+    }
+    finally {
+        globalThis.fetch = originalFetch;
+    }
+}
+//# sourceMappingURL=token-baseline.harness.js.map

package/dist/modules/apimapper/token-baseline.harness.js.map

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

package/dist/modules/apimapper/toolslist-size.d.ts

@@ -0,0 +1,55 @@
+import { type CollectedTool } from "./gateway/test-support.js";
+/**
+ * The minimal `tools/list`-relevant slice of a registered tool: the fields the
+ * MCP client receives and the LLM reads as part of the static catalog.
+ */
+export interface ToolCatalogEntry {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: Record<string, unknown>;
+}
+/** One side of the measurement: its tool count and total serialized bytes. */
+export interface ToolsListMeasurement {
+    /** Number of tools in this `tools/list` surface. */
+    toolCount: number;
+    /** Sum of `Buffer.byteLength(JSON.stringify(entry))` across all tools. */
+    totalBytes: number;
+    /** Per-tool byte tally, sorted by name, for the breakdown table. */
+    perTool: Array<{
+        name: string;
+        bytes: number;
+    }>;
+}
+/** The full Task-B result: the post-W3 and pre-W3-equivalent surfaces. */
+export interface ToolsListComparison {
+    /** Post-W3 `tools/list` — the 17 surface tools the server exposes today. */
+    postW3: ToolsListMeasurement;
+    /** Pre-W3-equivalent `tools/list` — all 76 tools exposed flat (no gateway). */
+    preW3Flat: ToolsListMeasurement;
+    /** Absolute byte reduction (preW3Flat.totalBytes − postW3.totalBytes). */
+    bytesSaved: number;
+    /** Reduction as a fraction of the pre-W3-equivalent total (0..1). */
+    fractionSaved: number;
+}
+/**
+ * Projects one tool to its `tools/list` JSON-Schema-bearing catalog entry.
+ * The `inputSchema` is JSON-Schema-projected the same way the SDK and the
+ * gateway's discovery mode do, so the byte count reflects the real wire shape.
+ */
+export declare function toCatalogEntry(name: string, tool: Pick<CollectedTool, "description" | "inputSchema" | "annotations">): ToolCatalogEntry;
+/**
+ * Builds the full 77-tool catalog from the current build and measures the
+ * post-W3 vs pre-W3-equivalent `tools/list` payload sizes.
+ *
+ * Surface composition (verified against `gateway/essentials.ts` + `src/index.ts`):
+ *   - module tools  : 13 essentials + `apimapper_advanced` = 14 (on the real
+ *                     McpServer) + 60 advanced (gateway registry)            = 74
+ *   - top-level tools: rest_modules_status + use_profile + list_profiles      =  3
+ *                                                                      total = 77
+ *
+ * POST-W3 `tools/list` = the 14 module-real tools + the 3 top-level tools = 17.
+ * PRE-W3 flat `tools/list` = the 16 non-gateway surface tools + the 60 advanced
+ * tools = 76 (the `apimapper_advanced` gateway did not exist pre-W3).
+ */
+export declare function measureToolsList(): Promise<ToolsListComparison>;

package/dist/modules/apimapper/toolslist-size.js

@@ -0,0 +1,190 @@
+// toolslist-size.ts — W3 Stage-5 token-Δ measurement (Task B)
+//
+// Measures the `tools/list` catalog overhead — the static tool descriptions +
+// JSON schemas an MCP client receives once per session, before any tool is
+// called. This is the DOMINANT token cost center of an API Mapper session.
+//
+// Two figures, both derived from the CURRENT build:
+//
+//   - POST-W3 `tools/list`        — the 17 surface tools the server now exposes
+//                                   (13 module essentials + `apimapper_advanced`
+//                                   + the 3 src/index.ts top-level tools).
+//   - PRE-W3-equivalent `tools/list` — what `tools/list` WOULD be if all 77
+//                                   tools were exposed flat (the pre-Gateway
+//                                   state): the 17 surface tools minus the
+//                                   gateway tool, plus the 60 advanced-registry
+//                                   tool configs — 76 flat tools. (Pre-W3 the
+//                                   `apimapper_advanced` gateway did not exist.)
+//
+// Per-tool serialization mirrors what the MCP SDK puts on the wire for one
+// `tools/list` entry: `{ name, description, inputSchema, annotations }`, where
+// `inputSchema` is the JSON Schema projected from the tool's Zod raw-shape
+// (the same `z.toJSONSchema` projection `gateway/advanced-tool.ts` uses for
+// discovery mode). `title` and `_meta` are omitted: they are small, present on
+// both sides, and cancel out in the delta — keeping the measurement focused on
+// the description + schema payload that actually scales with the tool count.
+//
+// Determinism: given the same build, every figure is byte-for-byte identical.
+// Pinned by toolslist-size.test.ts.
+import * as os from "node:os";
+import * as path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { loadModules } from "@getimo/mcp-toolkit";
+import { z } from "zod";
+import { apimapperRestModule } from "./index.js";
+import { collectModuleTools } from "./gateway/test-support.js";
+import { registerListProfilesTool, registerUseProfileTool, } from "./use-profile.js";
+import { ProfileStore } from "../../auth/profiles.js";
+/**
+ * Reads a tool config's `inputSchema` as a Zod raw-shape. Mirrors `shapeOf`
+ * in `gateway/advanced-tool.ts` — a registered `inputSchema` is the raw shape
+ * object; a zero-arg tool has none.
+ */
+function shapeOf(inputSchema) {
+    if (inputSchema && typeof inputSchema === "object") {
+        return inputSchema;
+    }
+    return {};
+}
+/**
+ * Projects one tool to its `tools/list` JSON-Schema-bearing catalog entry.
+ * The `inputSchema` is JSON-Schema-projected the same way the SDK and the
+ * gateway's discovery mode do, so the byte count reflects the real wire shape.
+ */
+export function toCatalogEntry(name, tool) {
+    let inputSchema;
+    try {
+        inputSchema = z.toJSONSchema(z.object(shapeOf(tool.inputSchema)));
+    }
+    catch {
+        // A schema that cannot be JSON-projected still yields a usable entry; the
+        // description carries the rest. Matches the gateway discovery-mode guard.
+        inputSchema = { type: "object" };
+    }
+    return {
+        name,
+        description: tool.description,
+        inputSchema,
+        annotations: tool.annotations,
+    };
+}
+/**
+ * Serializes a list of catalog entries and tallies the UTF-8 byte length of
+ * each entry's `JSON.stringify`. The total is the `tools/list` payload size
+ * for that surface.
+ */
+function measure(entries) {
+    const perTool = entries
+        .map((entry) => ({
+        name: entry.name,
+        bytes: Buffer.byteLength(JSON.stringify(entry), "utf8"),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const totalBytes = perTool.reduce((sum, t) => sum + t.bytes, 0);
+    return { toolCount: perTool.length, totalBytes, perTool };
+}
+/** A no-op keychain: registration stores the dep but never invokes it here. */
+const STUB_KEYCHAIN = {
+    set: async () => undefined,
+    get: async () => null,
+    delete: async () => undefined,
+};
+/**
+ * Captures the 3 top-level tools registered in `src/index.ts` —
+ * `apimapper_rest_modules_status`, `apimapper_use_profile`,
+ * `apimapper_list_profiles` — by replaying their registration against a
+ * recording registrar. `src/index.ts` registers these directly on the
+ * McpServer (not via the module / CapturingServer), so they must be added to
+ * the catalog explicitly for an accurate `tools/list` count.
+ *
+ * The use-profile registrations only *store* their `{ store, keychain }` deps;
+ * they are never invoked at registration time, so a real `ProfileStore` over a
+ * throwaway dir + a stub keychain is sufficient to capture the configs.
+ */
+function captureTopLevelTools() {
+    const captured = new Map();
+    const recorder = {
+        registerTool(name, config) {
+            const cfg = config;
+            captured.set(name, {
+                handler: () => ({ content: [] }),
+                description: cfg.description,
+                inputSchema: cfg.inputSchema,
+                annotations: cfg.annotations,
+            });
+        },
+    };
+    // apimapper_rest_modules_status — registered inline in src/index.ts. Its
+    // config is replicated here verbatim (zero-arg readOnly status tool). The
+    // toolslist-size.test.ts cross-checks the captured name set, so drift
+    // between this replica and src/index.ts surfaces as a failing pin.
+    recorder.registerTool("apimapper_rest_modules_status", {
+        title: "Adapter Modules Status",
+        description: "Module-loading status for this MCP adapter (which sub-modules registered cleanly). " +
+            "For runtime connectivity + auth checks against the API Mapper REST surface, use apimapper_health.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false, title: "MCP Modules Status" },
+    });
+    // apimapper_use_profile + apimapper_list_profiles — registered via the
+    // use-profile module functions. Replaying the real registration functions
+    // captures their exact live config (description + Zod inputSchema).
+    // F-1.1 (Pass-1 consolidation): platform-portable temp path. The store is a
+    // throwaway used purely for tool-list shape capture during the measurement.
+    const store = new ProfileStore(path.join(os.tmpdir(), "__w3_toolslist_measure__"));
+    registerUseProfileTool(recorder, { store, keychain: STUB_KEYCHAIN });
+    registerListProfilesTool(recorder, { store, keychain: STUB_KEYCHAIN });
+    return captured;
+}
+/**
+ * Builds the full 77-tool catalog from the current build and measures the
+ * post-W3 vs pre-W3-equivalent `tools/list` payload sizes.
+ *
+ * Surface composition (verified against `gateway/essentials.ts` + `src/index.ts`):
+ *   - module tools  : 13 essentials + `apimapper_advanced` = 14 (on the real
+ *                     McpServer) + 60 advanced (gateway registry)            = 74
+ *   - top-level tools: rest_modules_status + use_profile + list_profiles      =  3
+ *                                                                      total = 77
+ *
+ * POST-W3 `tools/list` = the 14 module-real tools + the 3 top-level tools = 17.
+ * PRE-W3 flat `tools/list` = the 16 non-gateway surface tools + the 60 advanced
+ * tools = 76 (the `apimapper_advanced` gateway did not exist pre-W3).
+ */
+export async function measureToolsList() {
+    const server = new McpServer({
+        name: "toolslist-size-measure",
+        version: "0.0.0",
+    });
+    await loadModules(server, [apimapperRestModule]);
+    // collectModuleTools unifies the real-server essentials (incl. the gateway
+    // tool) with the captured advanced-registry tools.
+    const moduleTools = collectModuleTools(server, apimapperRestModule);
+    const topLevelTools = captureTopLevelTools();
+    const advancedRegistry = apimapperRestModule.getAdvancedRegistry();
+    const advancedNames = new Set(advancedRegistry ? advancedRegistry.keys() : []);
+    // POST-W3 surface: every tool in `tools/list` today — module-real tools that
+    // are NOT in the advanced registry (i.e. essentials + the gateway) plus the
+    // 3 top-level tools.
+    const postEntries = [];
+    for (const [name, tool] of Object.entries(moduleTools)) {
+        if (advancedNames.has(name))
+            continue; // advanced — gated behind the gateway
+        postEntries.push(toCatalogEntry(name, tool));
+    }
+    for (const [name, tool] of topLevelTools) {
+        postEntries.push(toCatalogEntry(name, tool));
+    }
+    // PRE-W3-equivalent flat surface: the post-W3 surface MINUS the gateway tool
+    // (it did not exist pre-W3) PLUS every advanced tool exposed flat.
+    const preEntries = postEntries.filter((e) => e.name !== "apimapper_advanced");
+    for (const [name, tool] of Object.entries(moduleTools)) {
+        if (!advancedNames.has(name))
+            continue; // only the advanced tools
+        preEntries.push(toCatalogEntry(name, tool));
+    }
+    const postW3 = measure(postEntries);
+    const preW3Flat = measure(preEntries);
+    const bytesSaved = preW3Flat.totalBytes - postW3.totalBytes;
+    const fractionSaved = preW3Flat.totalBytes > 0 ? bytesSaved / preW3Flat.totalBytes : 0;
+    return { postW3, preW3Flat, bytesSaved, fractionSaved };
+}
+//# sourceMappingURL=toolslist-size.js.map

package/dist/modules/apimapper/toolslist-size.js.map

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

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

@@ -53,14 +53,8 @@ export interface FlowNode {
     data?: Record<string, unknown>;
     [k: string]: unknown;
 }
-export interface FlowEdge {
-    id: string;
-    source: string;
-    target: string;
-    sourceHandle?: string;
-    targetHandle?: string;
-    [k: string]: unknown;
-}
+import type { FlowEdge } from "./node-schema.js";
+export type { FlowEdge };
 export interface Flow {
     id: string;
     name: string;
@@ -109,3 +103,24 @@ export interface LicenseStatus {
     activation_count?: number;
     max_activations?: number;
 }
+/**
+ * Bridge a typed-domain array to the toolkit's structurally-typed table-row
+ * shape.
+ *
+ * The mcp-core `tableResult()` (and other table builders) accept
+ * `Record<string, unknown>[]` for ASCII-table serialization. Our domain
+ * interfaces (`Connection`, `Credential`, `Flow`, `LibraryItem`, …) are
+ * nominal types without an index signature, so they are not structurally
+ * assignable to `Record<string, unknown>` even though every concrete row
+ * happens to satisfy it at runtime.
+ *
+ * Rather than scatter `items as unknown as Record<string, unknown>[]`
+ * across call-sites — each one looking like a code smell — this is the
+ * single documented interop point. Call-sites stay cast-free and the
+ * narrowing decision lives in ONE place that reviewers can audit.
+ *
+ * This is NOT a license to widen domain types — fields used downstream
+ * (column `key`s in the table config) are still type-checked against the
+ * domain interface separately.
+ */
+export declare function toRows<T extends object>(items: readonly T[]): Record<string, unknown>[];

package/dist/modules/apimapper/types.js

@@ -10,5 +10,30 @@
 //   - LocalSource wire fmt   = camelCase (contentType) with "platform/type" id ("wordpress/posts")
 //
 // These types reflect the actual REST contract verified against the PHP controllers.
-export {};
+// =============================================================================
+// Domain → toolkit interop bridge (F-1.2 — Pass-1 consolidation)
+// =============================================================================
+/**
+ * Bridge a typed-domain array to the toolkit's structurally-typed table-row
+ * shape.
+ *
+ * The mcp-core `tableResult()` (and other table builders) accept
+ * `Record<string, unknown>[]` for ASCII-table serialization. Our domain
+ * interfaces (`Connection`, `Credential`, `Flow`, `LibraryItem`, …) are
+ * nominal types without an index signature, so they are not structurally
+ * assignable to `Record<string, unknown>` even though every concrete row
+ * happens to satisfy it at runtime.
+ *
+ * Rather than scatter `items as unknown as Record<string, unknown>[]`
+ * across call-sites — each one looking like a code smell — this is the
+ * single documented interop point. Call-sites stay cast-free and the
+ * narrowing decision lives in ONE place that reviewers can audit.
+ *
+ * This is NOT a license to widen domain types — fields used downstream
+ * (column `key`s in the table config) are still type-checked against the
+ * domain interface separately.
+ */
+export function toRows(items) {
+    return items;
+}
 //# sourceMappingURL=types.js.map

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

@@ -1 +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"}
+{"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;AA8HrF,gFAAgF;AAChF,iEAAiE;AACjE,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,MAAM,CAAmB,KAAmB;IAC1D,OAAO,KAAwD,CAAC;AAClE,CAAC"}