query_form_data
Retrieve form data entries from JianDaoYun with filtering, pagination, and field selection for targeted data analysis.
Instructions
Query multiple form data entries with filtering support
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| appId | Yes | The JianDaoYun application ID | |
| appKey | No | The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided) | |
| formId | Yes | The form ID (can be form ID or app ID) | |
| dataId | No | Last data ID for pagination | |
| fields | No | Fields to return (widget IDs) | |
| filter | No | Data filter conditions | |
| limit | No | Number of records to return (1-100, default: 10) |
Implementation Reference
- src/client.ts:229-262 (handler)Core handler implementation in JianDaoYunClient class. Performs the API POST request to '/v5/app/entry/data/list' with parameters for formId, pagination (dataId, limit), field selection, and filtering. Handles errors and returns the data.
async queryFormData(options: QueryDataOptions): Promise<any> { try { const requestData: any = { app_id: this.config.appId, entry_id: options.formId, limit: options.limit || 10 }; if (options.dataId) { requestData.data_id = options.dataId; } if (options.fields && options.fields.length > 0) { requestData.fields = options.fields; } if (options.filter) { requestData.filter = options.filter; } const response = await this.axios.post<ApiResponse>('/v5/app/entry/data/list', requestData); if (response.data.code !== 0) { throw new Error(`Failed to query form data: ${response.data.msg}`); } return response.data.data; } catch (error) { if (axios.isAxiosError(error)) { throw new Error(`API request failed: ${error.response?.data?.msg || error.message}`); } throw error; } } - src/index.ts:755-805 (handler)MCP server tool handler for 'query_form_data'. Validates parameters, resolves formId intelligently (appId or formId), instantiates JianDaoYunClient, calls its queryFormData method, formats response, and handles errors.
case 'query_form_data': { const { formId, dataId, fields, filter, limit } = args as { formId: string; dataId?: string; fields?: string[]; filter?: any; limit?: number; }; const { appId, appKey, baseUrl } = getDefaultParams(args); // 验证必需参数 if (!appKey) { throw new Error('appKey is required. Please set JIANDAOYUN_APP_KEY in MCP server configuration.'); } if (!appId) { throw new Error('appId is required. Please provide it as parameter.'); } try { // 创建客户端实例 const jdyClient = new JianDaoYunClient({ appId, appKey, baseUrl }); const resolved = await resolveFormId(formId, appKey); const result = await jdyClient.queryFormData({ formId: resolved.formId, dataId, fields, filter, limit, }); return { content: [ { type: 'text', text: JSON.stringify({ ...result, formUsed: resolved.formId, appId: resolved.appId || appId }, null, 2), }, ], }; } catch (error) { throw createEnhancedError(error, '查询表单数据'); } } - src/index.ts:330-392 (schema)Tool schema definition returned by listTools, including detailed inputSchema with properties for appId, appKey, formId, pagination, fields, filter conditions, and limit validation.
{ name: 'query_form_data', description: 'Query multiple form data entries with filtering support', inputSchema: { type: 'object', properties: { appId: { type: 'string', description: 'The JianDaoYun application ID', }, appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided)', }, formId: { type: 'string', description: 'The form ID (can be form ID or app ID)', }, dataId: { type: 'string', description: 'Last data ID for pagination', }, fields: { type: 'array', items: { type: 'string' }, description: 'Fields to return (widget IDs)', }, filter: { type: 'object', description: 'Data filter conditions', properties: { rel: { type: 'string', enum: ['and', 'or'], description: 'Relation between conditions', }, cond: { type: 'array', description: 'Filter conditions', items: { type: 'object', properties: { field: { type: 'string' }, type: { type: 'string' }, method: { type: 'string' }, value: {}, }, required: ['field', 'method'], }, }, }, required: ['rel', 'cond'], }, limit: { type: 'number', description: 'Number of records to return (1-100, default: 10)', minimum: 1, maximum: 100, }, }, required: ['appId', 'formId'], }, }, - src/types.ts:30-48 (schema)TypeScript interface definitions for QueryDataOptions, DataFilter, and FilterCondition used in the queryFormData method signature and filter handling.
export interface QueryDataOptions { formId: string; dataId?: string; fields?: string[]; filter?: DataFilter; limit?: number; } export interface DataFilter { rel: 'and' | 'or'; cond: FilterCondition[]; } export interface FilterCondition { field: string; type?: string; method: 'eq' | 'ne' | 'in' | 'nin' | 'range' | 'empty' | 'not_empty' | 'like' | 'verified' | 'unverified'; value?: any; } - src/index.ts:244-507 (registration)Registration of the query_form_data tool in the MCP server's listTools handler, including it in the tools array.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'get_form_fields', description: 'Get field definitions for a JianDaoYun form', inputSchema: { type: 'object', properties: { appId: { type: 'string', description: 'The JianDaoYun application ID', }, appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (can be provided via JIANDAOYUN_APP_KEY environment variable)', }, formId: { type: 'string', description: 'The form ID to query fields for (can be form ID or app ID)', }, }, required: ['appId', 'formId'], }, }, { name: 'submit_form_data', description: 'Submit data to a JianDaoYun form with automatic field type matching', inputSchema: { type: 'object', properties: { appId: { type: 'string', description: 'The JianDaoYun application ID', }, appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided)', }, formId: { type: 'string', description: 'The form ID to submit data to (can be form ID or app ID)', }, data: { type: ['object', 'array'], description: 'The data to submit (single object or array for batch)', }, autoMatch: { type: 'boolean', description: 'Whether to automatically match field types (default: true)', default: true, }, transactionId: { type: 'string', description: 'Optional transaction ID for idempotent submissions', }, }, required: ['appId', 'formId', 'data'], }, }, { name: 'get_form_data', description: 'Get a specific data entry from a JianDaoYun form', inputSchema: { type: 'object', properties: { appId: { type: 'string', description: 'The JianDaoYun application ID', }, appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided)', }, formId: { type: 'string', description: 'The form ID (can be form ID or app ID)', }, dataId: { type: 'string', description: 'The data entry ID', }, }, required: ['appId', 'formId', 'dataId'], }, }, { name: 'query_form_data', description: 'Query multiple form data entries with filtering support', inputSchema: { type: 'object', properties: { appId: { type: 'string', description: 'The JianDaoYun application ID', }, appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided)', }, formId: { type: 'string', description: 'The form ID (can be form ID or app ID)', }, dataId: { type: 'string', description: 'Last data ID for pagination', }, fields: { type: 'array', items: { type: 'string' }, description: 'Fields to return (widget IDs)', }, filter: { type: 'object', description: 'Data filter conditions', properties: { rel: { type: 'string', enum: ['and', 'or'], description: 'Relation between conditions', }, cond: { type: 'array', description: 'Filter conditions', items: { type: 'object', properties: { field: { type: 'string' }, type: { type: 'string' }, method: { type: 'string' }, value: {}, }, required: ['field', 'method'], }, }, }, required: ['rel', 'cond'], }, limit: { type: 'number', description: 'Number of records to return (1-100, default: 10)', minimum: 1, maximum: 100, }, }, required: ['appId', 'formId'], }, }, { name: 'update_form_data', description: 'Update an existing form data entry', inputSchema: { type: 'object', properties: { appId: { type: 'string', description: 'The JianDaoYun application ID', }, appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided)', }, formId: { type: 'string', description: 'The form ID (can be form ID or app ID)', }, dataId: { type: 'string', description: 'The data entry ID to update', }, data: { type: 'object', description: 'The data to update', }, transactionId: { type: 'string', description: 'Optional transaction ID', }, isStartTrigger: { type: 'boolean', description: 'Whether to trigger automation', }, }, required: ['appId', 'formId', 'dataId', 'data'], }, }, { name: 'delete_form_data', description: 'Delete one or more form data entries', inputSchema: { type: 'object', properties: { appId: { type: 'string', description: 'The JianDaoYun application ID', }, appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided)', }, formId: { type: 'string', description: 'The form ID (can be form ID or app ID)', }, dataIds: { type: ['string', 'array'], description: 'Data ID(s) to delete', items: { type: 'string' }, }, isStartTrigger: { type: 'boolean', description: 'Whether to trigger automation', }, }, required: ['appId', 'formId', 'dataIds'], }, }, { name: 'get_upload_token', description: 'Get file upload tokens for file/image fields', inputSchema: { type: 'object', properties: { appId: { type: 'string', description: 'The JianDaoYun application ID', }, appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided)', }, formId: { type: 'string', description: 'The form ID (can be form ID or app ID)', }, transactionId: { type: 'string', description: 'Transaction ID to bind uploads to', }, }, required: ['appId', 'formId', 'transactionId'], }, }, { name: 'list_apps_and_forms', description: 'List all available applications and their forms that the current API key can access', inputSchema: { type: 'object', properties: { appKey: { type: 'string', description: 'The JianDaoYun application key (API key) (optional, will use JIANDAOYUN_APP_KEY from environment if not provided)', }, appId: { type: 'string', description: 'Optional: specific app ID to get forms for. If not provided, lists all apps.', }, }, required: [], }, }, ], };