重力-MCP

Name: 重力-MCP
Author: GravityKit

作者：GravityKit12 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

Gravity Forms 的 MCP

一个用于 Gravity Forms 的 Model Context Protocol (MCP) 服务器。通过任何兼容 MCP 的客户端与您的 WordPress 表单、数据源和条目进行交互。

由 GravityKit 为 Gravity Forms 社区构建。

功能

全面的 API 覆盖：Gravity Forms API 端点
智能字段管理：具有依赖关系跟踪的智能字段操作
高级搜索：条目的复杂过滤和搜索能力
表单提交：完整的提交工作流程，包括验证
插件集成：管理 MailChimp、Stripe、PayPal 等的数据源
类型安全：所有操作的全面验证
经过实战考验：包含真实场景的广泛测试套件

快速开始

先决条件

Node.js 18+
安装了 Gravity Forms 2.5+ 的 WordPress
启用了 HTTPS 的 WordPress 站点（认证所需）

安装

克隆仓库

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

设置环境
```
cp .env.example .env
```

配置凭证 在 .env 文件中：

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

本地开发（Laravel Valet、MAMP 等）：

# 如果使用自签名证书，请添加此行
MCP_ALLOW_SELF_SIGNED_CERTS=true

生成 API 凭证 在 WordPress 中：
- 前往 表单 → 设置 → REST API
- 点击 添加密钥
- 保存消费者密钥和秘密

添加到 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"
      }
    }
  }
}

可用工具

表单 (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: '电子邮件地址',
    isRequired: true
  }
});

提交表单

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

配置

必需的环境变量

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 - 启用调试日志
MCP_ALLOW_SELF_SIGNED_CERTS=false - 允许自签名 SSL 证书（仅限本地开发）

测试环境配置

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

设置测试环境

在 .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

测试模式检测

当以下任一条件满足时，服务器会自动使用测试配置：

设置 GRAVITYMCP_TEST_MODE=true
或者设置 NODE_ENV=test
或者配置了测试凭据并且运行了测试命令

测试安全性功能

服务器包含多个安全机制，防止意外污染生产数据：

测试凭据要求 - 如果未配置测试凭据，setup-test-data 脚本默认失败
无静默回退 - 创建或修改数据的脚本不会静默回退到生产
明确生产覆盖 - 生产使用需要带有警告的 --force-production 标志
清晰错误信息 - 当缺少测试凭据时提供有用的指导
测试数据前缀 - 所有测试表单自动带有 "TEST_" 前缀，便于识别

最佳实践

始终配置测试环境 - 使用暂存/测试 WordPress 站点
不要首先在生产环境中测试 - 在生产之前先在测试站点上验证
分开测试凭据 - 测试与实时使用不同的 API 密钥
使用测试数据前缀 - 使清理容易且识别清晰
启用测试模式的调试 - GRAVITY_FORMS_DEBUG=true 以获得详细日志
审查安全警告 - 当出现警告时认真对待

测试

# 运行所有测试
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 是否已启用

本地开发使用自签名证书

如果您正在使用带有自签名 SSL 证书的本地开发环境（如 Laravel Valet、MAMP、Local WP 等），可能会遇到身份验证错误。要解决此问题：

在 .env 文件中添加：

MCP_ALLOW_SELF_SIGNED_CERTS=true

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

身份验证错误

确认 API 密钥正确
验证用户具有适当的 Gravity Forms 能力
检查 Forms → 设置 → REST API 中的密钥状态
对于本地开发，如果使用自签名证书，请确保 MCP_ALLOW_SELF_SIGNED_CERTS=true 已设置

调试模式

启用详细日志：

GRAVITY_FORMS_DEBUG=true

支持

许可证

GPL-2.0 许可证 - 详情见 LICENSE 文件。

贡献

我们欢迎来自 Gravity Forms 社区的贡献！无论您是构建插件、管理表单还是与其他服务集成，您的见解和代码贡献都能帮助所有人。

如何贡献

分叉仓库 - 从创建自己的副本开始
创建功能分支 - 保持更改有序
添加测试 - 通过测试覆盖率确保可靠性
运行测试套件 - 使用 npm run test:all 验证一切正常
提交拉取请求 - 与社区分享您的改进

自动发布

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

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

维护人员注意：确保在仓库设置中配置了 NPM_TOKEN 秘密，以便自动发布能正常工作。

贡献想法

对于插件开发者：

为您的插件数据源类型添加支持
增强自定义字段的字段类型定义
分享有效的集成模式

对于表单构建者：

改进字段验证逻辑
添加用于常见任务的帮助程序实用程序
增强错误消息和调试

对于所有人：

通过 GitHub Issues 报告错误或提出功能建议
改进文档和示例
分享您的使用案例和工作流

您的贡献有助于让 Gravity Forms 自动化对所有人来说都更好。让我们一起打造一些伟大的东西！