MCP Local Wp

🚀 MCP Server Local WP

MCP Server Local WP 是一個基於 Model Context Protocol (MCP) 的服務器，它能讓 Claude 和 Cursor 等 AI 助手直接以只讀方式訪問你通過 Local by Flywheel 創建的 WordPress 數據庫。有了它，AI 無需再猜測表結構，也不用盲目編寫 SQL 查詢，就能直接理解你的實際數據。

🚀 快速開始

前提條件

• 安裝並運行 Local by Flywheel。
• 有一個正在運行的 Local 站點。
• 若進行本地開發，需安裝 Node.js 18+。

快速設置（推薦）

Cursor IDE 配置

將以下內容添加到你的 Cursor MCP 配置文件（.cursor/mcp.json）中：

{
  "mcpServers": {
    "mcp-local-wp": {
      "command": "npx",
      "args": [
        "-y",
        "@verygoodplugins/mcp-local-wp@latest"
      ]
    }
  }
}

Claude Desktop 配置

在 macOS 系統中，將以下內容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json 文件中；在 Windows 系統中，添加到 %APPDATA%\\Claude\\claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "mcp-local-wp": {
      "command": "npx",
      "args": [
        "-y",
        "@verygoodplugins/mcp-local-wp@latest"
      ]
    }
  }
}

高級設置（本地開發）

從源碼安裝

git clone https://github.com/verygoodplugins/mcp-local-wp.git
cd mcp-local-wp
npm install
npm run build

本地配置

{
  "mcpServers": {
    "mcp-local-wp": {
      "command": "node",
      "args": [
        "/full/path/to/mcp-local-wp/dist/index.js"
      ]
    }
  }
}

自定義環境變量

對於非 Local 設置或自定義配置，可使用以下配置：

{
  "mcpServers": {
    "mcp-local-wp": {
      "command": "npx",
      "args": [
        "-y",
        "@verygoodplugins/mcp-local-wp@latest"
      ],
      "env": {
        "MYSQL_DB": "local",
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "root"
      }
    }
  }
}

✨ 主要特性

• 無需猜測表結構：AI 助手可以直接查看實際的表和列。
• 準確的 JOIN 操作：理解表之間的關係。
• 真實數據驗證：在建議查詢之前可以驗證數據是否存在。
• 支持插件開發：能夠適應任何插件的自定義表（如 WooCommerce、LearnDash 等）。
• 即時調試：例如，“顯示所有未完成問卷 ID 42 的用戶”這樣的任務可以在幾秒鐘內完成。

💻 使用示例

基礎用法

獲取最近發佈的文章：

SELECT ID, post_title, post_date, post_status 
FROM wp_posts 
WHERE post_type = 'post' AND post_status = 'publish' 
ORDER BY post_date DESC 
LIMIT 5;

高級用法

探索數據庫結構

-- 查看所有表
SHOW TABLES;

-- 檢查表結構
DESCRIBE wp_posts;

-- 獲取表信息
SHOW TABLE STATUS LIKE 'wp_%';

WordPress 特定查詢

-- 獲取網站選項
SELECT option_name, option_value 
FROM wp_options 
WHERE option_name IN ('blogname', 'blogdescription', 'admin_email');

-- 查找激活的插件
SELECT option_value 
FROM wp_options 
WHERE option_name = 'active_plugins';

-- 獲取用戶信息
SELECT user_login, user_email, display_name 
FROM wp_users 
LIMIT 10;

-- 文章元數據
SELECT p.post_title, pm.meta_key, pm.meta_value
FROM wp_posts p
JOIN wp_postmeta pm ON p.ID = pm.post_id
WHERE p.post_type = 'post' AND pm.meta_key = '_edit_last';

🔧 技術細節

解決的 Local by Flywheel 挑戰

使用原始的 mcp-server-mysql 與 Local by Flywheel 時，開發者會遇到以下挑戰：

1. 動態路徑：Local by Flywheel 為每個站點生成唯一標識符（如 lx97vbzE7），當站點重啟時這些標識符會改變。
2. 套接字與端口混淆：Local 同時使用 Unix 套接字和 TCP 端口，但配置可能會很棘手。
3. 硬編碼配置：大多數設置需要在 Local 每次重啟時手動更新路徑。

解決方案

這個 MCP 服務器通過以下方式自動檢測你正在運行的 Local by Flywheel MySQL 實例：

1. 進程檢測：掃描正在運行的進程以查找活動的 mysqld 實例。
2. 配置解析：從活動的 Local 站點中提取 MySQL 配置。
3. 動態連接：自動使用正確的套接字路徑或端口進行連接。
4. 備用支持：對於非 Local 設置，回退到環境變量。

可用工具

mysql_query

對本地 WordPress 數據庫執行只讀 SQL 查詢。 輸入字段：

• sql（字符串）：單個只讀語句（SELECT/SHOW/DESCRIBE/EXPLAIN）
• params（字符串數組）：? 佔位符的可選參數值

示例用法：

-- 帶參數
SELECT * FROM wp_posts WHERE post_status = ? ORDER BY post_date DESC LIMIT ?;
-- params: ["publish", "5"]

-- 直接查詢
SELECT option_name, option_value FROM wp_options WHERE option_name LIKE '%theme%';
SHOW TABLES;
DESCRIBE wp_users;

mysql_schema

使用 INFORMATION_SCHEMA 檢查數據庫架構。

• 無參數：列出具有基本統計信息的表
• 帶 table 參數：返回該表的列和索引

示例：

// 列出所有表
{
  "tool": "mysql_schema",
  "args": {}
}

