clappia-mcp

Clappia MCP（模型上下文协议）

一个基于 Python 的 MCP 服务，提供与 Clappia 平台交互的全面接口。此服务支持以编程方式管理 Clappia 应用、表单、提交内容等。

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

功能

• 应用管理

  • 创建新的 Clappia 应用，并自定义分区和字段

  • 获取包含字段元数据的详细应用定义

• 提交管理

  • 使用字段数据创建新的提交内容
  • 编辑现有提交内容并进行验证
  • 更新提交状态，并可选择添加评论
  • 通过电子邮件分配管理提交所有者
  • 使用高级筛选和分页功能检索提交内容
  • 获取提交内容的聚合数据，用于分析并支持自定义维度

• 字段管理

  • 添加新的字段，并提供全面的配置选项
  • 更新字段属性，包括验证、显示条件和布局
  • 配置字段验证（数字、电子邮件、URL、自定义）
  • 设置控制字段显示和可编辑性的条件逻辑
  • 使用响应式设计选项管理字段布局

前提条件

• Python 3.8 或更高版本
• uv Python 包管理器
• Clappia API Key 和 Workplace ID 的访问权限
• Claude 桌面版（或其他 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 桌面版：

   • 下载适用于 macOS 或 Windows 的 Claude 桌面版
   • 安装并启动 Claude 桌面版
   • 打开 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 桌面版
   • 检查输入框中的工具图标，确认 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：单行文本输入
  • 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
   • 保持向后兼容
   • 提供弃用通知