Clappia MCP

🚀 Clappia MCP (Model Context Protocol)

Clappia MCPは、PythonベースのMCPサーバーで、Clappiaプラットフォームとの包括的なインターフェースを提供します。このサーバーを使用すると、Clappiaのアプリケーション、フォーム、提出物などをプログラムで管理することができます。

Clappiaはノーコードプラットフォームで、ビジネス、オペレーションチーム、非開発者がコードを1行も書かずに、検査フォーム、承認ワークフロー、現場データ収集ツール、内部ダッシュボードなどのカスタムアプリを作成できます。手動プロセスの自動化、書類の電子化、運用効率の向上など、様々な業界で利用されています。こちらをクリックして詳細を学ぶことができます。

✨ 主な機能

アプリ管理

• カスタマイズ可能なセクションとフィールドを持つ新しいClappiaアプリを作成
• フィールドメタデータを含む詳細なアプリ定義を取得

提出物管理

• フィールドデータを含む新しい提出物を作成
• 検証付きで既存の提出物を編集
• オプションのコメント付きで提出物のステータスを更新
• メールベースの割り当てで提出物の所有者を管理
• 高度なフィルタリングとページネーションで提出物を取得
• カスタマイズ可能な次元で分析用の提出物集計を取得

フィールド管理

• 包括的な構成オプションで新しいフィールドを追加
• 検証、表示条件、レイアウトを含むフィールドプロパティを更新
• フィールド検証（数値、メール、URL、カスタム）を構成
• フィールドの表示と編集可能条件の条件付きロジックを設定
• レスポンシブデザインオプションでフィールドレイアウトを管理

📦 インストール

前提条件

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

インストール手順

1. Clappia APIアクセスの設定
   • Clappiaのワークプレイス（https://<your_workplace>.clappia.com）にアクセスします。このワークプレイスに対するワークプレイスマネージャーアクセスが必要です。
   • ワークプレイス設定を開き、ワークプレイスIDをメモします。
   • ワークプレイス設定 → 設定 → APIキーを開き、APIキーをメモします。未生成の場合は、新しく生成します。
2. Claude for Desktopの設定
   • macOSまたはWindows用のClaude for Desktopをダウンロードします。
   • インストールして起動します。
   • Claudeメニュー → 設定 → 開発者 → 設定の編集を開きます。
   • 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環境の設定

   # uvがまだインストールされていない場合はインストールします
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # 依存関係をインストールします
   uv sync
   

💻 使用例

基本的な使用法

新しいアプリケーションの作成

from tools.create_app import create_app, Section, Field

result = create_app(
    app_name="Employee Survey",
    requesting_user_email_address="user@company.com",
    sections=[
        Section(
            sectionName="Personal Information",
            fields=[
                Field(
                    fieldType="singleLineText",
                    label="Full Name",
                    required=True
                )
            ]
        )
    ]
)

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

from tools.add_field import add_field_to_app

result = add_field_to_app(
    app_id="APP123",
    requesting_user_email_address="user@company.com",
    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
)

フィールドの更新

from tools.update_field import update_field_in_app

result = update_field_in_app(
    app_id="APP123",
    requesting_user_email_address="user@company.com",
    field_name="employeeName",
    label="Full Employee Name",
    required=True,
    validation="none",
    display_condition="status == 'active'"
)

提出物の作成

from tools.create_submission import create_app_submission

result = create_app_submission(
    app_id="APP123",
    data={"employeeName": "John Doe", "employeeId": "12345"},
    email="user@company.com"
)

フィルタリングで提出物を取得

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="user@company.com",
    page_size=10,
    filters=filters
)

📚 ドキュメント

フィールドタイプ

• テキストフィールド
  • 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リクエストのコネクションプーリング
• 効率的なペイロード構築
• 適切なリソースクリーンアップ
• ロギングの最適化
• エラー処理の最適化

📄 ライセンス

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

API統合

Clappia Public API

MCPサーバーは、ClappiaのパブリックAPIと統合されており、以下の機能を提供します。

1. 認証
   • APIキーベースの認証
   • 安全な資格情報管理
   • レート制限サポート
2. エンドポイント
   • アプリケーション管理
   • フォーム提出
   • フィールド操作
   • ユーザー管理
   • 分析とレポート
3. APIドキュメント
   • Clappia Developer Portalを訪問すると、以下の情報が得られます。
     • APIリファレンス
     • 認証ガイド
     • レート制限
     • ベストプラクティス
     • 実装例
4. APIバージョニング
   • 現在の安定版：v1
   • 下位互換性が維持されています。
   • 非推奨通知が提供されます。