@wootsup/mcp 0.3.0 → 0.4.0

package/dist/modules/apimapper/gateway/advanced-read-tool.js

@@ -0,0 +1,172 @@
+// src/modules/apimapper/gateway/advanced-read-tool.ts — F200b
+//
+// `apimapper_advanced_read` — a READ-ONLY sibling of the `apimapper_advanced`
+// gateway. The Desktop-E2E #2 forensics (2026-06-12) showed every advanced
+// call (even pure reads like flow_get / graph_preview) routed through the
+// single write-capable gateway, whose `creating` annotation makes hosts gate
+// it behind an approval prompt. Most advanced calls in a session are READS.
+//
+// This gateway whitelists ONLY the read-only advanced subtools — derived
+// straight from each subtool's `readOnlyHint` annotation (zero per-provider
+// branching) — and carries a `readOnly` annotation itself, so a host treats
+// the whole read surface as side-effect-free and stops prompting on every
+// discovery / inspect call. Write/mutate/create/destructive subtools stay
+// reachable ONLY through `apimapper_advanced`.
+//
+// Two modes mirror the write gateway:
+//   { tool }              → discovery (schema + annotations, no invocation)
+//   { tool, arguments }   → execution (validate against the target's Zod schema,
+//                           then invoke the captured handler with the same `extra`)
+import { z } from "zod";
+import { readOnly, errorResult } from "@getimo/mcp-toolkit";
+import { renderGroupedList, shapeOf, discoveryResult, isReadOnlyEntry, } from "./gateway-shared.js";
+import { isEssential } from "./essentials.js";
+/**
+ * Builds the read gateway's description: it lists ONLY the read-only subtools,
+ * grouped by domain, and steers write/mutate/create/destructive calls to the
+ * full `apimapper_advanced` gateway.
+ */
+function buildReadDescription(readNames) {
+    const toolCount = readNames.length;
+    return (`Routes to the ${toolCount} READ-ONLY advanced API Mapper tools. ` +
+        // F214: stop the model habitually routing first-class tools through the
+        // gateway (a wasted invalid_arguments cycle each time). State the scope
+        // boundary up front, before the grouped-tool list.
+        "ONLY for the read-only advanced tools listed below — every tool that " +
+        "appears directly in tools/list is FIRST-CLASS: call it directly, never via this gateway. " +
+        "All targets are side-effect-free (readOnly), so this gateway can be called " +
+        "freely for discovery and inspection without write-confirmation prompts. " +
+        "Call with { tool } for a target's schema + annotations, or " +
+        "{ tool, arguments } to run it.\n\n" +
+        "Available read-only tools by domain:\n" +
+        `${renderGroupedList(readNames)}\n\n` +
+        "For write / mutate / create / delete tools, use the full apimapper_advanced gateway.");
+}
+/**
+ * Registers `apimapper_advanced_read` on the real McpServer.
+ *
+ * @param realServer       the McpServer that exposes the gateway tool
+ * @param advancedRegistry the captured non-essential tools (from CapturingServer)
+ */
+export function registerAdvancedReadTool(realServer, advancedRegistry) {
+    // F200b — derive the read whitelist from each subtool's readOnlyHint. This
+    // is the SOLE classifier; adding a read-only advanced tool covers it
+    // automatically on the next registration, with no list to maintain here.
+    const readEntries = new Map();
+    for (const [name, entry] of advancedRegistry) {
+        if (isReadOnlyEntry(entry))
+            readEntries.set(name, entry);
+    }
+    const readNames = [...readEntries.keys()].sort();
+    realServer.registerTool("apimapper_advanced_read", {
+        title: "Advanced Read-Only Tool Gateway",
+        description: buildReadDescription(readNames),
+        inputSchema: {
+            // F205 (P2): `tool` is a free string, NOT a z.enum — same trap as the
+            // write gateway. The MCP SDK validates the inputSchema before the
+            // handler runs; an enum rejected first-class names with a raw McpError
+            // -32602 so the handler's not_read_only / first_class_tool / unknown
+            // steering never ran. A plain string lets every name reach the handler.
+            tool: z
+                .string()
+                .describe('Read-only advanced tool to route to (e.g. "apimapper_flow_get"). ' +
+                "Must be one of the read-only advanced tools listed in this " +
+                "gateway's description. First-class tools (apimapper_health, ...) " +
+                "are called DIRECTLY; write/mutate tools use apimapper_advanced. " +
+                "Omit `arguments` to discover its schema first."),
+            arguments: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Arguments for the target tool. Omit for discovery mode " +
+                "(returns the tool's schema + annotations)."),
+        },
+        // The whole surface is side-effect-free — that is the entire point of
+        // this gateway. openWorld:true because the read targets may touch
+        // upstream APIs (graph_preview, connection_test, library_* reads).
+        annotations: readOnly({ openWorld: true, title: "Advanced Read-Only Tool Gateway" }),
+    }, async (args, extra) => {
+        const entry = readEntries.get(args.tool);
+        if (!entry) {
+            // A WRITE subtool name that exists in the FULL registry but not the
+            // read whitelist gets a targeted steer to apimapper_advanced; this
+            // branch MUST stay ahead of the first_class_tool check (an advanced
+            // write subtool is not a first-class tool).
+            const existsAsWrite = advancedRegistry.has(args.tool);
+            if (existsAsWrite) {
+                return errorResult({
+                    message: `"${args.tool}" is not a read-only tool — it mutates state and is not ` +
+                        "reachable through apimapper_advanced_read.",
+                    code: "not_read_only",
+                    suggestion: `Call it through the full gateway instead: ` +
+                        `apimapper_advanced({ tool: "${args.tool}", arguments: {...} }).`,
+                    details: { tool: args.tool },
+                });
+            }
+            // F205: a first-class tool name (in tools/list directly) is steered to
+            // a direct call rather than treated as a typo.
+            if (isEssential(args.tool)) {
+                return errorResult({
+                    message: `"${args.tool}" is a FIRST-CLASS tool — it appears directly in tools/list.`,
+                    code: "first_class_tool",
+                    suggestion: `Call "${args.tool}" directly instead of routing it through ` +
+                        "apimapper_advanced_read. This gateway only routes the read-only " +
+                        "advanced tools listed in its description.",
+                    details: { tool: args.tool },
+                });
+            }
+            return errorResult({
+                message: `Unknown read-only advanced tool: "${args.tool}".`,
+                code: "unknown_tool",
+                suggestion: "Pick one of the valid read-only advanced tool names below, or use " +
+                    "apimapper_advanced for write tools.\n\n" +
+                    `Valid read-only advanced tools by domain:\n${renderGroupedList(readNames)}`,
+                details: { valid_tools_by_domain: renderGroupedList(readNames) },
+            });
+        }
+        // Discovery mode — no arguments supplied.
+        if (args.arguments === undefined) {
+            return discoveryResult(args.tool, entry);
+        }
+        // Execution mode — validate against the target's Zod inputSchema.
+        // strict() surfaces unknown keys as Zod issues (parity with the write
+        // gateway's F-LS-06 behaviour).
+        const parsed = z.object(shapeOf(entry)).strict().safeParse(args.arguments);
+        if (!parsed.success) {
+            let expectedSchema;
+            try {
+                expectedSchema = z.toJSONSchema(z.object(shapeOf(entry)));
+            }
+            catch {
+                expectedSchema = { note: "input schema could not be derived" };
+            }
+            return errorResult({
+                message: `Invalid arguments for "${args.tool}".`,
+                code: "invalid_arguments",
+                suggestion: `Call apimapper_advanced_read with { tool: "${args.tool}" } to see ` +
+                    "the expected schema, then retry with corrected arguments.",
+                details: {
+                    issues: parsed.error.issues,
+                    expected_schema: expectedSchema,
+                },
+            });
+        }
+        // Invoke the captured handler with the parsed args + the SAME `extra`,
+        // so progress / elicitation / AbortSignal of the target tool keep
+        // working. A throw is wrapped into a structured errorResult (parity with
+        // the write gateway's DEF-LOW-1 guard).
+        try {
+            return await entry.handler(parsed.data, extra);
+        }
+        catch (e) {
+            return errorResult({
+                message: e instanceof Error ? e.message : String(e),
+                code: "tool_threw",
+                suggestion: "The target tool threw instead of returning a structured error. " +
+                    `Retry via apimapper_advanced_read({ tool: "${args.tool}" }) discovery, ` +
+                    "then re-run with corrected arguments. If it persists, run apimapper_health.",
+                details: { tool: args.tool },
+            });
+        }
+    });
+}
+//# sourceMappingURL=advanced-read-tool.js.map

