WordPress MCP Adapter 调试实战：从"连接失败"到完全可用WordPress MCP Adapter

前言

使用work Buddy给WordPress 网站配置MCP（Model Context Protocol）时，踩了不少坑，最后终于搞定了。整理一下经验教训，给有同样需求的朋友参考。

问题背景

客户网站：XXXX.com（工业机械官网）

托管：Hostinger
主题：Astra + Elementor
想通过 MCP 协议管理 WordPress 主题设置

目标：让 AI 助手能直接调用 WordPress MCP Adapter 来修改主题配置。

踩坑全过程

第一步：安装 MCP Adapter 插件

WordPress 后台直接搜索 "MCP Adapter" 就能找到并安装。启用后访问：

https://your-site.com/wp-json/mcp/

返回 {"status":"ok"} 说明插件正常工作。

第二步：尝试使用 @automattic/mcp-wordpress-remote

这是官方提供的 MCP 客户端包，配置方式：

{
  "command": "npx",
  "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
  "env": {
    "WP_API_URL": "https://helimachinery.com/wp-json/mcp/mcp-adapter-default-server",
    "WP_API_USERNAME": "your-email@gmail.com",
    "WP_API_PASSWORD": "XXXX XXXX XXXX XXXX XXXX XXXX"
  }
}

问题：连接总是超时或认证失败

第三步：自己测试 MCP 端点

用 PowerShell 直接测试：

# 测试端点是否可访问
Invoke-WebRequest -Uri 'https://your-site.com/wp-json/mcp/' -Headers @{
    'Authorization' = 'Basic <base64编码的user:app_password>'
} -UseBasicParsing

返回正常说明端点没问题。

第四步：手动实现 MCP 协议

深入研究后发现问题所在：

核心问题：WordPress MCP Adapter 需要 Mcp-Session-Id HTTP Header

MCP 协议是 有状态 的，需要维持会话：

先发 initialize 请求
服务器返回 Mcp-Session-Id header
后续所有请求必须带上这个 header
需要发送 initialized 通知
才能调用 tools/call 等方法

第五步：写一个兼容的 Node.js 客户端

const http = require('http');
const crypto = require('crypto');

const MCP_SERVER = 'https://helimachinery.com/wp-json/mcp/mcp-adapter-default-server';
const AUTH = Buffer.from('sanlin20201@gmail.com:XI2M 3Brf Y7nj pBuD 3ZJY u8tU').toString('base64');

let sessionId = null;

function request(body) {
    return new Promise((resolve, reject) => {
        const url = new URL(MCP_SERVER);
        const options = {
            hostname: url.hostname,
            path: url.pathname,
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Basic ${AUTH}`
            }
        };
        if (sessionId) {
            options.headers['Mcp-Session-Id'] = sessionId;
        }
        
        const req = http.request(options, (res) => {
            if (res.headers['mcp-session-id']) {
                sessionId = res.headers['mcp-session-id'];
            }
            let data = '';
            res.on('data', chunk => data += chunk);
            res.on('end', () => resolve(JSON.parse(data)));
        });
        req.on('error', reject);
        req.write(JSON.stringify(body));
        req.end();
    });
}

async function init() {
    const res = await request({
        jsonrpc: '2.0', id: 1, method: 'initialize',
        params: {
            protocolVersion: '2024-11-05',
            capabilities: {},
            clientInfo: { name: 'wp-client', version: '1.0' }
        }
    });
    console.log('Session initialized:', sessionId);
    
    // 必须发送 initialized 通知
    await request({ jsonrpc: '2.0', method: 'initialized', params: {} });
}

async function discover() {
    return await request({
        jsonrpc: '2.0', id: 2, method: 'tools/list'
    });
}

async function call(name, args = {}) {
    return await request({
        jsonrpc: '2.0', id: 3, method: 'tools/call',
        params: { name, arguments: args }
    });
}

第六步：调用成功！

// 发现可用工具
await init();
const tools = await discover();
console.log(tools);
// 输出：80+ Astra 主题相关 abilities

// 获取 Header 配置
await call('astra/get-header-builder', {});

// 获取侧边栏设置
await call('astra/get-sidebar-layout', {});

关键发现总结

问题	原因	解决方案
连接超时	npx 下载慢	全局安装：`npm install -g @automattic/mcp-wordpress-remote`
认证失败	应用密码格式错误	必须用 6段格式：`XXXX XXXX XXXX XXXX XXXX XXXX`
总是报错	缺少 SessionId	必须从 initialize 响应获取并维持
协议错误	缺少 initialized 通知	initialize 后必须发送 `initialized` 通知

WordPress 应用程序密码注意事项

不是登录密码 - 需要单独生成
位置：WP后台 → 用户 → 个人资料 → 应用程序密码
格式：6段，每段4个字符，用空格分隔
授权：生成时分配的权限就是 MCP 能操作的权限

最终成果

现在可以通过 MCP 直接管理：

✅ 字体设置（body/h1-h6/heading）
✅ 全局颜色/按钮颜色/链接颜色
✅ Header Builder（桌面/移动端）
✅ Sidebar 配置（布局/宽度/样式）
✅ Footer 设置
✅ 滚动到顶部按钮
✅ 性能优化（字体本地化）

结语

WordPress MCP Adapter 本身是能用的，问题在于第三方客户端对 HTTP Session 的处理不一致。自定义一个简单的客户端脚本，问题迎刃而解。

技术栈：Node.js + WordPress REST API + MCP 协议
插件版本：MCP Adapter（WordPress 官方插件目录）