STARWARCLOUD STARWAR.AI
返回市场
重力MCP服务器

重力MCP服务器

作者：GravityKit12 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

MCP for Gravity Forms

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

npm 版本

由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

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

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

  4. 在WordPress中生成API凭据：

    • 转到表单 → 设置 → REST API
    • 点击添加密钥
    • 保存消费者密钥和秘密

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

可用工具

表单（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 m
cp.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

测试模式检测

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

  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是否已启用

使用自签名证书的本地开发

如果你正在使用带有自签名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社区的贡献！无论你是构建插件、管理表单还是与其他服务集成，你的见解和代码贡献都能帮助所有人。

如何贡献

  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自动化更好。让我们一起打造一些伟大的东西！