Gravitymcp

交流 JavaScript

🚀 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 站点（认证所需）。

📦 安装指南

克隆仓库

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

在 WordPress 中生成 API 凭证：
- 访问 Forms → Settings → REST API。
- 点击 Add Key。
- 保存消费者密钥和密钥密码。

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

测试模式检测

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

设置 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。

认证错误

确认 API 密钥正确。
验证用户是否具备适当的 Gravity Forms 权限。
查看 Forms → Settings → REST API 中的密钥状态。

调试模式

启用详细日志：

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

0 条评论
分类：交流