@wootsup/mcp 0.1.0-rc.9 → 0.3.0

package/dist/modules/apimapper/settings-format.js

@@ -0,0 +1,135 @@
+// src/modules/apimapper/settings-format.ts — W3.1 structuredContent helpers
+//
+// rc.13 Welle 3 (2026-05-20) — extracted from settings.ts when the migration
+// to the toolkit's structuredContent builders added the detail builders for
+// settings_get / features_get and the table shape for health_warnings_list.
+// The tool-registration module (settings.ts) keeps the lean surface; the
+// column constants, detail builders and next-step strings live here —
+// matching connections-format.ts / credentials-format.ts.
+//
+//   - settings_get / features_get → detailResult (display="detail"): a flat
+//     scalar settings/feature dict renders as grouped key-value entries.
+//   - health_warnings_list → tableResult (display="data-table").
+//   - IA-10 (W3.9): every migrated tool carries actionable next-step guidance
+//     in the LLM-readable text (table footer / detail "Next steps" group).
+import { detailResult, } from "@getimo/mcp-toolkit";
+// ── health_warnings_list table shape ──────────────────────────────────
+export const HEALTH_WARNINGS_COLUMNS = [
+    { key: "credentialId", label: "CREDENTIAL_ID", width: 32 },
+    { key: "type", label: "TYPE", width: 28 },
+];
+// IA-10: next-step guidance, kept in the table footer so it is VISIBLE in the
+// LLM-readable text of the warning list.
+export const HEALTH_WARNINGS_NEXT_STEPS = "Next: apimapper_health_warnings_dismiss({ id }) to dismiss a warning · " +
+    "apimapper_credential_get({ id }) to inspect the affected credential.";
+/** health_warnings_list row map: warning item → table row. */
+export function mapHealthWarningRow(w) {
+    return {
+        credentialId: w.credentialId ? String(w.credentialId) : "—",
+        type: w.type ? String(w.type) : "—",
+    };
+}
+/** Coerce a scalar settings value into a detail entry string. */
+function scalarStr(v) {
+    if (v === null || v === undefined)
+        return "—";
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    return String(v);
+}
+/**
+ * Build a structured detail view for settings_get.
+ *
+ * The settings dict is a flat scalar map (cache_ttl, debug_mode, log_level,
+ * …) — each key becomes a detail entry. The active license tier is the
+ * badge; the canonical SETTABLE_KEYS list + next-step calls go into an
+ * IA-10 "Next steps" group so the LLM reads the affordance in the text.
+ */
+export function buildSettingsDetail(tier, settings, settableKeys) {
+    const entries = Object.keys(settings).map((key) => ({
+        key,
+        label: key,
+        value: scalarStr(settings[key]),
+        format: typeof settings[key] === "boolean" ? "boolean" : "text",
+    }));
+    const groups = [];
+    groups.push({
+        label: "Settings",
+        entries: entries.length > 0
+            ? entries
+            : [{ key: "_empty", label: "Settings", value: "no settings returned" }],
+    });
+    groups.push({
+        // IA-10 (W3.9): actionable next steps in a dedicated group.
+        label: "Next steps",
+        entries: [
+            {
+                key: "settable_keys",
+                label: "Settable keys",
+                value: settableKeys.join(", "),
+            },
+            {
+                key: "update",
+                label: "Update",
+                value: "apimapper_settings_update({ patch: { … } }) — only the settable keys above are honored",
+            },
+        ],
+    });
+    return detailResult({
+        title: "API Mapper Settings",
+        subtitle: tier ? `License tier: ${tier}` : undefined,
+        badge: tier
+            ? { text: `tier: ${tier}`, variant: "info" }
+            : { text: "settings", variant: "secondary" },
+        groups,
+    });
+}
+/**
+ * Build a structured detail view for features_get.
+ *
+ * The feature dict mixes booleans (jmespath: true) and numeric limits
+ * (max_connections: -1) — each key becomes a detail entry. The active tier
+ * is the badge; a single IA-10 "Next steps" group points at the license
+ * tools for upgrading a gated feature.
+ */
+export function buildFeaturesDetail(tier, features) {
+    const keys = Object.keys(features);
+    const entries = keys.map((key) => ({
+        key,
+        label: key,
+        value: scalarStr(features[key]),
+        format: typeof features[key] === "boolean" ? "boolean" : "text",
+    }));
+    const groups = [];
+    groups.push({
+        label: "Features",
+        entries: entries.length > 0
+            ? entries
+            : [{ key: "_empty", label: "Features", value: "no features returned" }],
+    });
+    groups.push({
+        label: "Next steps",
+        entries: [
+            {
+                key: "feature_count",
+                label: "Feature count",
+                value: keys.length,
+                format: "text",
+            },
+            {
+                key: "upgrade",
+                label: "Upgrade",
+                value: "A gated feature unlocks with a higher tier — apimapper_license_status to check the current license, apimapper_license_activate to apply a new key.",
+            },
+        ],
+    });
+    return detailResult({
+        title: "License-Gated Features",
+        subtitle: tier ? `License tier: ${tier}` : undefined,
+        badge: tier
+            ? { text: `tier: ${tier}`, variant: "info" }
+            : { text: "features", variant: "secondary" },
+        groups,
+    });
+}
+//# sourceMappingURL=settings-format.js.map

