Gravitymcp

🚀 GravityMCP

GravityMCP 是一款適用於 Gravity Forms 的模型上下文協議（MCP）服務器。藉助任何支持 MCP 的客戶端，你可以與 WordPress 表單、訂閱源和條目進行交互。

由 GravityKit 為 Gravity Forms 社區打造。

✨ 主要特性

• 全面的 API 覆蓋：涵蓋 Gravity Forms 的 API 端點。
• 智能字段管理：具備依賴跟蹤功能的智能字段操作。
• 高級搜索：支持對條目進行復雜的過濾和搜索。
• 表單提交：擁有完整的提交工作流程和驗證機制。
• 插件集成：可管理 MailChimp、Stripe、PayPal 等插件的訂閱源。
• 類型安全：對所有操作進行全面驗證。
• 經過實戰檢驗：擁有大量基於真實場景的測試套件。

🚀 快速開始

前提條件

• Node.js 18 及以上版本。
• 安裝了 Gravity Forms 2.5 及以上版本的 WordPress。
• 啟用 HTTPS 的 WordPress 站點（認證所需）。

📦 安裝指南

1. 克隆倉庫

   git clone https://github.com/GravityKit/GravityMCP.git
   cd GravityMCP
   npm install
   

2. 設置環境

   cp .env.example .env
   

3. 在 .env 文件中配置憑證：

   GRAVITY_FORMS_CONSUMER_KEY=your_key_here
   GRAVITY_FORMS_CONSUMER_SECRET=your_secret_here
   GRAVITY_FORMS_BASE_URL=https://yoursite.com
   

4. 在 WordPress 中生成 API 憑證：

   • 訪問 Forms → Settings → REST API。
   • 點擊 Add Key。
   • 保存消費者密鑰和密鑰密碼。

5. 添加到 Claude Desktop

   編輯 ~/Library/Application Support/Claude/claude_desktop_config.json 文件：

   {
     "mcpServers": {
       "gravitymcp": {
         "command": "node",
         "args": ["/path/to/GravityMCP/src/index.js"],
         "env": {
           "GRAVITY_FORMS_CONSUMER_KEY": "your_key",
           "GRAVITY_FORMS_CONSUMER_SECRET": "your_secret",
           "GRAVITY_FORMS_BASE_URL": "https://yoursite.com"
         }
       }
     }
   }
   

💻 使用示例

基礎用法

搜索條目

await mcp.call('gf_list_entries', {
  search: {
    field_filters: [
      { key: "1.3", value: "John", operator: "contains" },
      { key: "date_created", value: "2024-01-01", operator: ">=" }
    ],
    mode: "all"
  },
  sorting: { key: "date_created", direction: "desc" }
});

添加字段

await mcp.call('gf_add_field', {
  form_id: 1,
  field_type: 'email',
  properties: {
    label: 'Email Address',
    isRequired: true
  }
});

提交表單

await mcp.call('gf_submit_form_data', {
  form_id: 1,
  input_1: "John Doe",
  input_2: "john@example.com",
  input_3: "Message content"
});

📚 詳細文檔

可用工具

表單（6 個工具）

• gf_list_forms - 列出表單，支持過濾和分頁。
• gf_get_form - 獲取完整的表單配置。
• gf_create_form - 創建帶有字段的新表單。
• gf_update_form - 更新現有表單。
• gf_delete_form - 刪除表單（需要 ALLOW_DELETE=true）。
• gf_validate_form - 驗證表單數據。

條目（5 個工具）

• gf_list_entries - 使用高級過濾器搜索條目。
• gf_get_entry - 獲取特定條目的詳細信息。
• gf_create_entry - 創建新條目。
• gf_update_entry - 更新現有條目。
• gf_delete_entry - 刪除條目（需要 ALLOW_DELETE=true）。

字段操作（4 個工具）

• gf_add_field - 智能定位添加字段。
• gf_update_field - 檢查依賴關係後更新字段。
• gf_delete_field - 可選擇級聯刪除字段。
• gf_list_field_types - 列出可用的字段類型。

提交（2 個工具）

• gf_submit_form_data - 完整處理後提交表單。
• gf_validate_submission - 驗證但不提交。

插件（7 個工具）

• gf_list_feeds - 列出所有插件訂閱源。
• gf_get_feed - 獲取特定訂閱源的配置。
• gf_list_form_feeds - 列出特定表單的訂閱源。
• gf_create_feed - 創建新的插件訂閱源。
• gf_update_feed - 更新現有訂閱源。
• gf_patch_feed - 部分更新訂閱源屬性。
• gf_delete_feed - 刪除插件訂閱源。

配置

必需的環境變量

• GRAVITY_FORMS_CONSUMER_KEY - API 消費者密鑰。
• GRAVITY_FORMS_CONSUMER_SECRET - API 消費者密鑰密碼。
• GRAVITY_FORMS_BASE_URL - WordPress 站點 URL。

可選設置

• GRAVITY_FORMS_ALLOW_DELETE=false - 啟用刪除操作。
• GRAVITY_FORMS_TIMEOUT=30000 - 請求超時時間（毫秒）。
• GRAVITY_FORMS_DEBUG=false - 啟用調試日誌。

測試環境配置

服務器支持雙環境配置，可在不影響生產數據的情況下安全進行測試。

設置測試環境

在 .env 文件中添加測試站點的憑證，與生產憑證一起：

