@wootsup/mcp 0.1.0-rc.1

package/dist/skill-instructions.js

@@ -0,0 +1,68 @@
+// src/skill-instructions.ts — Reads the bundled apimapper skill's SKILL.md
+// and returns the body (post-frontmatter) truncated to 500 chars, for use
+// as the McpServer `instructions` field.
+//
+// Falls back to a one-line default if the file is missing or unreadable.
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+export const FALLBACK_INSTRUCTIONS = "Use this MCP to manage API Mapper flows, connections, and sources across WordPress + Joomla.";
+const MAX_LENGTH = 500;
+/**
+ * Loads MCP server instructions from skills/apimapper/SKILL.md.
+ *
+ * @param rootDir - Override the package root directory (used by tests).
+ *                  Defaults to the directory two levels up from this file
+ *                  (i.e. the package root), so that `skills/apimapper/SKILL.md`
+ *                  resolves correctly both in dev (src/) and in build (dist/).
+ */
+export function loadSkillInstructions(rootDir) {
+    const baseDir = rootDir ?? defaultRoot();
+    const skillPath = join(baseDir, "skills", "apimapper", "SKILL.md");
+    if (!existsSync(skillPath)) {
+        return FALLBACK_INSTRUCTIONS;
+    }
+    let raw;
+    try {
+        raw = readFileSync(skillPath, "utf8");
+    }
+    catch {
+        return FALLBACK_INSTRUCTIONS;
+    }
+    const body = stripFrontmatter(raw).trim();
+    if (body.length === 0) {
+        return FALLBACK_INSTRUCTIONS;
+    }
+    return body.slice(0, MAX_LENGTH);
+}
+/**
+ * Strips a YAML frontmatter block (`---\n...\n---\n`) from the start of the
+ * input. Returns the original string if no frontmatter is detected.
+ *
+ * Tiny inline parser — gray-matter would pull in dependencies we don't need.
+ */
+function stripFrontmatter(input) {
+    if (!input.startsWith("---")) {
+        return input;
+    }
+    // Find the closing fence. Must be at line start.
+    const closing = input.indexOf("\n---", 3);
+    if (closing < 0) {
+        return input;
+    }
+    // Advance past the closing fence and the newline that follows it.
+    const after = input.indexOf("\n", closing + 4);
+    if (after < 0) {
+        // Closing fence is the last line; return empty body.
+        return "";
+    }
+    return input.slice(after + 1);
+}
+function defaultRoot() {
+    // This file lives at <pkg-root>/src/skill-instructions.ts (or
+    // <pkg-root>/dist/skill-instructions.js after build). In both cases,
+    // the package root is one directory up.
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "..");
+}
+//# sourceMappingURL=skill-instructions.js.map

package/dist/skill-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-instructions.js","sourceRoot":"","sources":["../src/skill-instructions.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0EAA0E;AAC1E,yCAAyC;AACzC,EAAE;AACF,yEAAyE;AAEzE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,CAAC,MAAM,qBAAqB,GAChC,8FAA8F,CAAC;AAEjG,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,MAAM,OAAO,GAAG,OAAO,IAAI,WAAW,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;IAEnE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IAED,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,iDAAiD;IACjD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC1C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,kEAAkE;IAClE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IAC/C,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,qDAAqD;QACrD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,WAAW;IAClB,8DAA8D;IAC9D,qEAAqE;IACrE,wCAAwC;IACxC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/transports/http.d.ts

@@ -0,0 +1,29 @@
+import { type Server } from "node:http";
+import type { OAuthProvider } from "../auth/oauth-provider.js";
+export interface HttpAuthInfo {
+    client_id: string;
+    scope: string;
+}
+export type McpHandler = (body: unknown, authInfo: HttpAuthInfo | null) => Promise<unknown>;
+export interface HttpTransportOptions {
+    /** TCP port to bind. Use 0 for an ephemeral port. */
+    port: number;
+    /** OAuth provider state — typically a singleton per process. */
+    oauth: OAuthProvider;
+    /** MCP routing callback. Receives parsed JSON body + auth info. */
+    mcpHandler: McpHandler;
+    /**
+     * Public base URL used in OAuth metadata. Default: derived from the
+     * bound address (`http://127.0.0.1:<port>`).
+     */
+    publicBaseUrl?: string;
+}
+export interface HttpTransportServer {
+    /** http.Server instance. */
+    server: Server;
+    /** Resolved base URL (with port). */
+    url: string;
+    /** Stop accepting new connections + close existing keep-alives. */
+    close(): Promise<void>;
+}
+export declare function createHttpTransportServer(options: HttpTransportOptions): Promise<HttpTransportServer>;