package/dist/modules/apimapper/settings-format.js.map

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

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

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

package/dist/modules/apimapper/settings.js

@@ -1,6 +1,9 @@
 import { z } from "zod";
-import { formatResult, autoFormatTable, readOnly, mutating, destructive, } from "@getimo/mcp-toolkit";
-import { request, hintFor } from "./client.js";
+import { formatResult, tableResult, readOnly, mutating, destructive, } from "@getimo/mcp-toolkit";
+import { request } from "./client.js";
+import { restErrorResult } from "./tool-result.js";
+import { toRows } from "./types.js";
+import { HEALTH_WARNINGS_COLUMNS, HEALTH_WARNINGS_NEXT_STEPS, mapHealthWarningRow, buildSettingsDetail, buildFeaturesDetail, } from "./settings-format.js";
 // SettingsHandler::sanitizeSettingsData (core/src/Admin/Handler/SettingsHandler.php)
 // pins the canonical allow-list. Keep this in sync with that PHP constant.
 const SETTABLE_KEYS = [
@@ -12,6 +15,53 @@ const SETTABLE_KEYS = [
     "delete_data_on_uninstall",
     "error_reporting",
 ];
+// F-18 (W1.11): Strict patch schema — typed per-key, .strict() rejects unknown
+// keys at the Zod boundary so callers see a clear error instead of having
+// keys dropped silently by the server. PHP server-side limits api_timeout to
+// 1..120 (SettingsHandler.php) — surfaced here as int >=1 (upper-bound coerce
+// stays server-side so we don't fail closed if PHP ever widens the cap).
+// log_level intentionally `z.string()` (not enum): PHP accepts any string and
+// existing wire fixtures use values like "warning"/"warn" interchangeably.
+const settingsPatchSchema = z
+    .object({
+    cache_ttl: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Default cache lifetime for connection responses, in seconds (e.g. 3600). 0 disables caching."),
+    debug_mode: z
+        .boolean()
+        .optional()
+        .describe("Admin-UI debug mode: surfaces verbose diagnostics in the API Mapper admin screens."),
+    log_level: z
+        .string()
+        .optional()
+        .describe('Server log verbosity (e.g. "warning", "info", "debug"). Free-form string — PHP accepts any value.'),
+    api_timeout: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Upstream HTTP request timeout in seconds (e.g. 30). Server clamps to 1..120."),
+    server_debug_mode: z
+        .boolean()
+        .optional()
+        .describe("Server-side debug logging: writes detailed request/response traces to the PHP error log."),
+    delete_data_on_uninstall: z
+        .boolean()
+        .optional()
+        .describe("When true, removing the plugin also deletes all API Mapper data (connections, flows, credentials)."),
+    error_reporting: z
+        .boolean()
+        .optional()
+        .describe("Opt-in anonymized error reporting (Sentry) for the plugin."),
+})
+    .strict()
+    .describe("Settings patch (strict allow-list). Unknown keys rejected at schema level. " +
+    "Known SETTABLE_KEYS: " +
+    SETTABLE_KEYS.join(", ") +
+    ". Provide any subset; only changed keys are sent.");
 export function registerSettingsTools(server) {
     // ── apimapper_settings_get ─────────────────────────────────────────
     // F-A6-09: PHP returns `{success, settings, tier}`. Surface tier + settings
@@ -23,20 +73,19 @@ export function registerSettingsTools(server) {
             "server_debug_mode, delete_data_on_uninstall, error_reporting) plus the active license tier." +
             "\n\nExample:\n  apimapper_settings_get({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Get Settings", openWorld: true }),
     }, async () => {
         const r = await request("/settings");
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, {}, { message: "settings get failed" });
         }
         const settings = (r.data?.settings && typeof r.data.settings === "object")
             ? r.data.settings
             : {};
