JinDaGe - clappia-mcp MCP Details

article

README

🚀 Clappia MCP (模型上下文协议)

Clappia MCP 是一个基于 Python 的服务器，它为与 Clappia 平台进行交互提供了全面的接口。借助该服务器，用户可以通过编程方式管理 Clappia 应用程序、表单、提交内容等。

Clappia 是一个无代码平台，企业、运营团队和非开发人员无需编写任何代码，即可创建自定义应用程序，如检查表单、审批工作流、现场数据收集工具、内部仪表盘等。它广泛应用于各个行业，用于自动化手动流程、数字化纸质文件以及提高运营效率。点击此处了解更多信息。

✨ 主要特性

应用管理
- 创建具有可自定义部分和字段的新 Clappia 应用程序。
- 获取包含字段元数据的详细应用程序定义。
提交管理
- 使用字段数据创建新的提交内容。
- 对现有提交内容进行验证编辑。
- 更新提交状态，并可选择添加注释。
- 通过基于电子邮件的分配方式管理提交所有者。
- 使用高级过滤和分页功能检索提交内容。
- 获取具有可自定义维度的提交聚合数据，用于分析。
字段管理
- 添加具有全面配置选项的新字段。
- 更新字段属性，包括验证规则、显示条件和布局。
- 配置字段验证（数字、电子邮件、URL、自定义）。
- 设置字段显示和可编辑性的条件逻辑。
- 使用响应式设计选项管理字段布局。

📦 安装指南

前提条件

Python 3.8 或更高版本
uv Python 包管理器
访问 Clappia API 密钥和工作区 ID
Claude for Desktop（或任何其他 MCP 客户端）

安装步骤

设置 Clappia API 访问权限
- 访问 Clappia 中的工作区（https://<your_workplace>.clappia.com），你需要具备该工作区的工作区管理员权限。
- 访问工作区设置，记录你的工作区 ID。
- 访问工作区设置 -> 首选项 -> API 密钥，记录你的 API 密钥，如果尚未生成，请生成一个。
设置 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

设置 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 请求进行连接池管理。
高效构建有效负载。
正确清理资源。
优化日志记录。
优化错误处理。

支持

如需支持，请：

查看文档。
查看现有问题。
如有需要，创建新问题。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

API 集成

Clappia 公共 API

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

身份验证
- 基于 API 密钥的身份验证
- 安全的凭证管理
- 支持速率限制
端点
- 应用程序管理
- 表单提交
- 字段操作
- 用户管理
- 分析和报告
API 文档
- 访问 Clappia 开发者门户以获取：
  - API 参考
  - 身份验证指南
  - 速率限制
  - 最佳实践
  - 示例实现
API 版本控制
- 当前稳定版本：v1
- 保持向后兼容性
- 提供弃用通知

clappia-mcp