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
   • 保持向后兼容性
   • 提供弃用通知