-        return formatResult({
-            tier: r.data?.tier,
-            settings,
-            settable_keys: SETTABLE_KEYS,
-        }, false, { maxChars: 4000 });
+        // W3.1 — detailResult: grouped key-value detail for the Rich Card. The
+        // settings dict is a flat scalar map; IA-10 carries the settable-keys
+        // affordance + the settings_update follow-up in a "Next steps" group.
+        return buildSettingsDetail(r.data?.tier, settings, SETTABLE_KEYS);
     });
     // ── apimapper_settings_update ──────────────────────────────────────
     // F-A6-10: Real allow-list is SETTABLE_KEYS above; telemetry_enabled +
@@ -49,22 +98,17 @@ export function registerSettingsTools(server) {
             "Use apimapper_settings_get to inspect the current full set." +
             "\n\nExample:\n  apimapper_settings_update({ patch: { cache_ttl: 600, debug_mode: true } })",
         inputSchema: {
-            patch: z.record(z.string(), z.unknown()).describe("Settings keys to update (any subset of the allow-list)."),
+            patch: settingsPatchSchema,
         },
-        annotations: mutating(),
+        annotations: mutating({ title: "Update Settings", openWorld: true }),
     }, async ({ patch }) => {
+        const requestedKeys = Object.keys(patch);
         const r = await request("/settings", {
             method: "POST",
             body: JSON.stringify(patch),
         });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { keys: Object.keys(patch) },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { keys: requestedKeys }, { message: "settings update failed" });
         }
         // PHP returns the post-update sanitised settings dict; surface what was
         // actually applied (not what was requested), so the caller can spot
@@ -72,10 +116,17 @@ export function registerSettingsTools(server) {
         const appliedSettings = (r.data?.settings && typeof r.data.settings === "object")
             ? r.data.settings
             : undefined;
+        // F-18 (W1.11): compute server-side dropped keys. With .strict() unknown
+        // keys never reach here, but the server can still drop keys (e.g. a
+        // tier-gated value gets sanitised away). dropped_keys only surfaces when
+        // non-empty so the success envelope stays clean.
+        const appliedKeys = appliedSettings ? Object.keys(appliedSettings) : [];
+        const droppedKeys = requestedKeys.filter((k) => !appliedKeys.includes(k));
         return formatResult({
             updated: true,
-            requested_keys: Object.keys(patch),
+            requested_keys: requestedKeys,
             applied_settings: appliedSettings,
+            ...(droppedKeys.length > 0 ? { dropped_keys: droppedKeys } : {}),
         }, false, { maxChars: 2000 });
     });
     // ── apimapper_settings_reset_demo ──────────────────────────────────
@@ -92,7 +143,7 @@ export function registerSettingsTools(server) {
                 .default(false)
                 .describe("Must be true to execute. Ask user for confirmation first."),
         },
-        annotations: destructive(),
+        annotations: destructive({ title: "Reset Demo Settings", openWorld: true }),
     }, async ({ confirm }) => {
         if (!confirm) {
             return formatResult({
@@ -104,7 +155,7 @@ export function registerSettingsTools(server) {
         }
         const r = await request("/settings/reset-demo", { method: "POST" });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, {}, { message: "demo reset failed" });
         }
         return formatResult({ reset: true, result: r.data?.result }, false, { maxChars: 2000 });
     });
@@ -116,29 +167,39 @@ export function registerSettingsTools(server) {
             "(e.g., 'max_connections: 1'); read each key by its expected type." +
             "\n\nExample:\n  apimapper_features_get({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Get Feature Flags", openWorld: true }),
     }, async () => {
         const r = await request("/features");
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, {}, { message: "features get failed" });
         }
