@wootsup/mcp 0.1.0-rc.9 → 0.1.0

package/README.md

@@ -1,7 +1,7 @@
 # @wootsup/mcp
 
 **Build YOOtheme dynamic content via natural conversation.** The official MCP
-server for [API Mapper](https://wootsup.com/products/api-mapper) — connect
+server for [API Mapper](https://wootsup.com) — connect
 your AI assistant to API Mapper running on WordPress or Joomla, then create
 flows, manage OAuth credentials, and publish sources without leaving the
 chat.
@@ -16,7 +16,7 @@ chat.
 
 Two paths, pick one.
 
-### Option A — `npx` (Claude Code, Cursor, VS Code, Cline, Codex, ChatGPT)
+### Option A — `npx` (Claude Code, Cursor, VS Code, Cline, Codex CLI)
 
 ```bash
 npx -y @wootsup/mcp setup
@@ -46,9 +46,9 @@ subcommands.
 
 1. **Install the API Mapper plugin** on your site:
    - **WordPress:** plugin from
-     [wootsup.com](https://wootsup.com/products/api-mapper)
+     [wootsup.com](https://wootsup.com)
    - **Joomla:** extension from
-     [wootsup.com](https://wootsup.com/products/api-mapper)
+     [wootsup.com](https://wootsup.com)
 2. **Generate an MCP key** in the admin:
    - WordPress: click **API Mapper** in the WP admin menu — the flow
      editor opens. In the editor header (top-right), click the **⋮**
@@ -140,9 +140,9 @@ For the security disclosure process, see [`SECURITY.md`](./SECURITY.md).
 
 ## Links
 
-- **Homepage:** <https://wootsup.com/products/api-mapper>
-- **Plugin (WordPress + Joomla):** <https://wootsup.com/products/api-mapper>
-- **Docs:** <https://wootsup.com/docs/mcp>
+- **Homepage:** <https://wootsup.com>
+- **Plugin (WordPress + Joomla):** <https://wootsup.com> · download from `/downloads`
+- **Docs:** <https://wootsup.com/docs/mcp/>
 - **Issues:** <https://github.com/wootsup/api-mapper/issues>
 - **Architecture:** [`docs/architecture.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/docs/architecture.md)
 - **Security model:** [`docs/security.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/docs/security.md)

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ProfileStore } from "./auth/profiles.js";
 /**
  * Constructs the McpServer with bundled skill instructions wired into the
  * `instructions` field. Extracted as a factory for testability.
@@ -10,4 +11,22 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  */
 export declare function createServer(): McpServer;
 declare const server: McpServer;
+/**
+ * Bootstrap the active-profile pointer from `APIMAPPER_PROFILE` env var.
+ *
+ * F-49 (W1.27) added APIMAPPER_PROFILE to the DXT manifest + setup-cli, but
+ * no runtime consumer existed. A customer with multiple MCP-client entries
+ * declaring different profiles always landed on whichever was setActive
+ * last on disk — defeating the multi-site selection feature.
+ *
+ * Behaviour (A6-P3-INTEG-02 — pinned by index.bootstrap-profile.test.ts):
+ *   - unset / whitespace-only  → no-op (active pointer unchanged)
+ *   - "default"                → no-op (manifest default is the implicit state)
+ *   - "<known profile name>"   → store.setActive(name) is called
+ *   - "<unknown profile name>" → no-op, no throw (avoid phantom profiles)
+ *
+ * Best-effort: any error reading the store is logged + swallowed so the
+ * rest of the MCP surface still boots on a disk-locked or torn-write host.
+ */
+export declare function bootstrapActiveProfile(store: ProfileStore): Promise<void>;
 export { server };

package/dist/index.js

@@ -21,11 +21,31 @@ if (process.env.APIMAPPER_TOKEN && !process.env.APIMAPPER_WP_APP_PASS) {
 if (process.env.APIMAPPER_SITE_URL && !process.env.APIMAPPER_WP_BASE) {
     process.env.APIMAPPER_WP_BASE = process.env.APIMAPPER_SITE_URL;
 }
+// M-9 (2026-05-28) — accept the documented `APIMAPPER_BASE_URL` alias.
+// The original API Mapper docs referred to this variable name; the DXT
+// bundle later standardised on `APIMAPPER_SITE_URL`. Customers who set
+// `APIMAPPER_BASE_URL` (manual setups, custom container images) had
+// their value silently ignored. Bridge it through here so all three
+// names (`APIMAPPER_BASE_URL`, `APIMAPPER_SITE_URL`, `APIMAPPER_WP_BASE`)
+// resolve to the same underlying value. Precedence order:
+// `APIMAPPER_WP_BASE` (legacy canonical) > `APIMAPPER_SITE_URL` (DXT) >
+// `APIMAPPER_BASE_URL` (documentation alias). First-set wins.
+if (process.env.APIMAPPER_BASE_URL && !process.env.APIMAPPER_WP_BASE) {
+    process.env.APIMAPPER_WP_BASE = process.env.APIMAPPER_BASE_URL;
+}
 // APIMAPPER_PLATFORM is consumed by the platform factory once wired
 // (Phase 4 abstraction lands per-tool). Surfaced as a no-op read here so
 // the build-dxt grep gate verifies every user_config key has a runtime
 // consumer — see scripts/build-dxt.js.
 void process.env.APIMAPPER_PLATFORM;
+// APIMAPPER_PROFILE (F-49 / W1.27) — optional profile label for multi-site
+// setups. The setup-cli writes it into the MCP client entry env; the
+// profile-aware tools (apimapper_use_profile / apimapper_list_profiles)
+// consume the underlying ProfileStore. The actual env-var → setActive
+// bridge runs inside main() once the ProfileStore is constructed; see
+// `bootstrapActiveProfile` below for the A6-P3-INTEG-02 wiring + tests.
+void process.env.APIMAPPER_PROFILE;
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { loadModules, formatResult, readOnly } from "@getimo/mcp-toolkit";
 import { apimapperRestModule } from "./modules/apimapper/index.js";
@@ -33,7 +53,13 @@ import { loadSkillInstructions } from "./skill-instructions.js";
 import { connectStdio } from "./transports/stdio.js";
 import { createKeychain } from "./auth/keychain.js";
 import { ProfileStore, resolveConfigDir } from "./auth/profiles.js";
-import { registerUseProfileTool } from "./modules/apimapper/use-profile.js";
+import { registerUseProfileTool, registerListProfilesTool, } from "./modules/apimapper/use-profile.js";
+// Single source of truth for the package version (F-41 / W1.23).
+// Reads ../package.json at runtime so we never drift between the manifest
+// version (used by npm + DXT) and what we advertise to MCP clients.
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const PKG_VERSION = pkg.version;
 /**
  * Constructs the McpServer with bundled skill instructions wired into the
  * `instructions` field. Extracted as a factory for testability.
@@ -45,13 +71,48 @@ import { registerUseProfileTool } from "./modules/apimapper/use-profile.js";
 export function createServer() {
     return new McpServer({
         name: "API Mapper MCP",
-        version: "0.2.0",
+        version: PKG_VERSION,
     }, {
         instructions: loadSkillInstructions(),
     });
 }
 const server = createServer();
 let moduleStatuses = [];
+/**
+ * Bootstrap the active-profile pointer from `APIMAPPER_PROFILE` env var.
+ *
+ * F-49 (W1.27) added APIMAPPER_PROFILE to the DXT manifest + setup-cli, but
+ * no runtime consumer existed. A customer with multiple MCP-client entries
+ * declaring different profiles always landed on whichever was setActive
+ * last on disk — defeating the multi-site selection feature.
+ *
+ * Behaviour (A6-P3-INTEG-02 — pinned by index.bootstrap-profile.test.ts):
+ *   - unset / whitespace-only  → no-op (active pointer unchanged)
+ *   - "default"                → no-op (manifest default is the implicit state)
+ *   - "<known profile name>"   → store.setActive(name) is called
+ *   - "<unknown profile name>" → no-op, no throw (avoid phantom profiles)
+ *
+ * Best-effort: any error reading the store is logged + swallowed so the
+ * rest of the MCP surface still boots on a disk-locked or torn-write host.
+ */
+export async function bootstrapActiveProfile(store) {
+    const desired = process.env.APIMAPPER_PROFILE?.trim();
+    if (!desired || desired === "default")
+        return;
+    try {
+        const all = await store.list();
+        const known = all.some((p) => p.name === desired);
+        if (known) {
+            await store.setActive(desired);
+        }
+        // unknown profile: swallow silently to avoid creating phantom profiles
+        // or surfacing confusing errors on a fresh install where the profile
+        // env var was inherited from a different host.
+    }
+    catch (err) {
+        console.error("[apimapper-rest] APIMAPPER_PROFILE bootstrap skipped — profile store unreadable:", err instanceof Error ? err.message : err);
+    }
+}
 // Root tool: module-loading status. Distinct from `apimapper_health` (which
 // probes connectivity + auth against the live REST surface). Names diverge
 // to avoid agent confusion.
@@ -60,12 +121,12 @@ server.registerTool("apimapper_rest_modules_status", {
     description: "Module-loading status for this MCP adapter (which sub-modules registered cleanly). " +
         "For runtime connectivity + auth checks against the API Mapper REST surface, use apimapper_health.",
     inputSchema: {},
-    annotations: readOnly(),
+    annotations: readOnly({ title: "MCP Modules Status", openWorld: false }),
 }, async () => {
     const ok = moduleStatuses.filter((m) => m.status === "ok").length;
     const failed = moduleStatuses.filter((m) => m.status === "error").length;
     return formatResult({
-        version: "0.2.0",
+        version: PKG_VERSION,
         modules_loaded: ok,
         modules_total: moduleStatuses.length,
         modules_failed: failed,
@@ -90,7 +151,12 @@ async function main() {
         const configDir = resolveConfigDir();
         const keychain = await createKeychain({ configDir });
         const profileStore = new ProfileStore(configDir);
+        // A6-P3-INTEG-02: honour APIMAPPER_PROFILE env var. Must run AFTER the
+        // ProfileStore is constructed but BEFORE the tools register so any
+        // subsequent tool call sees the corrected active pointer.
+        await bootstrapActiveProfile(profileStore);
         registerUseProfileTool(server, { store: profileStore, keychain });
+        registerListProfilesTool(server, { store: profileStore, keychain });
     }
     catch (err) {
         console.error("[apimapper-rest] use-profile tool disabled — keychain/profile init failed:", err instanceof Error ? err.message : err);
@@ -102,7 +168,7 @@ async function main() {
     });
     await connectStdio(server);
     const ok = moduleStatuses.filter((m) => m.status === "ok").length;
-    console.error(`[apimapper-rest] MCP Server v0.2.0 running — ${ok}/${moduleStatuses.length} modules loaded`);
+    console.error(`[apimapper-rest] MCP Server v${PKG_VERSION} running — ${ok}/${moduleStatuses.length} modules loaded`);
 }
 // ── Subcommand dispatch (Phase 6 setup CLI integration) ──────────────
 // AI clients invoke `apimapper-mcp` with stdio piped and no subcommand;

package/dist/index.js.map

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

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

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

package/dist/modules/apimapper/cache.js

@@ -1,6 +1,14 @@
 import { z } from "zod";
-import { formatResult, readOnly, mutating } from "@getimo/mcp-toolkit";
+import { formatResult, statsResult, errorResult, readOnly, destructive, } from "@getimo/mcp-toolkit";
 import { request, hintFor } from "./client.js";
+// rc.13 Welle 3 (2026-05-20) — cache_stats migrated to the toolkit's
+// statsResult builder; both tools' error branches upgraded to errorResult.
+// The migration is purely additive (text `content` block preserved, `_meta.ui`
+// added). cache_stats' headline metrics (hits / misses / hit_rate / storage /
+// window / rt_avoidance) become the statsResult `stats[]`; the per-tier
+// breakdown + the (W1.15-capped) top_keys list move into the statsResult
+// `description` text so the LLM still reads them. cache_invalidate keeps its
+// formatResult success payload — a small confirmation.
 // F-A6-07: canonical PHP enum from CacheInvalidateController::scopeToEvent.
 // Legacy aliases (`flow`, `connection`, `credential`, `user`) are accepted
 // by Wave 1B PHP but the dotted form is the documented contract.
@@ -12,6 +20,9 @@ const CACHE_INVALIDATE_SCOPES = [
     "user.refresh",
     "user.fetch_data",
 ];
+// W1.15 (F-27): cap top_keys envelope size — PHP can return arbitrary
+// counts but the MCP response stays bounded for AI-client legibility.
+const CACHE_STATS_TOP_KEYS_CAP = 20;
 export function registerCacheTools(server) {
     // ── apimapper_cache_invalidate ─────────────────────────────────────
     server.registerTool("apimapper_cache_invalidate", {
@@ -33,20 +44,22 @@ export function registerCacheTools(server) {
                 .optional()
                 .describe("Event-specific payload (see scope description for required keys)."),
         },
-        annotations: mutating(),
+        // W1.26 (IA-1): cache_invalidate evicts state (destructive), not idempotent
+        // re-write of same payload. Aligns with the rest of the destructive() family
+        // (connection_delete, flow_delete, library_deactivate, ...).
+        annotations: destructive({ title: "Invalidate Admin Cache", openWorld: false }),
     }, async ({ scope, payload }) => {
         const body = { scope };
         if (payload)
             body.payload = payload;
         const r = await request("/cache/admin/invalidate", { method: "POST", body: JSON.stringify(body) });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { scope, payload_keys: payload ? Object.keys(payload) : [] },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return errorResult({
+                message: r.error ?? "cache invalidation failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: { scope, payload_keys: payload ? Object.keys(payload) : [] },
+            });
         }
         const ok = r.data?.ok === true;
         return formatResult({
@@ -62,14 +75,20 @@ export function registerCacheTools(server) {
     // events.
     server.registerTool("apimapper_cache_stats", {
         title: "Get Cache Stats",
-        description: "Fetch cache observability stats (per-tier hits/misses, storage size, invalidation events)." +
+        description: "Fetch cache observability stats (per-tier hits/misses, storage size, invalidation events, " +
+            `top_keys capped at ${CACHE_STATS_TOP_KEYS_CAP}).` +
             "\n\nExample:\n  apimapper_cache_stats({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Get Cache Stats", openWorld: false }),
     }, async () => {
         const r = await request("/cache-stats");
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return errorResult({
+                message: r.error ?? "cache stats failed",
+                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
+                suggestion: hintFor(r.errorCode),
+                details: {},
+            });
         }
         const tiers = r.data?.tiers ?? {};
         const admin = tiers.admin ?? {};
@@ -82,20 +101,83 @@ export function registerCacheTools(server) {
         const totalMisses = adminMisses + renderMisses;
         const denom = totalHits + totalMisses;
         const hitRate = denom > 0 ? `${((totalHits / denom) * 100).toFixed(1)}%` : "n/a";
-        return formatResult({
-            timestamp: r.data?.timestamp,
-            hits: totalHits,
-            misses: totalMisses,
-            hit_rate: hitRate,
-            tiers: {
-                admin: { hits: adminHits, misses: adminMisses, sets: admin.sets ?? 0 },
-                render: { hits: renderHits, misses: renderMisses, sets: render.sets ?? 0 },
+        // W3.1 — statsResult: every metric becomes a flat `stats[]` entry so it
+        // is BOTH LLM-visible (rendered as text by statsResult) and structured
+        // for the StatsDisplay card. The headline metrics, the per-tier
+        // breakdown, storage and the (W1.15-capped) top_keys all render as stat
+        // entries — statsResult.stats[] holds flat scalars, and the top_keys
+        // list is joined into a single string-valued stat.
+        const storage = r.data?.storage;
+        const topKeys = Array.isArray(r.data?.top_keys)
+            ? r.data.top_keys.slice(0, CACHE_STATS_TOP_KEYS_CAP)
+            : [];
+        const stats = [
+            { key: "hits", label: "Hits", value: totalHits, format: "number" },
+            { key: "misses", label: "Misses", value: totalMisses, format: "number" },
+            { key: "hit_rate", label: "Hit rate", value: hitRate },
+            {
+                key: "admin_tier",
+                label: "Tier admin",
+                value: `${adminHits} hits / ${adminMisses} misses / ${admin.sets ?? 0} sets`,
+            },
+            {
+                key: "render_tier",
+                label: "Tier render",
+                value: `${renderHits} hits / ${renderMisses} misses / ${render.sets ?? 0} sets`,
             },
-            storage: r.data?.storage,
-            invalidation: r.data?.invalidation,
-            window_seconds: r.data?.window_seconds,
-            rt_avoidance_ms_p50: r.data?.rt_avoidance_ms_p50,
-        }, false, { maxChars: 3000 });
+        ];
+        if (storage && typeof storage.entries === "number") {
+            stats.push({
+                key: "storage_entries",
+                label: "Storage entries",
+                value: storage.entries,
+                format: "number",
+            });
+        }
+        if (storage && typeof storage.bytes === "number") {
+            stats.push({
+                key: "storage_bytes",
+                label: "Storage bytes",
+                value: storage.bytes,
+                format: "number",
+            });
+        }
+        if (typeof r.data?.window_seconds === "number") {
+            stats.push({
+                key: "window_seconds",
+                label: "Window (s)",
+                value: r.data.window_seconds,
+                format: "number",
+            });
+        }
+        if (typeof r.data?.rt_avoidance_ms_p50 === "number") {
+            stats.push({
+                key: "rt_avoidance_ms_p50",
+                label: "RT avoidance p50 (ms)",
+                value: r.data.rt_avoidance_ms_p50,
+                format: "number",
+            });
+        }
+        if (r.data?.invalidation && typeof r.data.invalidation === "object") {
+            stats.push({
+                key: "invalidation",
+                label: "Invalidation",
+                value: JSON.stringify(r.data.invalidation),
+            });
+        }
+        if (topKeys.length > 0) {
+            stats.push({
+                key: "top_keys",
+                label: `Top keys (capped ${CACHE_STATS_TOP_KEYS_CAP})`,
+                value: topKeys.map((k) => String(k)).join(", "),
+            });
+        }
+        return statsResult({
+            title: "Cache Stats",
+            description: "Per-tier cache observability — hit/miss counters, storage size, " +
+                "invalidation throughput and the hottest keys.",
+            stats,
+        });
     });
 }
 //# sourceMappingURL=cache.js.map

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

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

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

@@ -1,6 +1,36 @@
 import { type ApiResponse } from "@getimo/mcp-toolkit";
 import { type Platform } from "../../platform/index.js";
+/**
+ * WordPress / Joomla site base URL.
+ *
+ * Env-var precedence: `APIMAPPER_WP_BASE` → `APIMAPPER_SITE_URL` (alias
+ * written by the DXT setup wizard) → empty string.
+ *
+ * The SITE_URL → WP_BASE bridge is handled exactly once, above, via
+ * `process.env.APIMAPPER_WP_BASE = process.env.APIMAPPER_SITE_URL`. This
+ * keeps a single source of truth in `process.env` so any consumer
+ * (including child processes spawned later, R7 verify scripts, and
+ * legacy CustomGraph internal code) sees the same value — not just
+ * this module's exported `WP_BASE` constant.
+ *
+ * Empty default is intentional (F-43, 2026-05-19): a freshly-installed
+ * customer who has not run the setup wizard must NOT silently inherit
+ * the WootsUp dev URL — that leaked the vendor's setup hostname into
+ * customer error logs and confused triage. In production (NODE_ENV
+ * === "production") an empty value causes a fail-fast exit below.
+ *
+ * Trailing slash is normalised away so downstream `${WP_BASE}/...` joins
+ * never produce double-slashes.
+ */
 export declare const WP_BASE: string;
+/**
+ * WordPress username for legacy Application-Password Basic auth.
+ *
+ * Empty default is intentional (F-44, 2026-05-19): the previous "getimo"
+ * default leaked a personal username into customer 401 logs. Customers
+ * using the modern Bearer-token flow (`amk_live_...`) don't need this
+ * value at all; legacy users must set `APIMAPPER_WP_USER` explicitly.
+ */
 export declare const WP_USER: string;
 export declare const WP_APP_PASS: string;
 /**
@@ -21,6 +51,15 @@ export interface ExtApiResponse<T = unknown> extends ApiResponse<T> {
     errorCode?: ApiErrorCode;
     /** When true, response was 2xx but payload had `success: false` — semantically failed. */
     payloadFailed?: boolean;
+    /**
+     * W2-3 (H-3, 2026-05-28): the parsed JSON body when the server returned a
+     * non-2xx response. Carries domain-specific fields like
+     * `compiler_error_code` (FlowHandler::compile) that the caller-side autofix
+     * branches on. `undefined` when the error response wasn't JSON, or when the
+     * call succeeded. Do NOT use as a "did the request succeed" check;
+     * `success` is the source of truth for that.
+     */
+    errorBody?: Record<string, unknown>;
 }
 interface RequestOpts {
     /**
@@ -65,6 +104,7 @@ export interface PlatformClient {
  * All errors are sanitised via `sanitizeErrorString()` before being returned.
  */
 export declare function createPlatformClient(platform: Platform): PlatformClient;
+export declare const PLATFORM_KIND: "wordpress" | "joomla";
 /**
  * Issue a request through the toolkit HTTP client + capture HTTP status.
  *