bricks-mcp-server 0.2.0

package/README.md

@@ -0,0 +1,73 @@
+# bricks-mcp-server
+
+Provider-agnostic **MCP server** that exposes [Bricks Builder](https://bricksbuilder.io/) data — pages, templates, global classes and theme styles — as tools for any MCP-compatible AI client (Claude Code, Codex CLI, etc.).
+
+It talks to a companion WordPress plugin (**Bricks MCP Bridge**) over the REST API, authenticated with a WordPress Application Password. No AI API key ever lives in WordPress; all model calls happen in your client.
+
+## Quick start
+
+No clone or build needed — `npx` runs it on demand. The fastest path is the guided wizard:
+
+```bash
+npx -y bricks-mcp-server setup
+```
+
+It asks for your site URL, opens the Application Password authorization flow, tests the connection, and writes your client config.
+
+### Manual registration (Claude Code)
+
+```bash
+claude mcp add bricks -s user \
+  -e WP_URL=https://yoursite.tld \
+  -e WP_USER=your-wp-username \
+  -e WP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
+  -- npx -y bricks-mcp-server
+```
+
+Or in `~/.claude.json` under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "bricks": {
+      "command": "npx",
+      "args": ["-y", "bricks-mcp-server"],
+      "env": {
+        "WP_URL": "https://yoursite.tld",
+        "WP_USER": "your-wp-username",
+        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js ≥ 18
+- A WordPress site running **Bricks Builder** with the **Bricks MCP Bridge** plugin installed and active.
+- A WordPress Application Password for a user with the `edit_pages` capability.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `npx -y bricks-mcp-server` | Run the MCP stdio server (what your client invokes). |
+| `npx -y bricks-mcp-server setup` | Interactive setup wizard. |
+| `npx -y bricks-mcp-server doctor` | Diagnose connection problems with specific fixes. |
+
+## Diagnostics
+
+If the connection fails, `doctor` pinpoints the exact cause — unreachable site, stripped `Authorization` header, bad credentials, missing capability, or plugin not installed:
+
+```bash
+WP_URL=https://yoursite.tld WP_USER=you WP_APP_PASSWORD="…" npx -y bricks-mcp-server doctor
+```
+
+## Tools
+
+`bricks_ping`, `bricks_list_pages`, `bricks_get_page`, `bricks_update_page`, `bricks_list_templates`, `bricks_create_template`, `bricks_get_global_classes`, `bricks_update_global_classes`, `bricks_get_theme_styles`.
+
+## License
+
+GPL-2.0-or-later

package/dist/index.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { wpRequest, diagnose, formatDiagnosis } from "./wp-client.js";
+// Subcommand dispatch: `setup` runs the interactive wizard, `doctor` runs the
+// diagnostic ladder once and exits. No subcommand → start the MCP stdio server.
+const subcommand = process.argv[2];
+if (subcommand === "setup") {
+    const { runSetup } = await import("./setup.js");
+    await runSetup();
+    process.exit(0);
+}
+if (subcommand === "doctor" || subcommand === "diagnose") {
+    const d = await diagnose();
+    // eslint-disable-next-line no-console
+    console.log(formatDiagnosis(d));
+    process.exit(d.problem ? 1 : 0);
+}
+const server = new Server({ name: "bricks-mcp-server", version: "0.1.0" }, { capabilities: { tools: {} } });
+const tools = [
+    {
+        name: "bricks_ping",
+        description: "Verify the WordPress connection and report Bricks + WP version.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        schema: z.object({}),
+        handler: async () => wpRequest("/ping"),
+    },
+    {
+        name: "bricks_list_pages",
+        description: "List pages/posts/templates with Bricks content. Supports search, post_type filter, per_page.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                post_type: {
+                    type: "string",
+                    description: "page | post | bricks_template | any (default any)",
+                },
+                search: { type: "string" },
+                per_page: { type: "number", description: "1-100, default 50" },
+            },
+            additionalProperties: false,
+        },
+        schema: z.object({
+            post_type: z.string().optional(),
+            search: z.string().optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+        }),
+        handler: async (args) => wpRequest("/pages", { query: args }),
+    },
+    {
+        name: "bricks_get_page",
+        description: "Get a page/post/template by ID, including its Bricks content/header/footer/settings JSON.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "number" } },
+            required: ["id"],
+            additionalProperties: false,
+        },
+        schema: z.object({ id: z.number().int().positive() }),
+        handler: async (args) => wpRequest(`/pages/${args.id}`),
+    },
+    {
+        name: "bricks_update_page",
+        description: "Update Bricks content/header/footer/settings for a page/post/template. Pass any subset of fields. The 'content' field must be an array of Bricks element objects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number" },
+                title: { type: "string" },
+                content: { type: "array", description: "Bricks elements array" },
+                header: { type: "array" },
+                footer: { type: "array" },
+                settings: { type: "object" },
+            },
+            required: ["id"],
+            additionalProperties: false,
+        },
+        schema: z.object({
+            id: z.number().int().positive(),
+            title: z.string().optional(),
+            content: z.array(z.any()).optional(),
+            header: z.array(z.any()).optional(),
+            footer: z.array(z.any()).optional(),
+            settings: z.record(z.any()).optional(),
+        }),
+        handler: async (args) => {
+            const { id, ...body } = args;
+            return wpRequest(`/pages/${id}`, { method: "PUT", body });
+        },
+    },
+    {
+        name: "bricks_list_templates",
+        description: "List Bricks templates. Optional filter by template type (section, header, footer, popup, content, etc.).",
+        inputSchema: {
+            type: "object",
+            properties: { type: { type: "string" } },
+            additionalProperties: false,
+        },
+        schema: z.object({ type: z.string().optional() }),
+        handler: async (args) => wpRequest("/templates", { query: args }),
+    },
+    {
+        name: "bricks_create_template",
+        description: "Create a Bricks template. Requires title and type; content is the Bricks elements array.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string" },
+                type: { type: "string" },
+                content: { type: "array" },
+            },
+            required: ["title", "type"],
+            additionalProperties: false,
+        },
+        schema: z.object({
+            title: z.string(),
+            type: z.string(),
+            content: z.array(z.any()).optional(),
+        }),
+        handler: async (args) => wpRequest("/templates", { method: "POST", body: args }),
+    },
+    {
+        name: "bricks_get_global_classes",
+        description: "Read Bricks global classes and their categories — useful before editing pages so styling stays consistent.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        schema: z.object({}),
+        handler: async () => wpRequest("/global-classes"),
+    },
+    {
+        name: "bricks_update_global_classes",
+        description: "Replace Bricks global classes and/or categories. Pass full arrays — destructive.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                classes: { type: "array" },
+                categories: { type: "array" },
+            },
+            additionalProperties: false,
+        },
+        schema: z.object({
+            classes: z.array(z.any()).optional(),
+            categories: z.array(z.any()).optional(),
+        }),
+        handler: async (args) => wpRequest("/global-classes", { method: "PUT", body: args }),
+    },
+    {
+        name: "bricks_get_theme_styles",
+        description: "Read Bricks theme styles, color palette, and global settings — context for matching brand styling when generating new sections.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        schema: z.object({}),
+        handler: async () => wpRequest("/theme-styles"),
+    },
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map(({ name, description, inputSchema }) => ({
+        name,
+        description,
+        inputSchema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.find((t) => t.name === request.params.name);
+    if (!tool) {
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    }
+    const parsed = tool.schema.parse(request.params.arguments ?? {});
+    try {
+        const result = await tool.handler(parsed);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            isError: true,
+            content: [{ type: "text", text: message }],
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/setup.js

@@ -0,0 +1,204 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { diagnose, formatDiagnosis } from "./wp-client.js";
+/** npm package name used in generated client configs (npx -y <PKG>). */
+const PKG = "bricks-mcp-server";
+function log(msg = "") {
+    // eslint-disable-next-line no-console
+    console.log(msg);
+}
+function normalizeUrl(raw) {
+    let u = raw.trim().replace(/\/+$/, "");
+    if (!/^https?:\/\//i.test(u))
+        u = `https://${u}`;
+    return u;
+}
+/** Open a URL in the default browser, cross-platform. Best-effort. */
+function openBrowser(url) {
+    const cmd = process.platform === "win32"
+        ? "cmd"
+        : process.platform === "darwin"
+            ? "open"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        /* user can open manually */
+    }
+}
+/**
+ * Run WordPress' Application Passwords Authorization flow.
+ * Spins up a localhost callback server, opens the authorize page, and waits
+ * for WordPress to redirect back with user_login + password.
+ */
+async function authorizeViaBrowser(baseUrl) {
+    return new Promise((resolve) => {
+        const token = randomUUID();
+        let settled = false;
+        const srv = createServer((req, res) => {
+            const reqUrl = new URL(req.url ?? "/", "http://localhost");
+            if (reqUrl.searchParams.get("state") !== token) {
+                res.writeHead(400).end("Bad state");
+                return;
+            }
+            const user = reqUrl.searchParams.get("user_login") ?? "";
+            const password = reqUrl.searchParams.get("password") ?? "";
+            res
+                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+                .end("<h2>✓ Listo</h2><p>Bricks MCP recibió la credencial. Vuelve a la terminal.</p>");
+            if (!settled) {
+                settled = true;
+                srv.close();
+                resolve(user && password ? { user, password } : null);
+            }
+        });
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            const successUrl = `http://127.0.0.1:${port}/callback?state=${token}`;
+            const authorizeUrl = `${baseUrl}/wp-admin/authorize-application.php` +
+                `?app_name=${encodeURIComponent("Bricks MCP")}` +
+                `&success_url=${encodeURIComponent(successUrl)}`;
+            log("\nAbriendo el navegador para autorizar la aplicación…");
+            log("Si no se abre solo, visita esta URL e inicia sesión:");
+            log(`  ${authorizeUrl}\n`);
+            openBrowser(authorizeUrl);
+        });
+        // Give up after 5 minutes.
+        setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                srv.close();
+                resolve(null);
+            }
+        }, 5 * 60 * 1000).unref();
+    });
+}
+/** Is the `claude` CLI on PATH? */
+function hasClaudeCli() {
+    const probe = spawnSync(process.platform === "win32" ? "claude.cmd" : "claude", [
+        "--version",
+    ]);
+    if (!probe.error && probe.status === 0)
+        return true;
+    // On Windows the bare name sometimes resolves via PATHEXT only.
+    const probe2 = spawnSync("claude", ["--version"], { shell: true });
+    return !probe2.error && probe2.status === 0;
+}
+function jsonSnippet(baseUrl, user, pwd) {
+    return JSON.stringify({
+        mcpServers: {
+            bricks: {
+                command: "npx",
+                args: ["-y", PKG],
+                env: { WP_URL: baseUrl, WP_USER: user, WP_APP_PASSWORD: pwd },
+            },
+        },
+    }, null, 2);
+}
+function tomlSnippet(baseUrl, user, pwd) {
+    return (`[mcp_servers.bricks]\n` +
+        `command = "npx"\n` +
+        `args = ["-y", "${PKG}"]\n\n` +
+        `[mcp_servers.bricks.env]\n` +
+        `WP_URL = "${baseUrl}"\n` +
+        `WP_USER = "${user}"\n` +
+        `WP_APP_PASSWORD = "${pwd}"\n`);
+}
+export async function runSetup() {
+    const rl = createInterface({ input, output });
+    try {
+        log("=== Bricks MCP · Setup ===\n");
+        // 1 · Site URL
+        const urlAns = await rl.question("URL de tu WordPress (ej. https://misitio.com): ");
+        const baseUrl = normalizeUrl(urlAns);
+        // 2 · Credentials
+        let user = "";
+        let password = "";
+        const mode = (await rl.question("\n¿Cómo quieres autenticar?\n" +
+            "  [1] Autorizar en el navegador (recomendado)\n" +
+            "  [2] Pegar usuario y Application Password\n" +
+            "Elige 1 o 2: ")).trim();
+        if (mode === "2") {
+            user = (await rl.question("Usuario de WordPress: ")).trim();
+            password = (await rl.question("Application Password: ")).trim();
+        }
+        else {
+            const creds = await authorizeViaBrowser(baseUrl);
+            if (!creds) {
+                log("\n✗ No se recibió la autorización. Reintenta o usa la opción [2].");
+                return;
+            }
+            user = creds.user;
+            password = creds.password;
+            log(`\n✓ Autorizado como '${user}'.`);
+        }
+        // 3 · Validate via the diagnostic ladder.
+        process.env.WP_URL = baseUrl;
+        process.env.WP_USER = user;
+        process.env.WP_APP_PASSWORD = password;
+        log("\nProbando la conexión…");
+        const d = await diagnose();
+        log(formatDiagnosis(d));
+        if (d.problem) {
+            log("\nCorrige lo anterior y vuelve a ejecutar `npx " + PKG + " setup`.");
+            return;
+        }
+        // 4 · Register with the client.
+        const client = (await rl.question("\n¿Qué cliente quieres configurar?\n" +
+            "  [1] Claude Code\n" +
+            "  [2] Codex CLI\n" +
+            "  [3] Solo mostrar la config (la pego yo)\n" +
+            "Elige 1, 2 o 3: ")).trim();
+        if (client === "1") {
+            if (hasClaudeCli()) {
+                const args = [
+                    "mcp",
+                    "add",
+                    "bricks",
+                    "-s",
+                    "user",
+                    "-e",
+                    `WP_URL=${baseUrl}`,
+                    "-e",
+                    `WP_USER=${user}`,
+                    "-e",
+                    `WP_APP_PASSWORD=${password}`,
+                    "--",
+                    "npx",
+                    "-y",
+                    PKG,
+                ];
+                const r = spawnSync("claude", args, { stdio: "inherit", shell: process.platform === "win32" });
+                if (!r.error && r.status === 0) {
+                    log("\n✓ Registrado en Claude Code. Reinicia la sesión y usa `bricks_ping`.");
+                    return;
+                }
+                log("\n⚠ No se pudo ejecutar `claude mcp add`. Pega esto manualmente:");
+            }
+            else {
+                log("\nNo encontré el CLI `claude`. Pega esto en ~/.claude.json (clave mcpServers):");
+            }
+            log("\n" + jsonSnippet(baseUrl, user, password) + "\n");
+        }
+        else if (client === "2") {
+            log("\nPega esto en ~/.codex/config.toml :\n");
+            log(tomlSnippet(baseUrl, user, password) + "\n");
+        }
+        else {
+            log("\nClaude Code (~/.claude.json):\n");
+            log(jsonSnippet(baseUrl, user, password));
+            log("\nCodex CLI (~/.codex/config.toml):\n");
+            log(tomlSnippet(baseUrl, user, password));
+        }
+        log("Listo. ✨");
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/wp-client.js

@@ -0,0 +1,216 @@
+const REQUIRED_ENV = ["WP_URL", "WP_USER", "WP_APP_PASSWORD"];
+/** Read config from env. Throws a friendly error listing what's missing. */
+export function loadConfig() {
+    const missing = REQUIRED_ENV.filter((k) => !process.env[k]);
+    if (missing.length) {
+        throw new Error(`Missing required env vars: ${missing.join(", ")}. Set them in your MCP server config.`);
+    }
+    const baseUrl = process.env.WP_URL.replace(/\/$/, "");
+    const user = process.env.WP_USER;
+    const appPassword = process.env.WP_APP_PASSWORD.replace(/\s+/g, "");
+    const auth = Buffer.from(`${user}:${appPassword}`).toString("base64");
+    return { baseUrl, user, appPassword, auth };
+}
+export async function wpRequest(path, opts = {}) {
+    const { baseUrl, auth } = loadConfig();
+    const url = new URL(`${baseUrl}/wp-json/bricks-mcp/v1${path}`);
+    if (opts.query) {
+        for (const [k, v] of Object.entries(opts.query)) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+    }
+    let res;
+    try {
+        res = await fetch(url, {
+            method: opts.method ?? "GET",
+            headers: {
+                Authorization: `Basic ${auth}`,
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+    }
+    catch (err) {
+        // Network-level failure: surface the actionable diagnostic instead of a raw fetch error.
+        const diag = await diagnose().catch(() => null);
+        const hint = diag ? `\n\n${formatDiagnosis(diag)}` : "";
+        throw new Error(`No se pudo conectar a ${baseUrl} (${err instanceof Error ? err.message : String(err)}).${hint}`);
+    }
+    const text = await res.text();
+    let json;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        throw new Error(`WP returned non-JSON (status ${res.status}): ${text.slice(0, 300)}`);
+    }
+    if (!res.ok) {
+        const code = json && typeof json === "object" && "code" in json
+            ? json.code
+            : undefined;
+        const message = (json && typeof json === "object" && "message" in json
+            ? json.message
+            : null) ?? `HTTP ${res.status}`;
+        // On auth/route failures, run the diagnostic ladder so the user gets an
+        // actionable cause instead of the opaque WordPress error.
+        if (res.status === 401 || res.status === 403 || res.status === 404) {
+            const diag = await diagnose().catch(() => null);
+            if (diag && diag.problem) {
+                throw new Error(formatDiagnosis(diag));
+            }
+        }
+        throw new Error(`WP error: ${message}${code ? ` (${code})` : ""}`);
+    }
+    return json;
+}
+async function tryFetch(url, headers = {}) {
+    try {
+        const res = await fetch(url, { headers: { Accept: "application/json", ...headers } });
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            /* non-JSON body */
+        }
+        return { ok: res.ok, status: res.status, code: body?.code, body };
+    }
+    catch (err) {
+        return { ok: false, status: 0, networkError: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Walk the auth/connectivity ladder and return the first concrete problem found.
+ * Mirrors the manual debugging: site reachable? → WP? → header passes? →
+ * credentials valid? → user has capability? → plugin installed?
+ */
+export async function diagnose() {
+    const missing = REQUIRED_ENV.filter((k) => !process.env[k]);
+    if (missing.length) {
+        return {
+            step: "missing_env",
+            problem: `Faltan variables de entorno: ${missing.join(", ")}.`,
+            fix: "Define WP_URL, WP_USER y WP_APP_PASSWORD en la configuración del MCP.",
+        };
+    }
+    const { baseUrl, user, auth } = loadConfig();
+    // 1 · Is the site reachable and is it WordPress?
+    const root = await tryFetch(`${baseUrl}/wp-json/`);
+    if (root.networkError) {
+        return {
+            step: "site_unreachable",
+            problem: `No se pudo conectar a ${baseUrl}.`,
+            fix: "Revisa que WP_URL sea correcta (incluido https://) y que el sitio esté en línea.",
+            details: { networkError: root.networkError },
+        };
+    }
+    if (root.status !== 200) {
+        return {
+            step: "not_wordpress",
+            problem: `${baseUrl}/wp-json/ respondió HTTP ${root.status}; no parece una REST API de WordPress.`,
+            fix: "Verifica WP_URL y que los permalinks/REST API estén activos.",
+            details: { status: root.status },
+        };
+    }
+    const HTACCESS_FIX = "Añade esta regla a tu .htaccess (encima de '# BEGIN WordPress'):\n" +
+        "  <IfModule mod_rewrite.c>\n" +
+        "  RewriteEngine On\n" +
+        "  RewriteCond %{HTTP:Authorization} ^(.*)\n" +
+        "  RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]\n" +
+        "  </IfModule>\n" +
+        "En Nginx: fastcgi_param HTTP_AUTHORIZATION $http_authorization;";
+    // 2 · Ask the plugin (public endpoint) whether the Authorization header
+    // actually reached PHP. This is the only reliable way to tell a stripped
+    // header apart from bad credentials — both look like rest_not_logged_in.
+    const authcheck = await tryFetch(`${baseUrl}/wp-json/bricks-mcp/v1/authcheck`, {
+        Authorization: `Basic ${auth}`,
+    });
+    const authcheckMissing = authcheck.status === 404 || authcheck.code === "rest_no_route";
+    if (authcheckMissing) {
+        // Older plugin (or none): the diagnostic endpoint isn't there, so we can't
+        // introspect the header. Fall back to the authenticated /ping and give a
+        // best-effort verdict.
+        const ping = await tryFetch(`${baseUrl}/wp-json/bricks-mcp/v1/ping`, {
+            Authorization: `Basic ${auth}`,
+        });
+        if (ping.ok)
+            return { step: "ok", problem: null };
+        if (ping.status === 404 || ping.code === "rest_no_route") {
+            return {
+                step: "plugin_not_installed",
+                problem: "El endpoint bricks-mcp/v1 no existe en este sitio.",
+                fix: "Instala y activa el plugin 'Bricks MCP Bridge' en este WordPress.",
+                details: { status: ping.status, code: ping.code },
+            };
+        }
+        if (ping.status === 403) {
+            return {
+                step: "user_lacks_capability",
+                problem: `El usuario '${user}' no tiene la capacidad requerida (edit_pages).`,
+                fix: "Usa un usuario con rol Editor o Administrador, o ajusta la capability en class-auth.php.",
+                details: { status: ping.status, code: ping.code },
+            };
+        }
+        return {
+            step: "bad_credentials",
+            problem: `Autenticación rechazada (HTTP ${ping.status}). Puede ser credenciales inválidas o que tu hosting elimine la cabecera Authorization.`,
+            fix: "1) Verifica WP_USER y la Application Password.\n" +
+                "2) Si son correctas, " +
+                HTACCESS_FIX +
+                "\n(Actualiza el plugin a v0.4.2+ para un diagnóstico exacto.)",
+            details: { status: ping.status, code: ping.code },
+        };
+    }
+    const headerReceived = authcheck.body?.authorization_header_received === true;
+    const appPwAvailable = authcheck.body?.app_passwords_available !== false;
+    if (!headerReceived) {
+        return {
+            step: "auth_header_stripped",
+            problem: "WordPress no recibe la cabecera Authorization: el servidor la elimina antes de llegar a PHP.",
+            fix: HTACCESS_FIX,
+            details: { authcheck: authcheck.body },
+        };
+    }
+    if (!appPwAvailable) {
+        return {
+            step: "bad_credentials",
+            problem: "Las Application Passwords están deshabilitadas en este sitio.",
+            fix: "Sirve el sitio por HTTPS (requisito de WordPress) o habilítalas con el filtro 'wp_is_application_passwords_available'.",
+            details: { authcheck: authcheck.body },
+        };
+    }
+    // 3 · Header passes and app passwords are on → any auth failure now is creds
+    // or capability. Hit the authenticated /ping to find out which.
+    const ping = await tryFetch(`${baseUrl}/wp-json/bricks-mcp/v1/ping`, {
+        Authorization: `Basic ${auth}`,
+    });
+    if (ping.ok) {
+        return { step: "ok", problem: null };
+    }
+    if (ping.status === 403) {
+        return {
+            step: "user_lacks_capability",
+            problem: `El usuario '${user}' no tiene la capacidad requerida (edit_pages).`,
+            fix: "Usa un usuario con rol Editor o Administrador, o ajusta la capability en class-auth.php.",
+            details: { status: ping.status, code: ping.code },
+        };
+    }
+    // 401 here means the header arrived but WordPress rejected the credentials.
+    return {
+        step: "bad_credentials",
+        problem: `Credenciales rechazadas para el usuario '${user}' (la cabecera sí llega).`,
+        fix: "Revisa WP_USER y regenera la Application Password (Perfil → Application Passwords). " +
+            "Cópiala completa; los espacios se ignoran.",
+        details: { status: ping.status, code: ping.code },
+    };
+}
+export function formatDiagnosis(d) {
+    if (!d.problem)
+        return "✓ Conexión OK.";
+    let out = `✗ ${d.problem}`;
+    if (d.fix)
+        out += `\n→ ${d.fix}`;
+    return out;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "bricks-mcp-server",
+  "version": "0.2.0",
+  "description": "Provider-agnostic MCP server that exposes Bricks Builder pages, templates, global classes and theme styles as tools. Works with any MCP-compatible client (Claude Code, Codex CLI, etc.).",
+  "type": "module",
+  "bin": {
+    "bricks-mcp-server": "dist/index.js",
+    "bricks-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "setup": "node dist/index.js setup",
+    "doctor": "node dist/index.js doctor",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bricks",
+    "bricks-builder",
+    "wordpress",
+    "claude",
+    "claude-code",
+    "ai"
+  ],
+  "author": "Juan Leonardo",
+  "license": "GPL-2.0-or-later",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "typescript": "^5.5.0"
+  }
+}