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

利用可能なツール

フォーム（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 - リクエストタイムアウト（ミリ秒）
• 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インスペクターで対話型テストを行う（テストモード）
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 Documentation
• MCP Documentation

📄 ライセンス

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の自動化が皆さんにとってより良いものになります。一緒に素晴らしいものを作りましょう！