# 生產/實時站點
GRAVITY_FORMS_CONSUMER_KEY=ck_live_key
GRAVITY_FORMS_CONSUMER_SECRET=cs_live_secret
GRAVITY_FORMS_BASE_URL=https://www.yoursite.com

# 測試/暫存站點（建議用於安全測試）
GRAVITY_FORMS_TEST_CONSUMER_KEY=ck_test_key
GRAVITY_FORMS_TEST_CONSUMER_SECRET=cs_test_secret
GRAVITY_FORMS_TEST_BASE_URL=https://staging.yoursite.com

# 啟用測試模式（可選）
GRAVITY_MCP_TEST_MODE=true

測試環境特性

使用測試配置時：

• 自動添加測試表單前綴 - 所有測試表單自動添加 "TEST_" 前綴。
• 自動清理 - 測試完成後自動刪除測試表單。
• 環境隔離 - 與生產數據完全分離。
• 安全實驗 - 無風險地測試破壞性操作。

使用測試模式

# 驗證測試環境配置
GRAVITY_MCP_TEST_MODE=true npm run check-env

# 在測試站點創建測試數據（需要測試憑證）
npm run setup-test-data

# 針對測試站點運行所有測試（自動檢測測試憑證）
npm test

# 使用 MCP Inspector 進行交互式測試（測試模式）
GRAVITYMCP_TEST_MODE=true npm run inspect

# 針對測試站點運行特定測試套件
NODE_ENV=test npm run test:forms
NODE_ENV=test npm run test:entries
NODE_ENV=test npm run test:submissions

測試模式檢測

當滿足以下條件時，服務器將自動使用測試配置：

1. 設置 GRAVITYMCP_TEST_MODE=true。
2. 或者設置 NODE_ENV=test。
3. 或者配置了測試憑證並運行了測試命令。

測試安全特性

服務器包含多種安全機制，防止意外汙染生產數據：

1. 測試憑證要求 - 如果未配置測試憑證，setup-test-data 腳本默認會失敗。
2. 無靜默回退 - 創建或修改數據的腳本不會靜默回退到生產環境。
3. 顯式生產覆蓋 - 需要使用可怕的 --force-production 標誌並伴有警告才能使用生產環境。
4. 清晰的錯誤消息 - 缺少測試憑證時提供有用的配置指導。
5. 測試數據前綴 - 所有測試表單自動添加 "TEST_" 前綴，便於識別。

最佳實踐

1. 始終配置測試環境 - 使用暫存/測試 WordPress 站點。
2. 切勿先在生產環境測試 - 在生產環境之前先在測試站點驗證。
3. 分開保存測試憑證 - 測試和實時環境使用不同的 API 密鑰。
4. 為測試數據添加前綴 - 便於清理和識別。
5. 在測試時啟用調試模式 - GRAVITY_FORMS_DEBUG=true 以獲取詳細日誌。
6. 查看安全警告 - 認真對待出現的警告。

測試

# 運行所有測試
npm run test:all

# 運行特定測試套件
npm run test:forms
npm run test:entries
npm run test:field-operations

# 使用實時 API 運行（需要憑證）
npm test

安全

• 需要 HTTPS：所有 API 通信均加密。
• 刪除保護：默認禁用破壞性操作。
• 輸入驗證：在進行 API 調用之前驗證所有輸入。
• 速率限制：自動重試並採用指數退避策略。

故障排除

連接問題

• 使用 npm run check-env 驗證憑證。
• 確保 WordPress 站點啟用了 HTTPS。
• 檢查 Gravity Forms 設置中是否啟用了 REST API。

認證錯誤

• 確認 API 密鑰正確。
• 驗證用戶是否具備適當的 Gravity Forms 權限。
• 查看 Forms → Settings → REST API 中的密鑰狀態。

調試模式

啟用詳細日誌：

GRAVITY_FORMS_DEBUG=true

支持

• GitHub Issues
• Gravity Forms 文檔
• MCP 文檔

許可證

本項目採用 GPL - 2.0 許可證，詳情請參閱 LICENSE 文件。

貢獻

我們歡迎 Gravity Forms 社區的貢獻！無論你是構建插件、管理表單還是與其他服務集成，你的見解和代碼貢獻都能幫助到大家。

如何貢獻

1. 分叉倉庫 - 首先創建自己的副本。
2. 創建功能分支 - 保持更改的組織性。
3. 添加測試 - 通過測試覆蓋確保可靠性。
4. 運行測試套件 - 使用 npm run test:all 驗證一切正常。
5. 提交拉取請求 - 與社區分享你的改進。

自動發佈

此倉庫使用 GitHub Actions 在標記新版本時自動發佈到 npm：

1. 在 package.json 中更新版本號。
2. 提交更改。
3. 創建並推送標籤：git tag v1.0.4 && git push origin v1.0.4。
4. GitHub Actions 將自動發佈到 npm。

維護者注意：為使自動發佈正常工作，請確保在倉庫設置中配置了 NPM_TOKEN 密鑰。

貢獻建議

對於插件開發者：

• 為你的插件訂閱源類型添加支持。
• 增強自定義字段的字段類型定義。
• 分享有效的集成模式。

對於表單構建者：

• 改進字段驗證邏輯。
• 為常見任務添加輔助工具。
• 增強錯誤消息和調試功能。

對於所有人：

• 通過 GitHub Issues 報告錯誤或提出功能建議。
• 改進文檔和示例。
• 分享你的使用案例和工作流程。

你的貢獻將使 Gravity Forms 自動化對每個人都更友好。讓我們一起打造偉大的項目！