jiandaoyun-mcp-server

cheungxin/jiandaoyun-mcp-server

3.2

If you are the rightful owner of jiandaoyun-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

JianDaoYun MCP Server is a Model Context Protocol service designed for managing form data in JianDaoYun, offering comprehensive CRUD operations and advanced query capabilities.

Tools

  1. get_form_fields

    Retrieve form field definitions.

  2. submit_form_data

    Submit data to a form with automatic field type matching.

  3. get_form_data

    Retrieve specific data records from a form.

  4. query_form_data

    Query multiple data records with filtering and pagination.

  5. update_form_data

    Update existing data records.

  6. delete_form_data

    Delete one or more data records.

  7. get_upload_token

    Retrieve file upload credentials.

  8. list_apps_and_forms

    List accessible applications or forms within a specified application.

JianDaoYun MCP Server

一个用于简道云表单数据管理的 MCP (Model Context Protocol) 服务，支持完整的CRUD操作和高级查询功能。

功能特性

  • 🔍 表单字段查询: 获取表单的字段定义，包括字段类型、必填状态等
  • 📝 智能数据提交: 自动匹配字段类型并转换数据格式
  • 🔄 批量操作支持: 支持单条或批量提交/删除（最多100条）
  • 🎯 字段智能匹配: 支持通过字段key、字段名称等多种方式匹配
  • 🔐 安全认证: 使用Bearer Token认证机制
  • 📊 高级查询: 支持数据筛选器、分页查询
  • 📁 文件上传: 获取文件上传凭证

安装

cd jiandaoyun-mcp-server
npm install
npm run build

配置

在使用前，只需要设置简道云的API Key作为环境变量：

export JIANDAOYUN_APP_KEY="your_app_key"
export JIANDAOYUN_BASE_URL="https://api.jiandaoyun.com/api" # 可选

或者在 .env 文件中设置：

JIANDAOYUN_APP_KEY=your_app_key
JIANDAOYUN_BASE_URL=https://api.jiandaoyun.com/api

注意： 从v2.0开始，APP_ID不再作为环境变量配置，而是在每次调用MCP工具时作为参数传入。这样可以让一个MCP服务器实例支持多个简道云应用，用户可以动态指定要操作的应用。

MCP 工具说明

1. get_form_fields

获取表单的字段定义信息。

参数:

  • appId (string): 简道云应用ID
  • appKey (string): 简道云API密钥
  • formId (string): 表单ID（支持应用ID或完整表单ID）

返回: 表单字段列表，包含字段key、名称、类型等信息

2. submit_form_data

提交数据到表单，支持自动字段类型匹配。

参数:

  • appId (string): 简道云应用ID
  • appKey (string): 简道云API密钥
  • formId (string): 表单ID（支持应用ID或完整表单ID）
  • data (object|array): 要提交的数据（单个对象或数组）
  • autoMatch (boolean): 是否自动匹配字段类型（默认: true）
  • transactionId (string): 可选的事务ID，用于幂等提交

返回: 提交结果

3. get_form_data

获取表单中的特定数据记录。

参数:

  • appId (string): 简道云应用ID
  • appKey (string): 简道云API密钥
  • formId (string): 表单ID（支持应用ID或完整表单ID）
  • dataId (string): 数据记录ID

返回: 数据记录详情

4. query_form_data

查询多条数据，支持筛选和分页。

参数:

  • appId (string): 简道云应用ID
  • appKey (string): 简道云API密钥
  • formId (string): 表单ID（支持应用ID或完整表单ID）
  • dataId (string): 可选，用于分页的最后一条数据ID
  • fields (array): 可选，要返回的字段列表（widget IDs）
  • filter (object): 可选，数据筛选条件
  • limit (number): 可选，返回记录数（1-100，默认10）

筛选器示例:

{
  "rel": "and",
  "cond": [
    {
      "field": "_widget_1508400000001",
      "type": "text",
      "method": "eq",
      "value": "张三"
    },
    {
      "field": "_widget_1508400000002",
      "type": "number",
      "method": "range",
      "value": [20, 30]
    }
  ]
}

5. update_form_data

更新已有数据记录。

参数:

  • appId (string): 简道云应用ID
  • appKey (string): 简道云API密钥
  • formId (string): 表单ID（支持应用ID或完整表单ID）
  • dataId (string): 要更新的数据ID
  • data (object): 更新的数据内容
  • transactionId (string): 可选的事务ID
  • isStartTrigger (boolean): 是否触发自动化流程

返回: 更新结果

6. delete_form_data

删除一条或多条数据记录。

参数:

  • appId (string): 简道云应用ID
  • appKey (string): 简道云API密钥
  • formId (string): 表单ID（支持应用ID或完整表单ID）
  • dataIds (string|array): 要删除的数据ID（单个字符串或数组）
  • isStartTrigger (boolean): 是否触发自动化流程

返回: 删除结果

7. get_upload_token

获取文件上传凭证。

参数:

  • appId (string): 简道云应用ID
  • appKey (string): 简道云API密钥
  • formId (string): 表单ID（支持应用ID或完整表单ID）
  • transactionId (string): 事务ID，上传的文件将绑定到此事务

返回: 文件上传凭证和上传地址（最多100个）

8. list_apps_and_forms

列出所有可访问的应用，或获取指定应用下的表单列表

参数:

  • appKey (string): 简道云API密钥
  • appId (string): 可选，如果提供则返回该应用下的表单列表

返回: 应用列表或表单列表

字段类型支持

