Gravity MCP

重力 MCP

重力表单的模型上下文协议（MCP）服务器。通过任何兼容MCP的客户端与您的WordPress表单、提要和条目进行交互。

](https://www.npmjs.com/package/@gravitykit/mcp)

由...建造 重力 Kit 重力形式社区。

特性

• API全面覆盖：重力形式API终点
• 智能现场管理：具有依赖跟踪功能的智能现场操作
• 高级搜索：条目的复杂过滤和搜索功能
• 表单提交：完整的提交工作流程，包括验证
• 附加组件集成：管理MailChimp、Stripe、PayPal等的订阅源
• 类型安全：对所有操作进行全面验证
• 战斗测试：具有真实场景的广泛测试套件

快速开始

先决条件

• Node.js 18+
• WordPress与重力形式2.5+
• 启用HTTPS的WordPress网站（身份验证所需）

安装

1. 克隆存储库

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

1. 设置环境

   cp .env.example .env

1. 配置凭据 在 .env:

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

为了地方发展 （Laravel代客泊车、MAMP等）：

   # Add this line if using self-signed certificates
   MCP_ALLOW_SELF_SIGNED_CERTS=true

1. 生成API凭据 在WordPress中：

- 首选 表单→ 设置→ REST API - 点击 添加密钥 - 保存消费者密钥和密码

1. 添加到克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

可用工具

表格（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 -删除附加订阅源

用法示例

搜索条目

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"
});

配置

所需的环境变量

• 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 -请求超时（ms）
• GRAVITY_FORMS_DEBUG=false -启用调试日志记录
• MCP_ALLOW_SELF_SIGNED_CERTS=false -允许自签名SSL证书（仅限本地开发人员）

测试环境配置

服务器支持 双环境配置 在不影响生产数据的情况下进行安全测试。

设置测试环境

将测试站点凭据添加到您的 .env 与生产凭据一起归档：

# Production/Live Site
GRAVITY_FORMS_CONSUMER_KEY=ck_live_key
GRAVITY_FORMS_CONSUMER_SECRET=cs_live_secret
GRAVITY_FORMS_BASE_URL=https://www.yoursite.com

# Test/Staging Site (recommended for safe testing)
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

# Enable test mode (optional)
GRAVITYKIT_MCP_TEST_MODE=true

测试环境特征

使用测试配置时：

• 自动测试表格前缀 -所有以“test\_”前缀创建的测试表单
• 自动清理 -测试后自动删除测试表单
• 环境隔离 -与生产数据完全分离
• 安全实验 -无风险测试破坏性操作

使用测试模式

# Verify test environment configuration
GRAVITYKIT_MCP_TEST_MODE=true npm run check-env

# Create test data on test site (requires test credentials)
npm run setup-test-data

# Run all tests against test site (auto-detects test credentials)
npm test

# Interactive testing with MCP Inspector (test mode)
GRAVITYKIT_MCP_TEST_MODE=true npm run inspect

# Run specific test suites against test site
NODE_ENV=test npm run test:forms
NODE_ENV=test npm run test:entries
NODE_ENV=test npm run test:submissions

测试模式检测

在以下情况下，服务器会自动使用测试配置：

1. GRAVITYKIT_MCP_TEST_MODE=true 已设置（或遗留 GRAVITYMCP_TEST_MODE=true)
2. 或 NODE_ENV=test 已设置
3. 配置OR测试凭据并运行测试命令

测试安全功能

服务器包括多种安全机制，以防止意外的生产数据污染：

1. 测试证书要求 -The setup-test-data 脚本将 默认失败 如果未配置测试凭据
2. 没有沉默的退路 -创建或修改数据的脚本不会悄无声息地退回生产环境
3. 显式生产覆盖 -生产使用需要可怕 --force-production 带有警告的标志
4. 清除错误消息 -丢失时配置测试凭据的有用指导
5. 测试数据前缀 -所有测试表格都自动前缀为“test\_”，以便于识别

最佳实践

1. 始终配置测试环境 -使用临时/测试WordPress网站
2. 切勿先在生产环境中进行测试 -生产前在测试现场验证
3. 将测试证书分开保存 -用于测试和现场的不同API密钥
4. 为测试数据使用前缀 -便于清理，标识清晰
5. 启用调试模式进行测试 - GRAVITY_FORMS_DEBUG=true 查看详细日志
6. 审查安全警告 -警告出现时要认真对待

测试

# Run all tests
npm run test:all

# Run specific test suites
npm run test:forms
npm run test:entries
npm run test:field-operations

# Run with live API (requires credentials)
npm test

安全

• 需要HTTPS：所有API通信加密
• 删除保护：默认情况下禁用破坏性操作
• 输入验证：在API调用之前验证的所有输入
• 速率限制：使用指数回退自动重试

故障排除

连接问题

• 使用验证凭据 npm run check-env
• 确保WordPress网站已启用HTTPS
• 检查REST API是否在重力形式设置中启用

具有自签名证书的本地开发

如果你使用的是带有自签名SSL证书的本地开发环境（Laravel Valet、MAMP、local WP等），你可能会遇到身份验证错误。要解决此问题，请执行以下操作：

添加到您的 .env 文件：

MCP_ALLOW_SELF_SIGNED_CERTS=true

⚠️ 安全警告：仅禁用本地开发环境的SSL证书验证。切勿在生产中使用此设置！

身份验证错误

• 确认API密钥正确
• 验证用户是否具有适当的重力表单功能
• 检查表格→ 设置→ 关键状态的REST API
• 为了地方发展，确保 MCP_ALLOW_SELF_SIGNED_CERTS=true 如果使用自签名证书，则设置

调试模式

启用详细日志记录：

GRAVITY_FORMS_DEBUG=true

支持

• 重力形式文件
• MCP文件

许可证

GPL-2.0许可证-请参阅 许可证 文件以获取详细信息。

贡献

我们欢迎Gravity Forms社区的贡献！无论您是构建附加组件、管理表单还是与其他服务集成，您的见解和代码贡献都可以帮助每个人。

如何做出贡献

1. 分叉存储库 -首先创建自己的副本
2. 创建要素分支 -保持更改有序
3. 添加测试 -确保测试覆盖率的可靠性
4. 运行测试套件 -验证一切是否正常 npm run test:all
5. 提交拉取请求 -与社区分享您的改进

自动发布

此存储库使用GitHub Actions在标记新版本时自动发布到npm：

1. 更新中的版本 package.json
2. 提交您的更改
3. 创建并推送标签： git tag v1.0.5 && git push origin v1.0.5
4. GitHub Actions将自动发布到npm

维护人员注意事项：确保 NPM_TOKEN secret在存储库设置中配置，以便自动发布工作。

贡献理念

对于附加组件开发人员：

• 添加对插件提要类型的支持
• 增强自定义字段的字段类型定义
• 分享运行良好的集成模式

对于模板建设者：

• 改进字段验证逻辑
• 为常见任务添加辅助工具
• 增强错误消息和调试

对于每个人：

• 通过以下方式报告错误或建议功能
• 改进文档和示例
• 分享您的用例和工作流程

您的贡献有助于使Gravity Forms自动化更好地为每个人服务。让我们一起创造一些伟大的东西！