package/dist/modules/apimapper/gateway/advanced-read-tool.js.map

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

package/dist/modules/apimapper/gateway/advanced-tool.js

@@ -21,123 +21,12 @@
 import { z } from "zod";
 import { creating, errorResult } from "@getimo/mcp-toolkit";
 import { SKILL_TOPICS } from "../get-skill.js";
-// Domains used to group advanced tool names in the description + errors.
-//
-// A4 (Wave-B audit, 2026-06-03): the previous list omitted several real
-// registered name-prefixes (release_*, brandfetch, feedback_*, features_*,
-// health/health_warnings_*, inspect_*, node_snapshot_*, platform_*) so those
-// tools all collapsed into the catch-all "misc" group. Each missing stem is
-// added below so every advanced tool renders under its own named domain.
-//
-// Forward-looking stems (workflow / onboarding / render / yootheme) are kept
-// too: the latter three are currently L1 essentials (never in the advanced
-// registry), but listing their stems means that if any future advanced tool
-// adopts that prefix it groups correctly instead of leaking into "misc".
-//
-// `misc` stays last as the explicit catch-all. `domainOf` matches a stem to a
-// domain by exact match or `${domain}_` prefix, and `groupByDomain` drops any
-// domain with zero tools — so unused stems (e.g. workflow, the legacy
-// `diagnostics` placeholder) cost nothing in the rendered output.
-const DOMAIN_ORDER = [
-    "connection",
-    "credential",
-    "flow",
-    "graph",
-    "library",
-    "license",
-    "settings",
-    "cache",
-    "local_source",
-    "schema",
-    "diagnostics",
-    "release",
-    "brandfetch",
-    "feedback",
-    "features",
-    "health",
-    "inspect",
-    "node_snapshot",
-    "platform",
-    "workflow",
-    "onboarding",
-    "render",
-    "yootheme",
-    "misc",
-];
-/** Maps a tool name to its display domain (the segment after `apimapper_`). */
-function domainOf(toolName) {
-    const stem = toolName.replace(/^apimapper_/, "");
-    for (const domain of DOMAIN_ORDER) {
-        if (stem === domain || stem.startsWith(`${domain}_`))
-            return domain;
-    }
-    return "misc";
-}
-/** Groups tool names by domain, in DOMAIN_ORDER, for stable output. */
-function groupByDomain(toolNames) {
-    const groups = new Map();
-    for (const domain of DOMAIN_ORDER)
-        groups.set(domain, []);
-    for (const name of [...toolNames].sort()) {
-        const domain = domainOf(name);
-        const bucket = groups.get(domain);
-        if (bucket)
-            bucket.push(name);
-    }
-    for (const [domain, names] of groups) {
-        if (names.length === 0)
-            groups.delete(domain);
-    }
-    return groups;
-}
-/** Renders the grouped tool list as readable text (used in description + errors). */
-function renderGroupedList(toolNames) {
-    const groups = groupByDomain(toolNames);
-    const lines = [];
-    for (const [domain, names] of groups) {
-        lines.push(`  ${domain}: ${names.join(", ")}`);
-    }
-    return lines.join("\n");
-}
-/** Reads the captured config's inputSchema as a Zod raw-shape (or empty). */
-function shapeOf(entry) {
-    const schema = entry.config.inputSchema;
-    if (schema && typeof schema === "object")
-        return schema;
-    return {};
-}
-/** Builds the discovery-mode result for a target tool. */
-function discoveryResult(toolName, entry) {
-    const cfg = entry.config;
-    let schema;
-    try {
-        schema = z.toJSONSchema(z.object(shapeOf(entry)));
-    }
-    catch {
-        // A schema that cannot be JSON-projected still yields a usable discovery
-        // payload — the description and annotations carry the rest.
-        schema = { note: "input schema could not be derived" };
-    }
-    const payload = {
-        tool: toolName,
-        description: cfg.description ?? "",
-        inputSchema: schema,
-        annotations: cfg.annotations ?? {},
-    };
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Discovery for ${toolName}\n\n` +
-                    `${cfg.description ?? ""}\n\n` +
-                    `Annotations: ${JSON.stringify(cfg.annotations ?? {})}\n\n` +
-                    `Input schema:\n${JSON.stringify(schema, null, 2)}\n\n` +
-                    `Call apimapper_advanced again with { tool: "${toolName}", arguments: {...} } to run it.`,
-            },
-        ],
-        structuredContent: payload,
-    };
-}
+import { isEssential } from "./essentials.js";
+// F200b — the domain grouping + discovery machinery is shared with the
+// read-only sibling gateway (apimapper_advanced_read). It lives in
+// gateway-shared.ts so the two surfaces render identical groupings and can
+// never drift.
+import { groupByDomain, renderGroupedList, shapeOf, discoveryResult, } from "./gateway-shared.js";
 /** Builds the gateway tool's description, grouping every advanced tool by domain. */
 function buildDescription(toolNames) {
     const toolCount = toolNames.length;
@@ -150,6 +39,11 @@ function buildDescription(toolNames) {
     // the LLM size the gateway at-a-glance before scanning the grouped list.
     return (`Routes to ${toolCount} advanced API Mapper tools across ${domainCount} ` +
         `domain${domainCount === 1 ? "" : "s"} (${domainList}). ` +
+        // F214: stop the model habitually routing first-class tools through the
+        // gateway (a wasted invalid_arguments cycle each time). State the scope
+        // boundary up front, before the grouped-tool list.
+        "ONLY for the advanced tools listed below — every tool that appears " +
+        "directly in tools/list is FIRST-CLASS: call it directly, never via this gateway. " +
         "Call with { tool } for a target's schema + annotations, or " +
         "{ tool, arguments } to run it. The target tool's own confirmation " +
         "guards and behavior stay in effect.\n\n" +
@@ -168,25 +62,27 @@ function buildDescription(toolNames) {
  */
 export function registerAdvancedTool(realServer, advancedRegistry) {
     const advancedNames = [...advancedRegistry.keys()].sort();
-    // z.enum needs a non-empty tuple. In production the advanced registry
-    // always holds the captured advanced tools, so the empty-registry arm is
-    // exercised only by test wiring with a zero-tool registry; it is kept as a
-    // defensive guard so a future zero-tool wiring still yields a valid
-    // (if inert) gateway schema rather than a z.enum construction crash.
-    // F-1.3 (Pass-1 consolidation): the `__none__` placeholder is now covered
-    // by a real assertion in gateway/advanced-tool.test.ts — the previous
-    // v8-ignore directive has been removed.
-    const enumValues = advancedNames.length > 0
-        ? advancedNames
-        : ["__none__"];
     realServer.registerTool("apimapper_advanced", {
         title: "Advanced Tool Gateway",
         description: buildDescription(advancedNames),
         inputSchema: {
+            // F205 (P2): `tool` is a free string, NOT a z.enum. The MCP SDK
+            // validates the gateway inputSchema BEFORE our handler runs; an enum
+            // rejected every first-class tool name (apimapper_health,
+            // apimapper_flow_full_recompile_publish, ...) with a raw McpError
+            // -32602, so the friendly first_class_tool / unknown_tool steering in
+            // the handler NEVER ran. A plain string lets every name reach the
+            // handler, which routes it: advanced → run; first-class → "call it
+            // directly"; unknown → grouped suggestion. renderGroupedList in the
+            // description stays the load-bearing discovery surface.
             tool: z
-                .enum(enumValues)
+                .string()
                 .describe('Advanced tool to route to (e.g. "apimapper_flow_get"). ' +
-                "Omit `arguments` to discover its schema first."),
+                "Must be one of the advanced tools listed in this gateway's " +
+                "description — first-class tools (apimapper_health, " +
+                "apimapper_flow_setup_with_sources, ...) are called DIRECTLY, " +
+                "not through this gateway. Omit `arguments` to discover its " +
+                "schema first."),
             arguments: z
                 .record(z.string(), z.unknown())
                 .optional()
@@ -197,6 +93,19 @@ export function registerAdvancedTool(realServer, advancedRegistry) {
     }, async (args, extra) => {
         const entry = advancedRegistry.get(args.tool);
         if (!entry) {
+            // F205: a name that is a first-class tool (in tools/list directly)
+            // is a different error than a typo. Steer the caller to call it
+            // directly instead of routing through the gateway.
+            if (isEssential(args.tool)) {
+                return errorResult({
+                    message: `"${args.tool}" is a FIRST-CLASS tool — it appears directly in tools/list.`,
+                    code: "first_class_tool",
+                    suggestion: `Call "${args.tool}" directly instead of routing it through ` +
+                        "apimapper_advanced. This gateway only routes the advanced " +
+                        "(non-essential) tools listed in its description.",
+                    details: { tool: args.tool },
+                });
+            }
             return errorResult({
                 message: `Unknown advanced tool: "${args.tool}".`,
                 code: "unknown_tool",

package/dist/modules/apimapper/gateway/advanced-tool.js.map

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

package/dist/modules/apimapper/gateway/collect-module-tools.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { ApimapperRestModule } from "../index.js";
+/** A tool entry as seen by tests: handler + the registered config. */
+export interface CollectedTool {
+    handler: (args: Record<string, unknown>, extra?: unknown) => CallToolResult | Promise<CallToolResult>;
+    title?: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: Record<string, unknown>;
+}
+/**
+ * Returns every API Mapper tool — the essentials registered on the real
+ * McpServer plus the advanced tools captured in the gateway registry —
+ * keyed by tool name. `module.register(server)` must have run first.
+ */
+export declare function collectModuleTools(server: McpServer, module: ApimapperRestModule): Record<string, CollectedTool>;

package/dist/modules/apimapper/gateway/collect-module-tools.js

@@ -0,0 +1,44 @@
+// src/modules/apimapper/gateway/collect-module-tools.ts — unified tool view
+//
+// After the W3.4 Gateway-Hub, advanced (non-essential) tools no longer live
+// in McpServer._registeredTools — they are captured into the advanced
+// registry behind `apimapper_advanced`. `collectModuleTools` returns a unified
+// view of every tool (essentials on the real server + advanced from the
+// registry), keeping lookup semantics identical to the pre-gateway behaviour.
+//
+// Used by tests (via test-support.ts re-export) AND by the build/release path
+// (catalog/build-catalog.ts, toolslist-size.ts), so it lives in its own
+// non-test module — it is NOT a test-only helper.
+/**
+ * Returns every API Mapper tool — the essentials registered on the real
+ * McpServer plus the advanced tools captured in the gateway registry —
+ * keyed by tool name. `module.register(server)` must have run first.
+ */
+export function collectModuleTools(server, module) {
+    const result = {};
+    const realTools = server._registeredTools;
+    for (const [name, tool] of Object.entries(realTools)) {
+        result[name] = {
+            handler: tool.handler,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        };
+    }
+    const advanced = module.getAdvancedRegistry();
+    if (advanced) {
+        for (const [name, entry] of advanced) {
+            const cfg = entry.config;
+            result[name] = {
+                handler: entry.handler,
+                title: cfg.title,
+                description: cfg.description,
+                inputSchema: cfg.inputSchema,
+                annotations: cfg.annotations,
+            };
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=collect-module-tools.js.map

package/dist/modules/apimapper/gateway/collect-module-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-module-tools.js","sourceRoot":"","sources":["../../../../src/modules/apimapper/gateway/collect-module-tools.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,4EAA4E;AAC5E,sEAAsE;AACtE,+EAA+E;AAC/E,wEAAwE;AACxE,8EAA8E;AAC9E,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,kDAAkD;AA0BlD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,MAA2B;IAE3B,MAAM,MAAM,GAAkC,EAAE,CAAC;IAEjD,MAAM,SAAS,GACb,MACD,CAAC,gBAAgB,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,MAAM,CAAC,IAAI,CAAC,GAAG;YACb,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC9C,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YACrC,MAAM,GAAG,GAAG,KAAK,CAAC,MAKjB,CAAC;YACF,MAAM,CAAC,IAAI,CAAC,GAAG;gBACb,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;aAC7B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/modules/apimapper/gateway/essentials.d.ts

@@ -1,4 +1,4 @@
 /** Tools kept as first-class entries in tools/list (Cursor-cap-safe surface). */
-export declare const ESSENTIAL_TOOLS: readonly ["apimapper_onboarding", "apimapper_diagnose", "apimapper_list_profiles", "apimapper_use_profile", "apimapper_library_featured", "apimapper_library_list", "apimapper_library_activate", "apimapper_connection_list", "apimapper_connection_create", "apimapper_connection_data", "apimapper_credential_list", "apimapper_oauth_authorize_begin", "apimapper_flow_setup_with_sources", "apimapper_flow_full_recompile_publish", "apimapper_yootheme_binding_for_flow", "apimapper_render", "apimapper_get_skill"];
+export declare const ESSENTIAL_TOOLS: readonly ["apimapper_onboarding", "apimapper_diagnose", "apimapper_list_profiles", "apimapper_use_profile", "apimapper_library_featured", "apimapper_library_list", "apimapper_library_activate", "apimapper_health", "apimapper_connection_list", "apimapper_connection_create", "apimapper_connection_data", "apimapper_credential_list", "apimapper_oauth_authorize_begin", "apimapper_flow_setup_with_sources", "apimapper_flow_full_recompile_publish", "apimapper_yootheme_binding_for_flow", "apimapper_render", "apimapper_get_skill"];
 export type EssentialTool = (typeof ESSENTIAL_TOOLS)[number];
 export declare function isEssential(name: string): boolean;

package/dist/modules/apimapper/gateway/essentials.js

@@ -2,13 +2,24 @@
 //
 // Single source of truth for the "essentials" surface: the tools kept as
 // first-class entries in `tools/list`. Cursor caps MCP servers at ~40 tools;
-// the API Mapper adapter has 79 registered tools (16 module-real = 15 module
-// essentials + the apimapper_advanced gateway, + 60 advanced-registry tools,
-// + 3 tools registered directly in src/index.ts), so all but the essentials
-// are routed through the `apimapper_advanced` gateway (see advanced-tool.ts).
-// That keeps the first-class `tools/list` surface at 19 — well under the cap.
-// The canonical counts are asserted live in gateway/gateway.test.ts (A2);
-// this comment cites what that test proves.
+// the API Mapper adapter has 81 registered tools (18 module-real = 16 module
+// essentials + the apimapper_advanced gateway + the apimapper_advanced_read
+// gateway, + 60 advanced-registry tools, + 3 tools registered directly in
+// src/index.ts), so all but the essentials are routed through the gateways
+// (see advanced-tool.ts / advanced-read-tool.ts). That keeps the first-class
+// `tools/list` surface at 21 — well under the cap. The canonical counts are
+// asserted live in gateway/gateway.test.ts (A2); this comment cites what that
+// test proves.
+//
+// F115 (2026-06-11): apimapper_health promoted from the advanced registry to
+// a module-registered essential — the documented "run this first" verify tool
+// was itself only reachable via the gateway (first-call deadend). This shifts
+// module essentials 15→16, advanced 60→59 (total then 79).
+//
+// F200b (2026-06-12): apimapper_advanced_read added as a 2nd module-real
+// gateway — module-real 17→18, surface 20→21, total 80→81. It whitelists the
+// read-only advanced subtools (readOnlyHint-derived) and carries a readOnly
+// annotation so hosts stop prompting on every advanced read.
 /** Tools kept as first-class entries in tools/list (Cursor-cap-safe surface). */
 export const ESSENTIAL_TOOLS = [
     "apimapper_onboarding",
@@ -18,6 +29,7 @@ export const ESSENTIAL_TOOLS = [
     "apimapper_library_featured",
     "apimapper_library_list",
     "apimapper_library_activate",
+    "apimapper_health",
     "apimapper_connection_list",
     "apimapper_connection_create",
     "apimapper_connection_data",

package/dist/modules/apimapper/gateway/essentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"essentials.js","sourceRoot":"","sources":["../../../../src/modules/apimapper/gateway/essentials.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,8EAA8E;AAC9E,0EAA0E;AAC1E,4CAA4C;AAE5C,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,sBAAsB;IACtB,oBAAoB;IACpB,yBAAyB;IACzB,uBAAuB;IACvB,4BAA4B;IAC5B,wBAAwB;IACxB,4BAA4B;IAC5B,2BAA2B;IAC3B,6BAA6B;IAC7B,2BAA2B;IAC3B,2BAA2B;IAC3B,iCAAiC;IACjC,mCAAmC;IACnC,uCAAuC;IACvC,qCAAqC;IACrC,kBAAkB;IAClB,qBAAqB;CACb,CAAC;AAUX,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAQ,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"essentials.js","sourceRoot":"","sources":["../../../../src/modules/apimapper/gateway/essentials.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,0EAA0E;AAC1E,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,eAAe;AACf,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,8EAA8E;AAC9E,2DAA2D;AAC3D,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,6DAA6D;AAE7D,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,sBAAsB;IACtB,oBAAoB;IACpB,yBAAyB;IACzB,uBAAuB;IACvB,4BAA4B;IAC5B,wBAAwB;IACxB,4BAA4B;IAC5B,kBAAkB;IAClB,2BAA2B;IAC3B,6BAA6B;IAC7B,2BAA2B;IAC3B,2BAA2B;IAC3B,iCAAiC;IACjC,mCAAmC;IACnC,uCAAuC;IACvC,qCAAqC;IACrC,kBAAkB;IAClB,qBAAqB;CACb,CAAC;AAUX,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAQ,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/dist/modules/apimapper/gateway/gateway-shared.d.ts

@@ -0,0 +1,21 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ZodRawShape } from "zod";
+import type { AdvancedToolEntry } from "./capturing-server.js";
+export declare const DOMAIN_ORDER: readonly ["connection", "credential", "flow", "graph", "library", "license", "settings", "cache", "local_source", "schema", "diagnostics", "release", "brandfetch", "feedback", "features", "health", "inspect", "node_snapshot", "platform", "workflow", "onboarding", "render", "yootheme", "misc"];
+/** Maps a tool name to its display domain (the segment after `apimapper_`). */
+export declare function domainOf(toolName: string): string;
+/** Groups tool names by domain, in DOMAIN_ORDER, for stable output. */
+export declare function groupByDomain(toolNames: string[]): Map<string, string[]>;
+/** Renders the grouped tool list as readable text (used in description + errors). */
+export declare function renderGroupedList(toolNames: string[]): string;
+/** Reads the captured config's inputSchema as a Zod raw-shape (or empty). */
+export declare function shapeOf(entry: AdvancedToolEntry): ZodRawShape;
+/**
+ * F200b: a registry entry is read-only when its annotation carries
+ * `readOnlyHint === true`. This is the SOLE classifier for the read gateway's
+ * whitelist — derived from the subtool's own annotation, zero per-provider
+ * branching.
+ */
+export declare function isReadOnlyEntry(entry: AdvancedToolEntry): boolean;
+/** Builds the discovery-mode result for a target tool. */
+export declare function discoveryResult(toolName: string, entry: AdvancedToolEntry): CallToolResult;