// 檢查特定表
{
  "tool": "mysql_schema",
  "args": { "table": "wp_posts" }
}

工作原理

原始問題

當首次嘗試使用 mcp-server-mysql 與 Local by Flywheel 時，遇到了以下問題：

1. 動態套接字路徑：Local 生成的路徑（如 /Users/.../Local/run/lx97vbzE7/mysql/mysqld.sock）中的 lx97vbzE7 每次重啟 Local 時都會改變。
2. 配置複雜性：原始服務器需要硬編碼路徑，每次 Local 重啟時都會失效。
3. 主機/端口混淆：Local 的 MySQL 配置在套接字和 TCP 連接方面可能會很棘手。

解決方案流程

1. 基於進程的檢測：

ps aux | grep mysqld | grep -v grep

通過此命令查找活動的 MySQL 實例並提取其配置文件路徑。

2. 動態路徑解析：

// 從進程參數中：--defaults-file=/Users/.../Local/run/lx97vbzE7/conf/mysql/my.cnf
// 提取站點目錄並構建套接字路徑
const configPath = extractFromProcess();
const siteDir = path.dirname(path.dirname(path.dirname(configPath)));
const socketPath = path.join(siteDir, 'mysql/mysqld.sock');

3. 自動配置： 服務器自動進行以下配置：

• 為活動的 Local 站點使用正確的套接字路徑。
• 使用正確的數據庫名稱（local）。
• 使用默認憑據（root/root）。
• 必要時回退到環境變量。

優勢

• 重啟無憂：每次重啟 Local by Flywheel 時都能正常工作。
• 站點切換：在切換 Local 站點時自動適應。
• 零維護：無需再手動更新路徑。
• 錯誤處理：如果 MySQL 未運行，會提供清晰的錯誤消息。

處理的本地目錄結構

~/Library/Application Support/Local/run/
├── lx97vbzE7/                    # 動態站點 ID（重啟時更改）
│   ├── conf/mysql/my.cnf        # 讀取此文件獲取端口信息
│   └── mysql/mysqld.sock        # 通過此套接字連接
└── WP7lolWDi/                   # 另一個站點（如果有多個正在運行）
    ├── conf/mysql/my.cnf
    └── mysql/mysqld.sock

服務器會智能地找到活動站點並連接到正確的 MySQL 實例。

📄 許可證

本項目採用 GPL-3.0-or-later 許可證，詳情請參閱 LICENSE 文件。作為一個專注於 WordPress 的工具，我們秉持 copyleft 理念，確保其對社區免費開放。

🔧 開發設置

從源碼運行

1. 啟動 Local 站點：確保有一個正在運行的 Local by Flywheel 站點。
2. 克隆並構建：

git clone https://github.com/verygoodplugins/mcp-local-wp.git
cd mcp-local-wp
npm install
npm run build

3. 測試連接：

node dist/index.js

開發模式

npm run dev

此命令會以 TypeScript 模式運行服務器，並監視更改。

代碼檢查與格式化

• 代碼檢查：npm run lint
• 修復代碼檢查問題：npm run lint:fix
• 格式化代碼：npm run format
• 檢查代碼格式：npm run format:check

通過 ESLint + Prettier 統一 MCP 服務器的標準。

🔍 故障排除

常見問題

1. “未找到活動的 MySQL 進程”

   • 確保 Local by Flywheel 正在運行。
   • 確保 Local 中至少有一個站點已啟動。
   • 檢查站點的數據庫是否正在運行。

2. “未找到 MySQL 套接字”

   • 驗證 Local 站點已完全啟動。
   • 嘗試在 Local 中停止並重新啟動站點。
   • 檢查 Local 的日誌以查看 MySQL 啟動問題。

3. 連接被拒絕

   • 確保 Local 站點的 MySQL 服務正在運行。
   • 檢查是否有其他進程正在使用 MySQL 端口。
   • 嘗試重啟 Local by Flywheel。

4. 權限被拒絕

   • 確保 MySQL 套接字文件具有正確的權限。
   • 檢查你的用戶是否有權限訪問 Local 的目錄。

手動配置

如果自動檢測失敗，你可以手動配置連接：

export MYSQL_SOCKET_PATH="/path/to/your/local/site/mysql/mysqld.sock"
export MYSQL_DB="local"
export MYSQL_USER="root"
export MYSQL_PASS="root"

調試

通過設置 DEBUG 啟用調試日誌：

DEBUG=mcp-local-wp mcp-local-wp

🔒 安全

• 只讀操作：僅允許 SELECT/SHOW/DESCRIBE/EXPLAIN 操作。
• 單語句：阻止在一次調用中執行多個語句。
• 本地開發：專為本地環境（Local by Flywheel）設計。
• 無外部連接：在可用時優先使用 Unix 套接字連接。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

開發指南

1. 分叉倉庫。
2. 創建功能分支：git checkout -b feature/your-feature-name。
3. 進行更改並添加測試。
4. 確保 TypeScript 編譯通過：npm run build。
5. 提交拉取請求。

📞 支持

• GitHub 問題：報告錯誤或請求功能
• 文檔：本 README 和內聯代碼文檔
• 社區：加入 Model Context Protocol 社區討論

📚 相關項目

• mcp-server-mysql - 啟發此 WordPress 特定版本的原始 MySQL MCP 服務器
• Local by Flywheel - 此服務器設計用於的本地 WordPress 開發環境
• Model Context Protocol - 協議規範

由 Jack Arturo 在 Very Good Plugins 用 ❤️ 構建 · 為開源社區精心打造