package/dist/transports/http.js

@@ -0,0 +1,267 @@
+// src/transports/http.ts — Phase 9.2.
+//
+// Native node:http server that exposes:
+//
+//   GET  /health                                — readiness probe
+//   GET  /.well-known/oauth-authorization-server — RFC 8414 metadata
+//   POST /register                              — RFC 7591 Dynamic Client Registration
+//   GET  /authorize                             — OAuth 2.0 Authorization endpoint
+//   POST /token                                 — OAuth 2.0 Token endpoint
+//   POST /mcp                                   — MCP JSON-RPC (Bearer-gated)
+//
+// The MCP routing is intentionally pluggable via the `mcpHandler` callback:
+// this file is responsible ONLY for HTTP framing + OAuth auth. The boot
+// entry `src/server-http.ts` glues this transport to a real MCP server by
+// supplying a handler that uses the SDK's StreamableHTTPServerTransport.
+//
+// Why hand-rolled HTTP instead of Express? We already have @modelcontextprotocol/sdk
+// + zod + clack as runtime deps; adding Express would balloon the DXT bundle
+// for ~50 lines of routing logic we own outright.
+import { createServer as createHttpServer } from "node:http";
+// ── Helpers ────────────────────────────────────────────────────────────
+function send(res, status, body, extraHeaders = {}) {
+    const payload = typeof body === "string" ? body : JSON.stringify(body);
+    res.writeHead(status, {
+        "content-type": typeof body === "string" ? "text/plain; charset=utf-8" : "application/json",
+        "content-length": String(Buffer.byteLength(payload)),
+        ...extraHeaders,
+    });
+    res.end(payload);
+}
+function sendError(res, status, error, description) {
+    const body = { error };
+    if (description)
+        body.error_description = description;
+    send(res, status, body);
+}
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function parseJson(raw) {
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function getBearer(req) {
+    const hdr = req.headers["authorization"];
+    if (typeof hdr !== "string")
+        return null;
+    const m = /^Bearer\s+(.+)$/i.exec(hdr);
+    return m ? m[1] : null;
+}
+// ── Factory ────────────────────────────────────────────────────────────
+export async function createHttpTransportServer(options) {
+    const { oauth, mcpHandler } = options;
+    // We compute the public base URL lazily — for port: 0 we need it after
+    // listen() resolves.
+    let publicBaseUrl = options.publicBaseUrl ?? "";
+    const server = createHttpServer(async (req, res) => {
+        try {
+            await handle(req, res);
+        }
+        catch (err) {
+            // Never let the listener throw — surface as a 500 with a sanitized body.
+            const msg = err instanceof Error ? err.message : "unknown_error";
+            sendError(res, 500, "server_error", msg);
+        }
+    });
+    async function handle(req, res) {
+        const url = new URL(req.url ?? "/", publicBaseUrl || "http://127.0.0.1");
+        const path = url.pathname;
+        const method = (req.method ?? "GET").toUpperCase();
+        // ── /health ──────────────────────────────────────────────────────
+        if (path === "/health" && method === "GET") {
+            send(res, 200, { status: "ok", transport: "http" });
+            return;
+        }
+        // ── /.well-known/oauth-authorization-server ──────────────────────
+        if (path === "/.well-known/oauth-authorization-server" &&
+            method === "GET") {
+            send(res, 200, {
+                issuer: publicBaseUrl,
+                authorization_endpoint: `${publicBaseUrl}/authorize`,
+                token_endpoint: `${publicBaseUrl}/token`,
+                registration_endpoint: `${publicBaseUrl}/register`,
+                response_types_supported: ["code"],
+                grant_types_supported: ["authorization_code", "refresh_token"],
+                code_challenge_methods_supported: ["S256"],
+                token_endpoint_auth_methods_supported: ["none"],
+                scopes_supported: ["read", "write", "admin"],
+            });
+            return;
+        }
+        // ── POST /register (RFC 7591 DCR) ────────────────────────────────
+        if (path === "/register" && method === "POST") {
+            const raw = await readBody(req);
+            const body = parseJson(raw);
+            if (body === null || typeof body !== "object") {
+                sendError(res, 400, "invalid_client_metadata", "body must be JSON");
+                return;
+            }
+            const b = body;
+            const redirectUris = Array.isArray(b.redirect_uris)
+                ? b.redirect_uris.filter((u) => typeof u === "string")
+                : [];
+            const clientName = typeof b.client_name === "string" ? b.client_name : undefined;
+            try {
+                const reg = oauth.registerClient({
+                    redirect_uris: redirectUris,
+                    client_name: clientName,
+                });
+                send(res, 201, reg);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : "invalid_client_metadata";
+                sendError(res, 400, "invalid_client_metadata", msg);
+            }
+            return;
+        }
+        // ── GET /authorize ───────────────────────────────────────────────
+        if (path === "/authorize" && method === "GET") {
+            const q = url.searchParams;
+            const clientId = q.get("client_id") ?? "";
+            const redirectUri = q.get("redirect_uri") ?? "";
+            const responseType = q.get("response_type") ?? "";
+            const codeChallenge = q.get("code_challenge") ?? "";
+            const codeChallengeMethod = q.get("code_challenge_method") ?? "";
+            const scope = q.get("scope") ?? "";
+            const state = q.get("state") ?? undefined;
+            if (responseType !== "code") {
+                sendError(res, 400, "unsupported_response_type");
+                return;
+            }
+            const client = oauth.getClient(clientId);
+            if (!client) {
+                sendError(res, 400, "unknown_client");
+                return;
+            }
+            if (!client.redirect_uris.includes(redirectUri)) {
+                sendError(res, 400, "invalid_redirect_uri");
+                return;
+            }
+            if (codeChallengeMethod !== "S256") {
+                sendError(res, 400, "invalid_request", "code_challenge_method must be S256");
+                return;
+            }
+            let code;
+            try {
+                code = oauth.issueCode({
+                    client_id: clientId,
+                    redirect_uri: redirectUri,
+                    code_challenge: codeChallenge,
+                    code_challenge_method: "S256",
+                    scope,
+                    state,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : "invalid_request";
+                sendError(res, 400, "invalid_request", msg);
+                return;
+            }
+            const cbUrl = new URL(redirectUri);
+            cbUrl.searchParams.set("code", code);
+            if (state !== undefined)
+                cbUrl.searchParams.set("state", state);
+            res.writeHead(302, { location: cbUrl.toString() });
+            res.end();
+            return;
+        }
+        // ── POST /token ──────────────────────────────────────────────────
+        if (path === "/token" && method === "POST") {
+            const raw = await readBody(req);
+            const params = new URLSearchParams(raw);
+            const grantType = params.get("grant_type") ?? "";
+            try {
+                if (grantType === "authorization_code") {
+                    const tokens = oauth.exchangeCode({
+                        client_id: params.get("client_id") ?? "",
+                        code: params.get("code") ?? "",
+                        redirect_uri: params.get("redirect_uri") ?? "",
+                        code_verifier: params.get("code_verifier") ?? "",
+                    });
+                    send(res, 200, tokens);
+                    return;
+                }
+                if (grantType === "refresh_token") {
+                    const tokens = oauth.refreshToken({
+                        client_id: params.get("client_id") ?? "",
+                        refresh_token: params.get("refresh_token") ?? "",
+                    });
+                    send(res, 200, tokens);
+                    return;
+                }
+                sendError(res, 400, "unsupported_grant_type");
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : "invalid_grant";
+                sendError(res, 400, "invalid_grant", msg);
+            }
+            return;
+        }
+        // ── POST /mcp ────────────────────────────────────────────────────
+        if (path === "/mcp" && method === "POST") {
+            const token = getBearer(req);
+            if (!token) {
+                send(res, 401, { error: "unauthorized", error_description: "Bearer token required" }, {
+                    "www-authenticate": `Bearer realm="${publicBaseUrl}", error="invalid_token"`,
+                });
+                return;
+            }
+            const info = oauth.verifyAccessToken(token);
+            if (!info) {
+                send(res, 401, {
+                    error: "invalid_token",
+                    error_description: "Bearer token unknown or expired",
+                }, {
+                    "www-authenticate": `Bearer realm="${publicBaseUrl}", error="invalid_token"`,
+                });
+                return;
+            }
+            const raw = await readBody(req);
+            const body = parseJson(raw);
+            if (body === null) {
+                sendError(res, 400, "invalid_request", "body must be JSON");
+                return;
+            }
+            const result = await mcpHandler(body, {
+                client_id: info.client_id,
+                scope: info.scope,
+            });
+            send(res, 200, result);
+            return;
+        }
+        // ── 404 fallback ─────────────────────────────────────────────────
+        sendError(res, 404, "not_found", `no route for ${method} ${path}`);
+    }
+    // Bind + resolve base URL
+    await new Promise((resolve) => server.listen(options.port, resolve));
+    const addr = server.address();
+    if (!publicBaseUrl) {
+        publicBaseUrl = `http://127.0.0.1:${addr.port}`;
+    }
+    else if (publicBaseUrl === "http://127.0.0.1" ||
+        publicBaseUrl === "http://localhost") {
+        publicBaseUrl = `${publicBaseUrl}:${addr.port}`;
+    }
+    return {
+        server,
+        url: publicBaseUrl,
+        close: () => new Promise((resolve, reject) => {
+            server.close((err) => (err ? reject(err) : resolve()));
+            // Force-close keep-alive sockets so tests don't hang.
+            server.closeAllConnections?.();
+        }),
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/transports/http.js.map

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

package/dist/transports/stdio.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Connect the given McpServer to a fresh `StdioServerTransport`.
+ *
+ * Resolves once the SDK has finished its handshake. Rejects with the
+ * underlying SDK error if `server.connect()` throws — callers should treat
+ * a rejection as a fatal startup error.
+ */
+export declare function connectStdio(server: McpServer): Promise<void>;

package/dist/transports/stdio.js

@@ -0,0 +1,19 @@
+// src/transports/stdio.ts — Phase 9.1.
+//
+// Thin factory that connects an McpServer to a StdioServerTransport so the
+// process speaks JSON-RPC over stdin/stdout. Extracted from src/index.ts as
+// part of the multi-transport split — Task 9.2 introduces an HTTP variant
+// using the same `connect*` shape.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+/**
+ * Connect the given McpServer to a fresh `StdioServerTransport`.
+ *
+ * Resolves once the SDK has finished its handshake. Rejects with the
+ * underlying SDK error if `server.connect()` throws — callers should treat
+ * a rejection as a fatal startup error.
+ */
+export async function connectStdio(server) {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=stdio.js.map

package/dist/transports/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,0EAA0E;AAC1E,mCAAmC;AAGnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAiB;IAClD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/docs/architecture.md

@@ -0,0 +1,140 @@
+# Architecture
+
+`@wootsup/mcp` is the MCP server side of the API Mapper product.
+This document is intentionally short — for the full design, see the
+internal plan-doc `~/Projekte/getimo/40-Plans/active/
+2026-05-18-apimapper-mcp-implementation-plan.md` (vault, not public).
+
+## System diagram
+
+```
+   ┌──────────────────────────────────────────────────────────────┐
+   │  AI client                                                   │
+   │  (Claude Desktop · Claude Code · Cursor · VS Code · ChatGPT) │
+   └─────────────┬─────────────────────────────────┬──────────────┘
+                 │ stdio                            │ HTTP+OAuth2 PKCE
+                 │ (npx / DXT)                      │ (server-http.ts)
+                 ▼                                  ▼
+   ┌──────────────────────────────────────────────────────────────┐
+   │  @wootsup/mcp (this package)                               │
+   │                                                              │
+   │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐    │
+   │  │ Transport    │→ │  Tool        │→ │  Platform router │    │
+   │  │  stdio /     │  │  registry    │  │  (WP / Joomla)   │    │
+   │  │  HTTP+OAuth  │  │  (~76 tools) │  │                  │    │
+   │  └──────────────┘  └──────────────┘  └──────────────────┘    │
+   │           │              ▲                    │              │
+   │           │              │                    │              │
+   │           ▼              │                    ▼              │
+   │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐    │
+   │  │ Setup CLI    │  │ Bundled      │  │ HTTP client      │    │
+   │  │ (clack)      │  │ skill        │  │ + sanitizer      │    │
+   │  └──────┬───────┘  └──────────────┘  └────────┬─────────┘    │
+   │         │ keychain / profile                  │              │
+   │         ▼                                     │              │
+   │  ┌──────────────┐                             │              │
+   │  │ Keychain     │                             │              │
+   │  │ + Profiles   │                             │              │
+   │  └──────────────┘                             │              │
+   └────────────────────────────────────────────────┼─────────────┘
+                                                    │
+                                                    │ HTTPS + Bearer
+                                                    │ (amk_live_…)
+                                                    ▼
+   ┌──────────────────────────────────────────────────────────────┐
+   │  API Mapper plugin (WordPress or Joomla)                     │
+   │                                                              │
+   │  WordPress: /wp-json/api-mapper/v1/{mcp,connections,...}    │
+   │  Joomla:    /?option=com_apimapper&task=mcp.{...}            │
+   │                                                              │
+   │  HMAC-SHA256 verify → scope check → handler                  │
+   └──────────────────────────────────────────────────────────────┘
+```
+
+## Five components
+
+1. **Transport layer** (`src/transports/`)
+   - `stdio.ts` — default; pipes JSON-RPC over stdin/stdout. Spawned
+     by the AI client.
+   - `http.ts` + `server-http.ts` — HTTP+SSE transport behind an
+     OAuth 2.0 PKCE-required authorization server. Bearer tokens are
+     site-bound; cross-origin requests are rejected.
+
+2. **Tool registry** (`src/modules/apimapper/`)
+   - 15 register-files (connections, credentials, flows, graph,
+     local-sources, schema, library, cache, settings, license, misc,
+     workflows, get-skill, onboarding, inspect, diagnose,
+     use-profile) plus 1 entry-point (`index.ts`).
+   - Each tool follows the `@getimo/mcp-toolkit` Goldstandard:
+     annotations, structured errors, `formatResult` / `autoFormatTable`,
+     pagination clamps, destructive confirm-guards.
+
+3. **Platform router** (`src/modules/apimapper/client.ts`)
+   - Detects WP vs. Joomla from site URL + `APIMAPPER_PLATFORM` env.
+   - Dispatches to `/wp-json/api-mapper/v1/...` (WP) or
+     `index.php?option=com_apimapper&task=...` (Joomla).
+   - Joomla envelope unwrap is handled here transparently.
+
+4. **Auth / keychain / profiles** (`src/auth/`)
+   - `keychain.ts` — `@napi-rs/keyring` wrapper with file-fallback.
+   - `profiles.ts` — named profiles (`APIMAPPER_PROFILE=staging` ↔
+     `APIMAPPER_PROFILE=prod`).
+   - `token.ts` — `amk_*` token decoding (payload only — signature is
+     opaque, verified server-side).
+   - `credential-sanitizer.ts` — strips secrets from every response.
+
+5. **Setup + skills** (`src/setup-cli.ts`, `skills/apimapper/`)
+   - `@clack/prompts` interactive wizard.
+   - Auto-detects AI clients, patches their MCP config idempotently.
+   - Ships the skill files (`SKILL.md` + 4 references) into
+     `~/.claude/skills/apimapper/`.
+
+## Auth flow (token issuance)
+
+1. User runs `npx @wootsup/mcp setup`.
+2. Wizard asks for site URL + token.
+3. Wizard calls `GET <site>/api-mapper/v1/mcp/identity` and verifies
+   the returned `siteSignature` against the public `key_id` carried
+   in the token payload.
+4. User confirms the displayed site title + URL.
+5. Wizard writes the token to OS keychain (or `0600` file fallback)
+   under a profile name (default: `default`).
+6. Wizard patches the AI client's MCP config to launch
+   `npx -y @wootsup/mcp` with `APIMAPPER_PROFILE=<name>` in env.
+
+At runtime, the server reads the token from the keychain on every
+launch — tokens never live in the client config file.
+
+## Multi-transport rationale
+
+| | stdio | HTTP+OAuth |
+|---|---|---|
+| Where it runs | User's machine | User's machine or remote |
+| Auth | Bearer from keychain | OAuth 2.0 PKCE bound to site |
+| Use case | Local dev, single user | Remote AI agents (future) |
+| Discovery | Static (one-tool-set) | Dynamic per session |
+
+Both paths feed the same tool registry; the only difference is the
+transport adapter wired into `createServer()`.
+
+## Multi-platform rationale
+
+The same REST contract is implemented in both the WordPress plugin
+and the Joomla extension. The router maps tool calls to whichever
+URL shape the user's platform speaks. This means:
+
+- One MCP server binary, two backends.
+- Every tool works on both platforms (parity test in
+  `apimapper_platform_parity`).
+- Users can move a flow between WP and Joomla via
+  `apimapper_flow_export` / `apimapper_flow_import` without manual
+  rewriting.
+
+## Further reading
+
+- [`security.md`](./security.md) — threat model + mitigations.
+- [`tools.md`](./tools.md) — full tool inventory.
+- [`../skills/apimapper/SKILL.md`](../skills/apimapper/SKILL.md) —
+  task-oriented usage guide.
+- Internal: `~/Projekte/getimo/40-Plans/active/
+  2026-05-18-apimapper-mcp-implementation-plan.md` (full design plan).