支持的字段类型及自动转换规则：

  • 文本 (text): 自动转换为字符串
  • 数字 (number): 自动解析为数字
  • 日期/日期时间 (date/datetime): 支持多种日期格式，自动转换为ISO格式
  • 单选/多选 (select/multi_select): 自动处理数组格式
  • 复选框 (checkbox): 自动转换为布尔值
  • 用户/部门 (user/dept): 支持单个或多个ID
  • 文件/图片 (file/image): 支持URL或文件对象格式
  • 地理位置 (location): 支持对象或字符串格式
  • 地址 (address): 支持省市区详细地址格式
  • 手机号 (phone): 支持对象格式 {phone: "15812345678"}
  • 子表单 (subform): 递归处理子表单数据
  • 流水号 (sn): 只读字段，自动生成

使用示例

在 Claude Desktop 中配置

方法一：使用 npx（推荐）

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "jiandaoyun": {
      "command": "npx",
      "args": ["jiandaoyun-mcp-server"],
      "env": {
        "JIANDAOYUN_APP_KEY": "your_app_key"
      }
    }
  }
}
方法二：使用本地安装
# 全局安装
npm install -g jiandaoyun-mcp-server

# 或本地安装
npm install jiandaoyun-mcp-server

配置文件：

{
  "mcpServers": {
    "jiandaoyun": {
      "command": "jiandaoyun-mcp",
      "env": {
        "JIANDAOYUN_APP_KEY": "your_app_key"
      }
    }
  }
}
方法三：使用 Node.js 直接运行
{
  "mcpServers": {
    "jiandaoyun": {
      "command": "node",
      "args": ["/path/to/jiandaoyun-mcp-server/build/index.js"],
      "env": {
        "JIANDAOYUN_APP_KEY": "your_app_key"
      }
    }
  }
}

配置说明：

  • 将 your_app_key 替换为你的简道云API密钥
  • 从v2.0开始，APP_ID作为工具参数传入，无需在环境变量中配置
  • 推荐使用npx方式，无需手动安装和维护本地文件

获取表单字段

// 获取表单字段定义
const fields = await get_form_fields({
  appId: "your_app_id",
  appKey: "your_app_key",
  formId: "your_form_id"
});

提交数据

// 提交单条数据
const result = await submit_form_data({
  appId: "your_app_id",
  appKey: "your_app_key",
  formId: "your_form_id",
  data: {
    "姓名": "张三",
    "年龄": 25,
    "邮箱": "zhangsan@example.com"
  }
});

// 批量提交数据
const batchResult = await submit_form_data({
  appId: "your_app_id",
  appKey: "your_app_key",
  formId: "your_form_id",
  data: [
    { "姓名": "张三", "年龄": 25 },
    { "姓名": "李四", "年龄": 30 }
  ]
});

查询数据

// 查询所有数据
const allData = await query_form_data({
  appId: "your_app_id",
  appKey: "your_app_key",
  formId: "your_form_id"
});

// 带条件查询
const filteredData = await query_form_data({
  appId: "your_app_id",
  appKey: "your_app_key",
  formId: "your_form_id",
  filter: {
    rel: "and",
    cond: [
      {
        field: "age_field_id",
        method: "gte",
        value: 18
      }
    ]
  },
  limit: 10
});

列出应用和表单

// 列出所有应用
const apps = await list_apps_and_forms({
  appKey: "your_app_key"
});

// 获取特定应用下的表单列表
const forms = await list_apps_and_forms({
  appKey: "your_app_key",
  appId: "your_app_id"
});

数据提交示例

// 单条数据提交（使用字段别名）
{
  "formId": "5f3e4d2c1b0a9",
  "data": {
    "姓名": "张三",
    "年龄": 25,
    "入职日期": "2024-01-15",
    "部门": ["dept_001"],
    "技能": ["JavaScript", "Python"],
    "手机号": { "phone": "15812345678" },
    "地址": {
      "province": "江苏省",
      "city": "无锡市",
      "district": "滨湖区",
      "detail": "太湖大道1000号"
    },
    "简历": { "url": "https://example.com/resume.pdf" }
  }
}

// 使用widget ID提交（推荐）
{
  "formId": "5f3e4d2c1b0a9",
  "data": {
    "_widget_1432728651402": "张三",
    "_widget_1432728651403": 25,
    "_widget_1432728651407": "2024-01-15T00:00:00.000Z",
    "_widget_1432728651413": {
      "province": "江苏省",
      "city": "无锡市",
      "district": "滨湖区",
      "detail": "太湖大道1000号",
      "lnglatXY": [120.31237, 31.49099]
    }
  }
}

// 批量数据提交
{
  "formId": "5f3e4d2c1b0a9",
  "data": [
    { "姓名": "张三", "年龄": 25 },
    { "姓名": "李四", "年龄": 30 }
  ]
}

// 数据查询示例
{
  "formId": "5f3e4d2c1b0a9",
  "filter": {
    "rel": "and",
    "cond": [
      {
        "field": "_widget_1508400000001",
        "type": "text",
        "method": "eq",
        "value": "张三"
      },
      {
        "field": "createTime",
        "method": "range",
        "value": ["2024-01-01", null]
      }
    ]
  },
  "limit": 50
}

开发

# 开发模式
npm run dev

# 构建
npm run build

# 启动服务
npm start

错误处理

服务会自动处理以下情况：

  • API认证失败
  • 网络错误
  • 字段不匹配警告
  • 数据格式转换错误

许可证

MIT