-        const features = r.data?.features ?? {};
-        const featureCount = Object.keys(features).length;
-        return formatResult({ tier: r.data?.tier, feature_count: featureCount, features }, false, { maxChars: 4000 });
+        const features = (r.data?.features && typeof r.data.features === "object")
+            ? r.data.features
+            : {};
+        // W3.1 — detailResult: the feature dict mixes booleans + numeric limits;
+        // each key becomes a scalar detail entry. IA-10 "Next steps" group
+        // points at the license tools for unlocking a gated feature.
+        return buildFeaturesDetail(r.data?.tier, features);
     });
     // ── apimapper_platform_parity ──────────────────────────────────────
     // F-A6-02: PHP PlatformParityHandler returns `{matrix, summary, gaps}` —
     // `wordpress`/`joomla` are nested inside `matrix`, not top-level.
     server.registerTool("apimapper_platform_parity", {
         title: "Get Platform Parity Status",
-        description: "Compare feature parity between WordPress and Joomla versions of API Mapper." +
+        description: "Compare feature parity between the WordPress and Joomla builds of API " +
+            "Mapper and report any gaps. Use before promising a feature works on the " +
+            "user's platform, or when a flow behaves differently on WP vs Joomla. " +
+            "Returns a matrix (per-feature WP/Joomla support), a summary, and a gaps list. " +
+            "Keywords: parity, WordPress vs Joomla, platform differences, feature gaps, cross-platform. " +
+            "When NOT to use: for connectivity/auth checks use apimapper_health; for the " +
+            "feature-flag matrix of the current license tier use apimapper_features_get." +
             "\n\nExample:\n  apimapper_platform_parity({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Check Platform Parity", openWorld: true }),
     }, async () => {
         const r = await request("/platform-parity");
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, {}, { message: "platform parity failed" });
         }
         const gaps = Array.isArray(r.data?.gaps) ? r.data.gaps : [];
         return formatResult({
@@ -156,24 +217,21 @@ export function registerSettingsTools(server) {
         description: "List active admin health-warnings (banners shown in the Admin UI)." +
             "\n\nExample:\n  apimapper_health_warnings_list({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "List Health Warnings", openWorld: true }),
     }, async () => {
         const r = await request("/admin/health-warnings");
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, {}, { message: "health warnings list failed" });
         }
         const items = Array.isArray(r.data?.items) ? r.data.items : [];
         const visible = Boolean(r.data?.visible);
-        return autoFormatTable(items.map((w) => ({
-            credentialId: w.credentialId || "—",
-            type: w.type || "—",
-        })), {
-            columns: [
-                { key: "credentialId", label: "CREDENTIAL_ID", width: 32 },
-                { key: "type", label: "TYPE", width: 28 },
-            ],
+        // W3.1 — tableResult: ASCII table for the LLM + typed DataTable payload
+        // for the Rich Card. IA-10: the footer carries the next-step guidance.
+        return tableResult(toRows(items), {
+            columns: HEALTH_WARNINGS_COLUMNS,
+            map: mapHealthWarningRow,
             header: (n) => `${n} active warnings${visible ? "" : " (banner dismissed)"}`,
-            footer: "Use apimapper_health_warnings_dismiss to dismiss the current set.",
+            footer: HEALTH_WARNINGS_NEXT_STEPS,
         });
     });
     // ── apimapper_health_warnings_dismiss ──────────────────────────────
@@ -184,14 +242,14 @@ export function registerSettingsTools(server) {
         inputSchema: {
             id: z.string().describe("Warning ID. Use apimapper_health_warnings_list to find."),
         },
-        annotations: mutating(),
+        annotations: mutating({ title: "Dismiss Health Warning", openWorld: true }),
     }, async ({ id }) => {
         const r = await request("/admin/health-warnings/dismiss", {
             method: "POST",
             body: JSON.stringify({ id }),
         });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "warning dismiss failed" });
         }
         return formatResult({ dismissed: true, id }, false, { maxChars: 1500 });
     });

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

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

package/dist/modules/apimapper/sites-tools.d.ts

@@ -0,0 +1,29 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SitesRegistry } from "../../sites/loader.js";
+import type { SiteEntryT } from "../../sites/schema.js";
+interface ToolRegistrar {
+    registerTool(name: string, config: unknown, handler: unknown): void;
+}
+export interface SitesIdentityProbeResult {
+    plugin_version: string;
+    plugin_hash: string;
+    capabilities: string[];
+    site_url: string;
+}
+/** Identity probe for the active site. Injected so tests can stub the network. */
+export type SitesProbeIdentityFn = (entry: SiteEntryT) => Promise<SitesIdentityProbeResult>;
+export interface SitesListProfilesDeps {
+    getRegistry: () => SitesRegistry;
+    /** The active site_id pointer, or null when none set (default entry active). */
+    getActiveSiteId: () => string | null;
+}
+export declare function registerSitesListProfilesTool(server: ToolRegistrar | McpServer, deps: SitesListProfilesDeps): void;
+export interface SitesUseProfileDeps {
+    getRegistry: () => SitesRegistry;
+    /** Flip the client's active-site pointer (resets resolution → retargets). */
+    setActiveSite: (id: string) => void;
+    /** Identity probe. Defaults to a real /identity call on the active site. */
+    probeIdentity?: SitesProbeIdentityFn;
+}
+export declare function registerSitesUseProfileTool(server: ToolRegistrar | McpServer, deps: SitesUseProfileDeps): void;
+export {};

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