@wootsup/mcp 0.1.0 → 0.4.0

package/dist/modules/apimapper/sites-tools.js

@@ -0,0 +1,165 @@
+// src/modules/apimapper/sites-tools.ts — Phase 3.
+//
+// Sites-file-backed implementations of the profile tools. When a sites-file is
+// active (APIMAPPER_SITES_FILE set + non-empty), index.ts wires THESE registrars
+// under the canonical tool names (apimapper_list_profiles / apimapper_use_profile)
+// instead of the keychain ProfileStore versions in use-profile.ts. The tool
+// names + response shapes stay identical so the agent surface is unchanged —
+// only the backing store differs (sites-file entries vs keychain profiles).
+//
+// `apimapper_use_profile(name)` calls `setActiveSite(name)` on the client, which
+// resets the resolution memo so the NEXT request() retargets the chosen site.
+// `setActiveSite` runs BEFORE the optional identity probe so the probe hits the
+// newly-activated site.
+import { z } from "zod";
+import { formatResult, mutating, readOnly } from "@getimo/mcp-toolkit";
+import { request } from "./client.js";
+export function registerSitesListProfilesTool(server, deps) {
+    const registrar = server;
+    registrar.registerTool("apimapper_list_profiles", {
+        title: "List Configured Profiles",
+        description: "List all configured site profiles (name, siteUrl, platform) with an " +
+            "is_active flag indicating which one is currently active. " +
+            "Backed by your sites-file (APIMAPPER_SITES_FILE). " +
+            "Use this to discover available profile names before calling " +
+            "apimapper_use_profile to switch the active site. " +
+            "Read-only — does not contact any site." +
+            "\n\nResponse shape:\n" +
+            "  { profile_count, active_profile, profiles: [{ name, siteUrl, platform, is_active }] }",
+        inputSchema: {},
+        annotations: readOnly({ title: "List Configured Profiles", openWorld: false }),
+    }, async () => {
+        const reg = deps.getRegistry();
+        const active = deps.getActiveSiteId();
+        // When no explicit pointer is set, the default entry is the active one.
+        const activeName = active ?? reg.getDefault().site_id;
+        const profiles = reg.list().map((entry) => ({
+            name: entry.site_id,
+            siteUrl: entry.url,
+            platform: entry.platform,
+            is_active: entry.site_id === activeName,
+        }));
+        return formatResult({
+            profile_count: profiles.length,
+            active_profile: activeName,
+            source: "sites-file",
+            profiles,
+        }, false, { maxChars: 3000 });
+    });
+}
+/**
+ * Default probe: switch already happened (setActiveSite ran first), so the
+ * legacy `request("identity")` now resolves to the freshly-activated site.
+ */
+async function defaultSitesProbeIdentity(_entry) {
+    const r = await 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) ||
+        (typeof o.siteurl === "string" && o.siteurl) ||
+        "";
+    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 };
+}
+export function registerSitesUseProfileTool(server, deps) {
+    const probe = deps.probeIdentity ?? defaultSitesProbeIdentity;
+    const registrar = server;
+    registrar.registerTool("apimapper_use_profile", {
+        title: "Switch Active Profile",
+        description: "Activate a configured site (from your sites-file) and probe its identity " +
+            "endpoint to confirm the site is reachable and the plugin is installed. " +
+            "Switching retargets every subsequent tool call at the chosen site. " +
+            "Use `noProbe: true` to skip the network probe for offline activation." +
+            "\n\nExample:\n  apimapper_use_profile({ name: 'prod', noProbe: false })",
+        inputSchema: {
+            name: z
+                .string()
+                .min(1)
+                .describe('Site_id to activate (e.g., "dev", "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."),
+        },
+        // Mutating: flips the active-site pointer (changes which backend every
+        // subsequent request targets). Closed-world — bounded to the local
+        // sites-file selection + an internal /identity call.
+        annotations: mutating({ title: "Switch Active Profile", openWorld: false }),
+    }, async (args) => {
+        const { name, noProbe = false } = args;
+        const reg = deps.getRegistry();
+        const entry = reg.get(name);
+        if (!entry) {
+            return formatResult({
+                error: `Site "${name}" not found in sites-file`,
+                context: { name, known: reg.listIds() },
+                hint: "Use apimapper_list_profiles to see configured sites.",
+            }, true);
+        }
+        // Switch FIRST so the (default) identity probe targets the new site.
+        try {
+            deps.setActiveSite(name);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return formatResult({
+                error: `Failed to activate site "${name}": ${msg}`,
+                context: { name },
+                hint: "Verify APIMAPPER_SITES_FILE is set and the site_id exists.",
+            }, true);
+        }
+        if (noProbe) {
+            return formatResult({
+                activated: true,
+                profile: { name: entry.site_id, siteUrl: entry.url, platform: entry.platform },
+                noProbe: true,
+                source: "sites-file",
+                warnings: [
+                    "Identity probe skipped (noProbe=true). Plugin reachability not verified.",
+                ],
+            }, false, { maxChars: 2500 });
+        }
+        let identity;
+        try {
+            identity = await probe(entry);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return formatResult({
+                // The switch already happened; surface that the probe (not the
+                // switch) failed so the agent knows the active site DID change.
+                error: `Site "${name}" activated, but identity probe failed: ${msg}`,
+                context: { name, siteUrl: entry.url, platform: entry.platform },
+                hint: "Verify the site is reachable and the plugin is installed/active. " +
+                    "Re-run with `noProbe: true` to activate without probing.",
+            }, true);
+        }
+        return formatResult({
+            activated: true,
+            profile: { name: entry.site_id, siteUrl: entry.url, platform: entry.platform },
+            source: "sites-file",
+            identity: {
+                plugin_version: identity.plugin_version,
+                plugin_hash: identity.plugin_hash,
+                capabilities: identity.capabilities,
+                site_url: identity.site_url,
+            },
+        }, false, { maxChars: 3000 });
+    });
+}
+//# sourceMappingURL=sites-tools.js.map

package/dist/modules/apimapper/sites-tools.js.map

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

package/dist/modules/apimapper/tool-result.d.ts

@@ -0,0 +1,66 @@
+import type { StructuredCallToolResult } from "@getimo/mcp-toolkit";
+import { type ApiErrorCode } from "./client.js";
+/**
+ * The minimal slice of a response this helper reads. `ExtApiResponse` (the
+ * shared client return type) is a structural superset, and the graph
+ * hydration object `{ error, status?, errorCode? }` also satisfies it, so
+ * both can flow through `restErrorResult` without a cast.
+ */
+export interface RestErrorLike {
+    /** Human-readable error from the upstream response, if any. */
+    error?: string;
+    /** Coarse error classification used for the recovery hint + code fallback. */
+    errorCode?: ApiErrorCode | string;
+    /** HTTP status, used as the `code` fallback when `errorCode` is absent. */
+    status?: number;
+    /**
+     * F11 (2026-06-09): the parsed JSON body of a non-2xx response (the WP +
+     * Joomla platform paths thread it through as `errorBody`). When the server
+     * returns a STRUCTURED domain error — e.g. the 400 `invalid_content_type`
+     * payload `{error_code, valid_types, suggestion}` — we surface those fields
+     * VERBATIM instead of the coarse `errorCode`/`hintFor()` defaults. Absent for
+     * non-JSON errors and for the legacy paths that never set it.
+     */
+    errorBody?: Record<string, unknown>;
+}
+/** Per-site overrides for the canonical REST-error mapping. */
+export interface RestErrorOpts {
+    /**
+     * Fallback message when `response.error` is absent. Mirrors the per-tool
+     * `r.error ?? "<fallback>"` string each site used inline.
+     */
+    message?: string;
+    /**
+     * Bespoke suggestion that overrides the default `hintFor(response.errorCode)`.
+     * Use only where a site intentionally pinned a tool-specific recovery hint.
+     */
+    suggestion?: string;
+    /**
+     * Bespoke `code` fallback that overrides the default `String(status)` when
+     * `response.errorCode` is absent. Use only where a site pinned a domain code.
+     */
+    code?: string;
+    /**
+     * F6 (2026-06-09): opt-in scope-aware 403 handling. Set by tools whose 403
+     * means "your key lacks the required scope" rather than "your key is
+     * invalid" — e.g. the *_delete tools (delete needs admin scope; a valid
+     * read+write key still 403s). When true AND the response is a 403 (or the
+     * body signals insufficient scope), the suggestion becomes a scope-upgrade
+     * hint instead of the generic key-recovery walkthrough. A 401 always stays a
+     * genuine bad-key auth failure even under scopeAware. Leave unset everywhere
+     * else so non-delete tools keep the legacy auth hint byte-for-byte.
+     */
+    scopeAware?: boolean;
+}
+/**
+ * Build the canonical structured error result for a failed REST request.
+ *
+ * Behaviour-preserving replacement for the 67× inline
+ * `errorResult({ message: r.error ?? …, code: …, suggestion: hintFor(…), details })`
+ * block. See the file header for the exact mapping and the opts contract.
+ *
+ * @param response the failed response (`!response.success` already checked by the caller)
+ * @param details  the structured `details` payload (typically the echoed input params)
+ * @param opts     per-site overrides — see {@link RestErrorOpts}
+ */
+export declare function restErrorResult(response: RestErrorLike, details?: Record<string, unknown>, opts?: RestErrorOpts): StructuredCallToolResult;

package/dist/modules/apimapper/tool-result.js

@@ -0,0 +1,125 @@
+// src/modules/apimapper/tool-result.ts — shared REST-error result builder.
+//
+// A1 (Wave-B audit, 2026-06-03): ~67 tool handlers across the apimapper
+// modules hand-wrote the IDENTICAL post-request error block:
+//
+//   if (!r.success) {
+//     return errorResult({
+//       message: r.error ?? "<per-tool fallback>",
+//       code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+//       suggestion: hintFor(r.errorCode),
+//       details: { ...inputParams },
+//     });
+//   }
+//
+// `restErrorResult(r, details?, opts?)` collapses that block to a single
+// call while preserving the output BYTE-FOR-BYTE. The mapping is:
+//
+//   message    → r.error ?? opts.message ?? "request failed"
+//   code       → r.errorCode ?? (r.status ? String(r.status) : undefined)
+//   suggestion → opts.suggestion ?? hintFor(r.errorCode)
+//   details    → details (passed through verbatim; computed by the caller)
+//
+// Per-site nuance is preserved through `opts`:
+//   - opts.message    : the per-tool fallback string when `r.error` is absent.
+//   - opts.suggestion : a bespoke suggestion that overrides hintFor() (used by
+//                       the few sites that want a tool-specific recovery hint
+//                       regardless of the error code).
+//   - opts.code       : a bespoke `code` fallback that overrides the
+//                       `r.status`-derived default when `r.errorCode` is absent
+//                       (used by sites that pin a domain code like
+//                       "credential_lookup_failed").
+//
+// Sites whose error is NOT a `!response.success` REST failure (e.g. a
+// post-success "entity not found" semantic check, or a `bad_request`
+// validation guard with a hardcoded message/code/suggestion) deliberately
+// stay on the raw `errorResult({...})` form — they are documented per-site
+// and must NOT be funnelled through this helper, because their message/code
+// do not derive from the response shape.
+import { errorResult } from "@getimo/mcp-toolkit";
+import { hintFor } from "./client.js";
+/**
+ * Build the canonical structured error result for a failed REST request.
+ *
+ * Behaviour-preserving replacement for the 67× inline
+ * `errorResult({ message: r.error ?? …, code: …, suggestion: hintFor(…), details })`
+ * block. See the file header for the exact mapping and the opts contract.
+ *
+ * @param response the failed response (`!response.success` already checked by the caller)
+ * @param details  the structured `details` payload (typically the echoed input params)
+ * @param opts     per-site overrides — see {@link RestErrorOpts}
+ */
+export function restErrorResult(response, details, opts = {}) {
+    const errorCode = response.errorCode;
+    const body = response.errorBody;
+    // F11: structured server-error passthrough. When the server attached a
+    // domain error_code (e.g. invalid_content_type), prefer it for `code`, lift
+    // its `suggestion` over the coarse hintFor(), and thread its `valid_types`
+    // (and any other primitive hint) into `details` so the agent can
+    // self-correct. Only engages when the body actually carries a string
+    // `error_code` — so a plain `{success:false, error}` body keeps the legacy
+    // path byte-for-byte.
+    const serverErrorCode = body && typeof body.error_code === "string" && body.error_code !== ""
+        ? body.error_code
+        : undefined;
+    const serverSuggestion = body && typeof body.suggestion === "string" && body.suggestion !== ""
+        ? body.suggestion
+        : undefined;
+    const serverValidTypes = body && Array.isArray(body.valid_types) ? body.valid_types : undefined;
+    // F6: scope-aware 403. A delete tool (scopeAware:true) that gets a 403 — or
+    // any body signalling insufficient scope — is missing the admin scope, not
+    // holding a bad key. A 401 is always a genuine bad-key failure regardless.
+    const bodyScopeSignal = body &&
+        ((typeof body.error_code === "string" && /scope/i.test(body.error_code)) ||
+            (typeof body.required_scope === "string" && body.required_scope !== ""));
+    const isScopeFailure = response.status !== 401 &&
+        (opts.scopeAware === true || bodyScopeSignal === true) &&
+        (response.status === 403 || bodyScopeSignal === true);
+    // F204 — distinguish an OWNERSHIP denial from a plain missing-admin-scope
+    // denial. `insufficient_scope_ownership` means the write-scope key tried to
+    // delete a flow it did NOT create; the remedy is "delete only your own flows,
+    // or use an admin key", not just "create an admin key".
+    const isOwnershipFailure = body && typeof body.error_code === "string" && body.error_code === "insufficient_scope_ownership";
+    const scopeSuggestion = isOwnershipFailure
+        ? "This write-scope key can only delete flows they created (the flow's owner " +
+            "kid must match the key's kid). This flow was created by a different key or " +
+            "via the dashboard, so it needs the admin scope. Use an admin-scope key " +
+            "(API Mapper → ⋮ menu → Settings → MCP Access → New API key, grant the admin " +
+            "scope, then re-run `npx -y @wootsup/mcp setup`), or delete it from the dashboard."
+        : isScopeFailure
+            ? "Your key lacks the admin scope required for delete/destructive operations. " +
+                "Create an admin-scope key (API Mapper → ⋮ menu → Settings → MCP Access → New API key, " +
+                "grant the admin scope) and re-run `npx -y @wootsup/mcp setup`, or perform the deletion " +
+                "from the dashboard."
+            : undefined;
+    // Suggestion precedence: explicit opts.suggestion → server suggestion (F11)
+    // → scope hint (F6) → coarse/message-driven hintFor(). The first three are
+    // intentional overrides; hintFor() is the legacy default. F83: pass the
+    // upstream `error` message so a JMESPath depth-limit 422 (which classifies to
+    // "unknown") routes to the two-transform-split remedy instead of the generic
+    // health hint. The depth detection only fires on the depth-limit wording, so
+    // every other message keeps the code-based hint byte-for-byte.
+    const suggestion = opts.suggestion ??
+        serverSuggestion ??
+        scopeSuggestion ??
+        hintFor(errorCode, response.error);
+    // Code precedence: server domain error_code (F11) → coarse errorCode →
+    // opts.code → status. The server code is the most specific, so it wins over
+    // the coarse classification (which is often just "unknown" for a 400).
+    const code = serverErrorCode ??
+        (errorCode !== undefined && errorCode !== ""
+            ? String(errorCode)
+            : opts.code ?? (response.status ? String(response.status) : undefined));
+    // Merge server hint fields (valid_types) into details so they reach the
+    // agent. Caller-supplied details win on key collision.
+    const mergedDetails = serverValidTypes !== undefined
+        ? { valid_types: serverValidTypes, ...(details ?? {}) }
+        : details;
+    return errorResult({
+        message: response.error ?? opts.message ?? "request failed",
+        code,
+        suggestion,
+        ...(mergedDetails !== undefined ? { details: mergedDetails } : {}),
+    });
+}
+//# sourceMappingURL=tool-result.js.map

package/dist/modules/apimapper/tool-result.js.map

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

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

@@ -1,4 +1,4 @@
-import { type CollectedTool } from "./gateway/test-support.js";
+import { type CollectedTool } from "./gateway/collect-module-tools.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.
@@ -23,9 +23,9 @@ export interface ToolsListMeasurement {
 }
 /** 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. */
+    /** Post-W3 `tools/list` — the 21 surface tools the server exposes today. */
     postW3: ToolsListMeasurement;
-    /** Pre-W3-equivalent `tools/list` — all 76 tools exposed flat (no gateway). */
+    /** Pre-W3-equivalent `tools/list` — all 79 tools exposed flat (no gateways). */
     preW3Flat: ToolsListMeasurement;
     /** Absolute byte reduction (preW3Flat.totalBytes − postW3.totalBytes). */
     bytesSaved: number;
@@ -39,17 +39,18 @@ export interface ToolsListComparison {
  */
 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
+ * Builds the full 81-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
+ * Surface composition (verified against `gateway/essentials.ts` + `src/index.ts`,
+ * pinned live in `gateway/gateway.test.ts` — A2):
+ *   - module tools  : 16 essentials + `apimapper_advanced` + `apimapper_advanced_read`
+ *                     = 18 (on the real McpServer) + 60 advanced (gateway registry) = 78
  *   - top-level tools: rest_modules_status + use_profile + list_profiles      =  3
- *                                                                      total = 77
+ *                                                                      total = 81
  *
- * 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).
+ * POST-W3 `tools/list` = the 18 module-real tools + the 3 top-level tools = 21.
+ * PRE-W3 flat `tools/list` = the 19 non-gateway surface tools + the 60 advanced
+ * tools = 79 (neither gateway existed pre-W3).
  */
 export declare function measureToolsList(): Promise<ToolsListComparison>;

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

@@ -4,17 +4,26 @@
 // 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:
+// Two figures, both derived from the CURRENT build (canonical counts asserted
+// live in gateway/gateway.test.ts — A2, 2026-06-03):
 //
-//   - 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
+//   - POST-W3 `tools/list`        — the 21 surface tools the server now exposes
+//                                   (16 module essentials + `apimapper_advanced`
+//                                   + `apimapper_advanced_read` + the 3
+//                                   src/index.ts top-level tools).
+//   - PRE-W3-equivalent `tools/list` — what `tools/list` WOULD be if all 79
 //                                   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.)
+//                                   state): the 21 surface tools minus the TWO
+//                                   gateway tools, plus the 60 advanced-registry
+//                                   tool configs — 79 flat tools. (Pre-W3 neither
+//                                   gateway existed.)
+//                                   F115 (2026-06-11): apimapper_health promoted
+//                                   advanced→essential — surface 19→20, advanced
+//                                   60→59 then 60. F200b (2026-06-12):
+//                                   apimapper_advanced_read added as a 2nd
+//                                   module-real gateway — surface 20→21; the flat
+//                                   total stays 79 (a gateway is a routing entry,
+//                                   never a flat tool).
 //
 // Per-tool serialization mirrors what the MCP SDK puts on the wire for one
 // `tools/list` entry: `{ name, description, inputSchema, annotations }`, where
@@ -32,7 +41,7 @@ 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 { collectModuleTools } from "./gateway/collect-module-tools.js";
 import { registerListProfilesTool, registerUseProfileTool, } from "./use-profile.js";
 import { ProfileStore } from "../../auth/profiles.js";
 /**
@@ -136,18 +145,19 @@ function captureTopLevelTools() {
     return captured;
 }
 /**
- * Builds the full 77-tool catalog from the current build and measures the
+ * Builds the full 81-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
+ * Surface composition (verified against `gateway/essentials.ts` + `src/index.ts`,
+ * pinned live in `gateway/gateway.test.ts` — A2):
+ *   - module tools  : 16 essentials + `apimapper_advanced` + `apimapper_advanced_read`
+ *                     = 18 (on the real McpServer) + 60 advanced (gateway registry) = 78
  *   - top-level tools: rest_modules_status + use_profile + list_profiles      =  3
- *                                                                      total = 77
+ *                                                                      total = 81
  *
- * 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).
+ * POST-W3 `tools/list` = the 18 module-real tools + the 3 top-level tools = 21.
+ * PRE-W3 flat `tools/list` = the 19 non-gateway surface tools + the 60 advanced
+ * tools = 79 (neither gateway existed pre-W3).
  */
 export async function measureToolsList() {
     const server = new McpServer({
@@ -173,9 +183,12 @@ export async function measureToolsList() {
     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");
+    // PRE-W3-equivalent flat surface: the post-W3 surface MINUS the gateway tools
+    // (neither existed pre-W3) PLUS every advanced tool exposed flat. F200b added
+    // the apimapper_advanced_read gateway — it is a routing entry like
+    // apimapper_advanced, not a flat tool, so it is excluded from the pre-W3 flat
+    // catalog too (the flat surface still totals 79 real tools).
+    const preEntries = postEntries.filter((e) => e.name !== "apimapper_advanced" && e.name !== "apimapper_advanced_read");
     for (const [name, tool] of Object.entries(moduleTools)) {
         if (!advancedNames.has(name))
             continue; // only the advanced tools

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

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

@@ -32,6 +32,11 @@ export interface Connection {
     template_fields?: Record<string, unknown>;
     origin_hash?: string;
     origin_id?: string | null;
+    health?: {
+        status?: string | null;
+        message?: string | null;
+        [k: string]: unknown;
+    } | null;
 }
 export interface Credential {
     id: string;
@@ -39,6 +44,27 @@ export interface Credential {
     auth_type: string;
     oauth_provider?: string | null;
     oauth_token_expires_at?: string | null;
+    /**
+     * Wave-12 F1 (Cold-AI #6) — canonical token-validity surface emitted by the
+     * PHP `/credentials` endpoint (`CredentialRepository::calculateStatus`).
+     * Values: 'active' | 'expiring' | 'expired' | 'broken'.
+     *
+     * - 'active' covers credentials with a refresh-token even if their
+     *   short-lived access token's `oauth_token_expires_at` is in the past —
+     *   they auto-renew on next use.
+     * - 'expired' is the only state where the customer truly needs to reconnect.
+     *
+     * The onboarding suggestion engine MUST prefer this field over the raw
+     * `oauth_token_expires_at` heuristic to avoid false-positive reconnect
+     * prompts for refreshable tokens (Google, GitHub, etc.).
+     */
+    status?: "active" | "expiring" | "expired" | "broken" | string | null;
+    /**
+     * Hard-expiry timestamp emitted ONLY for credentials WITHOUT a refresh-token
+     * (e.g. Meta/Instagram 60-day expiry). When this field is null/absent on an
+     * OAuth credential, the token is auto-refreshable and not user-visibly expirable.
+     */
+    token_hard_expires_at?: string | null;
     provider?: string | null;
     created_at?: string;
     updated_at?: string;
@@ -74,6 +100,13 @@ export interface Flow {
     version?: number;
     updated_at?: string;
     created_at?: string;
+    created_by?: string | null;
+    last_execution?: {
+        at?: string;
+        output_count?: number;
+        step_count?: number;
+        had_error?: boolean;
+    };
 }
 export interface LibraryItem {
     id: string;
@@ -85,6 +118,7 @@ export interface LibraryItem {
     is_activated?: boolean;
     logo_svg?: string;
     logo_hex?: string;
+    featured?: boolean;
 }
 export interface NodeSnapshot {
     id: string;

package/dist/modules/apimapper/types.js

@@ -7,7 +7,7 @@
 //   - 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")
+//   - LocalSource wire fmt   = camelCase (contentType) with "platform/type" id ("wordpress/post")
 //
 // These types reflect the actual REST contract verified against the PHP controllers.
 // =============================================================================

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;AA8HrF,gFAAgF;AAChF,iEAAiE;AACjE,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,MAAM,CAAmB,KAAmB;IAC1D,OAAO,KAAwD,CAAC;AAClE,CAAC"}
+{"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,kGAAkG;AAClG,EAAE;AACF,qFAAqF;AA+KrF,gFAAgF;AAChF,iEAAiE;AACjE,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,MAAM,CAAmB,KAAmB;IAC1D,OAAO,KAAwD,CAAC;AAClE,CAAC"}