README.md•9.81 kB
# JianDaoYun MCP Server
一个用于简道云表单数据管理的 MCP (Model Context Protocol) 服务，支持完整的CRUD操作和高级查询功能。
## 功能特性
- 🔍 **表单字段查询**: 获取表单的字段定义，包括字段类型、必填状态等
- 📝 **智能数据提交**: 自动匹配字段类型并转换数据格式
- 🔄 **批量操作支持**: 支持单条或批量提交/删除（最多100条）
- 🎯 **字段智能匹配**: 支持通过字段key、字段名称等多种方式匹配
- 🔐 **安全认证**: 使用Bearer Token认证机制
- 📊 **高级查询**: 支持数据筛选器、分页查询
- 📁 **文件上传**: 获取文件上传凭证
## 安装
```bash
cd jiandaoyun-mcp-server
npm install
npm run build
```
## 配置
在使用前，只需要设置简道云的API Key作为环境变量：
```bash
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）
**筛选器示例:**
```json
{
"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` 中添加：
```json
{
"mcpServers": {
"jiandaoyun": {
"command": "npx",
"args": ["jiandaoyun-mcp-server"],
"env": {
"JIANDAOYUN_APP_KEY": "your_app_key"
}
}
}
}
```
#### 方法二：使用本地安装
```bash
# 全局安装
npm install -g jiandaoyun-mcp-server
# 或本地安装
npm install jiandaoyun-mcp-server
```
配置文件：
```json
{
"mcpServers": {
"jiandaoyun": {
"command": "jiandaoyun-mcp",
"env": {
"JIANDAOYUN_APP_KEY": "your_app_key"
}
}
}
}
```
#### 方法三：使用 Node.js 直接运行
```json
{
"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方式，无需手动安装和维护本地文件
### 获取表单字段
```javascript
// 获取表单字段定义
const fields = await get_form_fields({
appId: "your_app_id",
appKey: "your_app_key",
formId: "your_form_id"
});
```
### 提交数据
```javascript
// 提交单条数据
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 }
]
});
```
### 查询数据
```javascript
// 查询所有数据
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
});
```
### 列出应用和表单
```javascript
// 列出所有应用
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"
});
```
### 数据提交示例
```javascript
// 单条数据提交（使用字段别名）
{
"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
}
```
## 开发
```bash
# 开发模式
npm run dev
# 构建
npm run build
# 启动服务
npm start
```
## 错误处理
服务会自动处理以下情况：
- API认证失败
- 网络错误
- 字段不匹配警告
- 数据格式转换错误
## 许可证
MIT