clappia-mcp

Clappia MCP（Model Context Protocol）

Clappia プラットフォームを操作するための包括的なインターフェースを提供する、Python ベースの MCP サーバーです。このサーバーを使うと、Clappia アプリ、フォーム、送信内容などをプログラムから管理できます。

Clappia は、企業、運用チーム、開発者以外のユーザーが、コードを一切書かずに、検査フォーム、承認ワークフロー、現場データ収集ツール、社内ダッシュボードなどのカスタムアプリを作成できるノーコードプラットフォームです。手作業のプロセスの自動化、書類のデジタル化、業務効率の向上を目的として、さまざまな業界で利用されています。詳しくはこちらをご覧ください。

機能

• アプリ管理

  • カスタマイズ可能なセクションとフィールドを含む、新しい Clappia アプリを作成します

  • フィールドのメタデータを含む、詳細なアプリ定義を取得します

• 送信内容の管理

  • フィールドデータを含む新しい送信内容を作成します
  • 既存の送信内容を検証しながら編集します
  • 任意のコメントを添えて送信内容のステータスを更新します
  • メールアドレスを指定して送信内容の所有者を管理します
  • 高度なフィルタリングとページネーションを使って送信内容を取得します
  • カスタマイズ可能なディメンションを使って、分析用の送信内容の集計を取得します

• フィールド管理

  • 豊富な設定オプションを使って新しいフィールドを追加します
  • 検証、表示条件、レイアウトなどのフィールドプロパティを更新します
  • フィールドの検証（数値、メールアドレス、URL、カスタム）を設定します
  • フィールドの表示と編集可能性に関する条件付きロジックを設定します
  • レスポンシブデザインのオプションを使ってフィールドのレイアウトを管理します

前提条件

• Python 3.8 以降
• uv Python パッケージマネージャー
• Clappia API Key と Workplace ID へのアクセス
• Claude for Desktop（またはその他の MCP クライアント）

インストール

1. Clappia API アクセスを設定する：

   • Clappia の Workplace（https://<your_workplace>.clappia.com）にアクセスします。この Workplace の Workplace Manager アクセス権が必要です。
   • Workplace Settings にアクセスし、Workplace ID を控えます。
   • Workplace Settings -> Preferences -> API Keys にアクセスし、API Key を控えます。まだ生成していない場合は、生成してください。

2. Claude for Desktop を設定する：

   • macOS または Windows 用の Claude for Desktop をダウンロードします
   • Claude for Desktop をインストールして起動します
   • Claude メニュー → Settings → Developer → Edit Config を開きます
   • 次の設定を claude_desktop_config.json に追加します：

     {
        "mcpServers": {
           "clappia-mcp": {
              "command": "uv",
              "args": [
                 "--directory",
                 "/Users/<YOUR_DIECTORY>/Desktop/clappia-mcp",
                 "run",
                 "clappia-mcp.py"
              ],
              "env": {
                 "CLAPPIA_API_KEY": "<ENTER_YOUR_WORKPLACE_API_KEY_HERE>",
                 "CLAPPIA_WORKPLACE_ID": "<ENTER_YOUR_WORKPLACE_ID_HERE>"
              }
           }
        }
     }
     

   • Claude for Desktop を再起動します
   • 入力ボックスにツールアイコンが表示されることを確認し、MCP サーバーが実行中であることを確認します

3. リポジトリをクローンする：

   git clone https://github.com/clappia-dev/clappia-mcp.git
   cd clappia-mcp
   

4. Python 環境を設定する：

   # Install uv if not already installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies
   uv sync
   

プロジェクト構成

clappia-mcp/
├── clappia-mcp.py          # Main MCP server implementation
├── tools/                  # Core functionality modules
│   ├── add_field.py        # Field addition functionality
│   ├── create_app.py       # App creation functionality
│   ├── create_submission.py # Submission creation
│   ├── edit_submission.py  # Submission editing
│   ├── get_definition.py   # App definition retrieval
│   ├── get_submissions.py  # Submission retrieval
│   ├── get_submissions_aggregation.py # Analytics functionality
│   ├── update_field.py     # Field update functionality
│   ├── update_submission_owners.py # Owner management
│   └── update_submission_status.py # Status management
├── pyproject.toml         # Project metadata and dependencies
├── uv.lock               # Dependency lock file (if using uv)
└── .env                  # Environment variables

使用方法

• Claude Desktop の起動時にサーバーが自動的に起動します
• Claude Desktop のインターフェースからツールにアクセスします

トラブルシューティング

1. サーバーが起動しない場合：

   • Claude Desktop のログでエラーを確認します
   • Python 環境が有効化されていることを確認します
   • すべての依存関係がインストールされていることを確認します
   • 環境変数が正しく設定されていることを確認します

2. API 接続の問題：

   • claude_desktop_config.json ファイル内の API 認証情報を確認します
   • ネットワーク接続を確認します
   • API のレート制限を確認します

3. ツールの実行に失敗する場合：

   • サーバーログで詳細なエラーメッセージを確認します
   • 入力パラメーターが API の要件に合っていることを確認します
   • API 操作に必要な権限があることを確認します

API 呼び出しの例

1. 新しいアプリケーションを作成

   from tools.create_app import create_app, Section, Field
   
   result = create_app(
       app_name="Employee Survey",
       requesting_user_email_address="[email protected]",
       sections=[
           Section(
               sectionName="Personal Information",
               fields=[
                   Field(
                       fieldType="singleLineText",
                       label="Full Name",
                       required=True
                   )
               ]
           )
       ]
   )
   

