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): 简道云应用IDappKey(string): 简道云API密钥formId(string): 表单ID（支持应用ID或完整表单ID）
返回: 表单字段列表，包含字段key、名称、类型等信息
2. submit_form_data
提交数据到表单，支持自动字段类型匹配。
参数:
appId(string): 简道云应用IDappKey(string): 简道云API密钥formId(string): 表单ID（支持应用ID或完整表单ID）data(object|array): 要提交的数据（单个对象或数组）autoMatch(boolean): 是否自动匹配字段类型（默认: true）transactionId(string): 可选的事务ID，用于幂等提交
返回: 提交结果
3. get_form_data
获取表单中的特定数据记录。
参数:
appId(string): 简道云应用IDappKey(string): 简道云API密钥formId(string): 表单ID（支持应用ID或完整表单ID）dataId(string): 数据记录ID
返回: 数据记录详情
4. query_form_data
查询多条数据，支持筛选和分页。
参数:
appId(string): 简道云应用IDappKey(string): 简道云API密钥formId(string): 表单ID（支持应用ID或完整表单ID）dataId(string): 可选，用于分页的最后一条数据IDfields(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): 简道云应用IDappKey(string): 简道云API密钥formId(string): 表单ID（支持应用ID或完整表单ID）dataId(string): 要更新的数据IDdata(object): 更新的数据内容transactionId(string): 可选的事务IDisStartTrigger(boolean): 是否触发自动化流程
返回: 更新结果
6. delete_form_data
删除一条或多条数据记录。
参数:
appId(string): 简道云应用IDappKey(string): 简道云API密钥formId(string): 表单ID（支持应用ID或完整表单ID）dataIds(string|array): 要删除的数据ID（单个字符串或数组）isStartTrigger(boolean): 是否触发自动化流程
返回: 删除结果
7. get_upload_token
获取文件上传凭证。
参数:
appId(string): 简道云应用IDappKey(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