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 自动化对每个人都更友好。让我们一起打造伟大的项目！