2. アプリケーションにフィールドを追加

   from tools.add_field import add_field_to_app
   
   result = add_field_to_app(
       app_id="APP123",
       requesting_user_email_address="[email protected]",
       section_index=0,
       field_index=1,
       field_type="singleLineText",
       label="Employee ID",
       required=True,
       validation="number",
       block_width_percentage_desktop=50,
       block_width_percentage_mobile=100
   )
   

3. フィールドを更新

   from tools.update_field import update_field_in_app
   
   result = update_field_in_app(
       app_id="APP123",
       requesting_user_email_address="[email protected]",
       field_name="employeeName",
       label="Full Employee Name",
       required=True,
       validation="none",
       display_condition="status == 'active'"
   )
   

4. 送信データを作成

   from tools.create_submission import create_app_submission
   
   result = create_app_submission(
       app_id="APP123",
       data={"employeeName": "John Doe", "employeeId": "12345"},
       email="[email protected]"
   )
   

5. フィルタリングして送信データを取得

   from tools.get_submissions import get_app_submissions, Filters, QueryGroup, Query, Condition
   
   filters = Filters(queries=[
       QueryGroup(queries=[
           Query(
               conditions=[
                   Condition(
                       operator="EQ",
                       filterKeyType="STANDARD",
                       key="status",
                       value="active"
                   )
               ],
               operator="AND"
           )
       ])
   ])
   
   result = get_app_submissions(
       app_id="APP123",
       requesting_user_email_address="[email protected]",
       page_size=10,
       filters=filters
   )
   

API ドキュメント

フィールドの種類

• テキストフィールド

  • singleLineText：1 行のテキスト入力
  • multiLineText：複数行のテキスト入力
  • richTextEditor：書式設定機能付きのリッチテキストエディター

• セレクターフィールド

  • singleSelector：単一選択
  • multiSelector：複数選択
  • dropDown：ドロップダウン選択

• 日付／時刻フィールド

  • dateSelector：日付選択
  • timeSelector：時刻選択
  • dateTime：日付と時刻を組み合わせて選択

• ファイルフィールド

  • file：種類を設定できるファイルアップロード
  • camera：カメラで直接撮影
  • signature：電子署名の取得

• 高度なフィールド

  • calculationsAndLogic：数式ベースの計算
  • gpsLocation：位置情報の追跡
  • codeScanner：バーコード／QR コードのスキャン
  • nfcReader：NFC タグの読み取り
  • liveTracking：リアルタイムの位置情報追跡
  • address：検証機能付きの住所入力

検証の種類

• none：検証なし
• number：数値の検証
• email：メールアドレス形式の検証
• url：URL 形式の検証
• custom：カスタム検証ルール

フィールドのプロパティ

• レイアウト

  • block_width_percentage_desktop：デスクトップでの幅（25、50、75、100）
  • block_width_percentage_mobile：モバイルでの幅（50、100）
  • number_of_cols：セレクターフィールドの列数

• 動作

  • required：フィールドが必須かどうか
  • is_editable：フィールドを編集できるかどうか
  • hidden：フィールドを非表示にするかどうか
  • retain_values：非表示のときに値を保持するかどうか

• 条件

  • display_condition：フィールドの表示条件
  • editability_condition：フィールドの編集可否条件

• ファイル設定

  • allowed_file_types：許可されているファイル形式の一覧
  • max_file_allowed：アップロード可能なファイルの最大数（1～10）
  • image_quality：画像品質（低、中、高）
  • file_name_prefix：アップロードファイルの接頭辞

エラー処理

サーバーでは、以下を対象とした包括的なエラー処理を実装しています。

• 無効な API 認証情報
• ネットワーク接続の問題
• 無効な入力パラメーター
• API のレート制限
• サーバーエラー

デバッグに必要なコンテキスト情報を含め、すべてのエラーをログに記録します。

セキュリティ

• API キーは環境変数に保存されます
• すべての API 呼び出しは HTTPS 経由で行われます
• すべてのパラメーターに入力検証を実装しています
• レート制限に対応しています
• エラーメッセージはサニタイズされます

パフォーマンスに関する考慮事項

• API リクエストにコネクションプーリングを使用
• ペイロードを効率的に構築
• リソースを適切に解放
• ログ記録を最適化
• エラー処理を最適化

サポート

サポートを受けるには、以下を行ってください。

1. ドキュメントを確認する
2. 既存の課題を確認する
3. 必要に応じて新しい課題を作成する

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

API 連携

Clappia Public API

MCP サーバーは Clappia の Public API と連携し、以下の機能を提供します。

1. 認証：

   • API キーベースの認証
   • 認証情報の安全な管理
   • レート制限への対応

2. エンドポイント：

   • アプリケーション管理
   • フォーム送信データ
   • フィールド操作
   • ユーザー管理
   • 分析とレポート作成

3. API ドキュメント：

   • Clappia Developer Portal にアクセスすると、以下を確認できます。
     • API リファレンス
     • 認証ガイド
     • レート制限
     • ベストプラクティス
     • 実装例

4. API のバージョン管理：

   • 現在の安定版：v1
   • 後方互換性を維持
   • 非推奨化の通知を提供