Content
# JianDaoYun MCP Server
A MCP (Model Context Protocol) service for managing JianDaoYun form data, supporting complete CRUD operations and advanced query functionalities.
## Features
- 🔍 **Form Field Query**: Retrieve the field definitions of a form, including field types, required status, etc.
- 📝 **Smart Data Submission**: Automatically match field types and convert data formats.
- 🔄 **Batch Operation Support**: Support for single or batch submission/deletion (up to 100 records).
- 🎯 **Intelligent Field Matching**: Support matching through field keys, field names, and more.
- 🔐 **Secure Authentication**: Uses Bearer Token authentication mechanism.
- 📊 **Advanced Query**: Supports data filters and pagination.
- 📁 **File Upload**: Obtain file upload credentials.
## Installation
```bash
cd jiandaoyun-mcp-server
npm install
npm run build
```
## Configuration
Before use, simply set the JianDaoYun API Key as an environment variable:
```bash
export JIANDAOYUN_APP_KEY="your_app_key"
export JIANDAOYUN_BASE_URL="https://api.jiandaoyun.com/api" # Optional
```
Or set it in the `.env` file:
```
JIANDAOYUN_APP_KEY=your_app_key
JIANDAOYUN_BASE_URL=https://api.jiandaoyun.com/api
```
**Note:** Starting from v2.0, `APP_ID` is no longer configured as an environment variable but is passed as a parameter each time the MCP tool is called. This allows a single MCP server instance to support multiple JianDaoYun applications, enabling users to dynamically specify the application to operate on.
## MCP Tool Description
### 1. get_form_fields
Retrieve the field definition information of a form.
**Parameters:**
- `appId` (string): JianDaoYun Application ID
- `appKey` (string): JianDaoYun API Key
- `formId` (string): Form ID (supports Application ID or full Form ID)
**Returns:** A list of form fields, including field keys, names, types, etc.
### 2. submit_form_data
Submit data to a form, supporting automatic field type matching.
**Parameters:**
- `appId` (string): JianDaoYun Application ID
- `appKey` (string): JianDaoYun API Key
- `formId` (string): Form ID (supports Application ID or full Form ID)
- `data` (object|array): Data to be submitted (single object or array)
- `autoMatch` (boolean): Whether to automatically match field types (default: true)
- `transactionId` (string): Optional transaction ID for idempotent submission
**Returns:** Submission result
### 3. get_form_data
Retrieve specific data records from a form.
**Parameters:**
- `appId` (string): JianDaoYun Application ID
- `appKey` (string): JianDaoYun API Key
- `formId` (string): Form ID (supports Application ID or full Form ID)
- `dataId` (string): Data record ID
**Returns:** Details of the data record
### 4. query_form_data
Query multiple data records, supporting filtering and pagination.
**Parameters:**
- `appId` (string): JianDaoYun Application ID
- `appKey` (string): JianDaoYun API Key
- `formId` (string): Form ID (supports Application ID or full Form ID)
- `dataId` (string): Optional, ID of the last data record for pagination
- `fields` (array): Optional, list of fields to return (widget IDs)
- `filter` (object): Optional, data filtering conditions
- `limit` (number): Optional, number of records to return (1-100, default 10)
**Filter Example:**
```json
{
"rel": "and",
"cond": [
{
"field": "_widget_1508400000001",
"type": "text",
"method": "eq",
"value": "Zhang San"
},
{
"field": "_widget_1508400000002",
"type": "number",
"method": "range",
"value": [20, 30]
}
]
}
```
### 5. update_form_data
Update existing data records.
**Parameters:**
- `appId` (string): JianDaoYun Application ID
- `appKey` (string): JianDaoYun API Key
- `formId` (string): Form ID (supports Application ID or full Form ID)
- `dataId` (string): ID of the data to be updated
- `data` (object): Content of the data to be updated
- `transactionId` (string): Optional transaction ID
- `isStartTrigger` (boolean): Whether to trigger automation processes
**Returns:** Update result
### 6. delete_form_data
Delete one or more data records.
**Parameters:**
- `appId` (string): JianDaoYun Application ID
- `appKey` (string): JianDaoYun API Key
- `formId` (string): Form ID (supports Application ID or full Form ID)
- `dataIds` (string|array): IDs of the data to be deleted (single string or array)
- `isStartTrigger` (boolean): Whether to trigger automation processes
**Returns:** Deletion result
### 7. get_upload_token
Obtain file upload credentials.
**Parameters:**
- `appId` (string): JianDaoYun Application ID
- `appKey` (string): JianDaoYun API Key
- `formId` (string): Form ID (supports Application ID or full Form ID)
- `transactionId` (string): Transaction ID, the uploaded file will be bound to this transaction
**Returns:** File upload credentials and upload addresses (up to 100)
### 8. list_apps_and_forms
List all accessible applications or get the list of forms under a specified application.
**Parameters:**
- `appKey` (string): JianDaoYun API Key
- `appId` (string): Optional, if provided, returns the list of forms under that application
**Returns:** List of applications or forms
## Supported Field Types
Supported field types and automatic conversion rules:
- **Text** (text): Automatically converted to string
- **Number** (number): Automatically parsed as a number
- **Date/DateTime** (date/datetime): Supports various date formats, automatically converted to ISO format
- **Single Choice/Multiple Choice** (select/multi_select): Automatically handles array format
- **Checkbox** (checkbox): Automatically converted to boolean
- **User/Department** (user/dept): Supports single or multiple IDs
- **File/Image** (file/image): Supports URL or file object format
- **Location** (location): Supports object or string format
- **Address** (address): Supports detailed address format for province, city, and district
- **Phone Number** (phone): Supports object format {phone: "15812345678"}
- **Subform** (subform): Recursively processes subform data
- **Serial Number** (sn): Read-only field, automatically generated
## Usage Examples
### Configuration in Claude Desktop
#### Method 1: Using npx (Recommended)
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"jiandaoyun": {
"command": "npx",
"args": ["jiandaoyun-mcp-server"],
"env": {
"JIANDAOYUN_APP_KEY": "your_app_key"
}
}
}
}
```
#### Method 2: Using Local Installation
```bash
# Global installation
npm install -g jiandaoyun-mcp-server
# Or local installation
npm install jiandaoyun-mcp-server
```
Configuration file:
```json
{
"mcpServers": {
"jiandaoyun": {
"command": "jiandaoyun-mcp",
"env": {
"JIANDAOYUN_APP_KEY": "your_app_key"
}
}
}
}
```
#### Method 3: Running Directly with Node.js
```json
{
"mcpServers": {
"jiandaoyun": {
"command": "node",
"args": ["/path/to/jiandaoyun-mcp-server/build/index.js"],
"env": {
"JIANDAOYUN_APP_KEY": "your_app_key"
}
}
}
}
```
**Configuration Notes:**
- Replace `your_app_key` with your JianDaoYun API Key.
- Starting from v2.0, `APP_ID` is passed as a tool parameter, no need to configure in environment variables.
- It is recommended to use the npx method to avoid manual installation and maintenance of local files.
### Retrieve Form Fields
```javascript
// Retrieve form field definitions
const fields = await get_form_fields({
appId: "your_app_id",
appKey: "your_app_key",
formId: "your_form_id"
});
```
### Submit Data
```javascript
// Submit a single data record
const result = await submit_form_data({
appId: "your_app_id",
appKey: "your_app_key",
formId: "your_form_id",
data: {
"Name": "Zhang San",
"Age": 25,
"Email": "zhangsan@example.com"
}
});
// Batch submit data
const batchResult = await submit_form_data({
appId: "your_app_id",
appKey: "your_app_key",
formId: "your_form_id",
data: [
{ "Name": "Zhang San", "Age": 25 },
{ "Name": "Li Si", "Age": 30 }
]
});
```
### Query Data
```javascript
// Query all data
const allData = await query_form_data({
appId: "your_app_id",
appKey: "your_app_key",
formId: "your_form_id"
});
// Query with conditions
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
});
```
### List Applications and Forms
```javascript
// List all applications
const apps = await list_apps_and_forms({
appKey: "your_app_key"
});
// Get the list of forms under a specific application
const forms = await list_apps_and_forms({
appKey: "your_app_key",
appId: "your_app_id"
});
```
### Data Submission Example
```javascript
// Single data submission (using field aliases)
{
"formId": "5f3e4d2c1b0a9",
"data": {
"Name": "Zhang San",
"Age": 25,
"Joining Date": "2024-01-15",
"Department": ["dept_001"],
"Skills": ["JavaScript", "Python"],
"Phone Number": { "phone": "15812345678" },
"Address": {
"province": "Jiangsu Province",
"city": "Wuxi City",
"district": "Binhu District",
"detail": "1000 Taihu Avenue"
},
"Resume": { "url": "https://example.com/resume.pdf" }
}
}
// Submitting using widget IDs (recommended)
{
"formId": "5f3e4d2c1b0a9",
"data": {
"_widget_1432728651402": "Zhang San",
"_widget_1432728651403": 25,
"_widget_1432728651407": "2024-01-15T00:00:00.000Z",
"_widget_1432728651413": {
"province": "Jiangsu Province",
"city": "Wuxi City",
"district": "Binhu District",
"detail": "1000 Taihu Avenue",
"lnglatXY": [120.31237, 31.49099]
}
}
}
// Batch data submission
{
"formId": "5f3e4d2c1b0a9",
"data": [
{ "Name": "Zhang San", "Age": 25 },
{ "Name": "Li Si", "Age": 30 }
]
}
// Data query example
{
"formId": "5f3e4d2c1b0a9",
"filter": {
"rel": "and",
"cond": [
{
"field": "_widget_1508400000001",
"type": "text",
"method": "eq",
"value": "Zhang San"
},
{
"field": "createTime",
"method": "range",
"value": ["2024-01-01", null]
}
]
},
"limit": 50
}
```
## Development
```bash
# Development mode
npm run dev
# Build
npm run build
# Start service
npm start
```
## Error Handling
The service will automatically handle the following situations:
- API authentication failure
- Network errors
- Field mismatch warnings
- Data format conversion errors
## License
MIT
