Clappia MCP

🚀 Clappia MCP (模型上下文協議)

Clappia MCP 是一個基於 Python 的服務器，它為與 Clappia 平臺進行交互提供了全面的接口。藉助該服務器，用戶可以通過編程方式管理 Clappia 應用程序、表單、提交內容等。

Clappia 是一個無代碼平臺，企業、運營團隊和非開發人員無需編寫任何代碼，即可創建自定義應用程序，如檢查表單、審批工作流、現場數據收集工具、內部儀表盤等。它廣泛應用於各個行業，用於自動化手動流程、數字化紙質文件以及提高運營效率。點擊此處瞭解更多信息。

✨ 主要特性

• 應用管理
  • 創建具有可自定義部分和字段的新 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 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：單行文本輸入
  • 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 公共 API

MCP 服務器與 Clappia 的公共 API 集成，提供以下功能：

1. 身份驗證
   • 基於 API 密鑰的身份驗證
   • 安全的憑證管理
   • 支持速率限制
2. 端點
   • 應用程序管理
   • 表單提交
   • 字段操作
   • 用戶管理
   • 分析和報告
3. API 文檔
   • 訪問 Clappia 開發者門戶 以獲取：
     • API 參考
     • 身份驗證指南
     • 速率限制
     • 最佳實踐
     • 示例實現
4. API 版本控制
   • 當前穩定版本：v1
   • 保持向後兼容性
   • 提供棄用通知