get_form_fields
Retrieve field definitions for a JianDaoYun form using application and form IDs. Simplify form data management and ensure accurate field type matching across applications.
Instructions
Get field definitions for a JianDaoYun form
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| appId | Yes | The JianDaoYun application ID | |
| appKey | No | The JianDaoYun application key (API key) (can be provided via JIANDAOYUN_APP_KEY environment variable) | |
| formId | Yes | The form ID to query fields for (can be form ID or app ID) |
Implementation Reference
- src/index.ts:526-567 (handler)Main MCP tool handler for get_form_fields: validates inputs, resolves formId, instantiates client, fetches and returns form fields.case 'get_form_fields': { const { formId } = args as { formId: string }; 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 fields = await jdyClient.getFormFields(resolved.formId); let responseText = JSON.stringify(fields, null, 2); // 如果有多个表单建议，添加提示信息 if (resolved.suggestions && resolved.suggestions.length > 1) { responseText = `// 注意: 检测到应用下有多个表单，当前使用第一个表单\n// 可用表单列表:\n${resolved.suggestions.map(s => `// - ${s}`).join('\n')}\n\n${responseText}`; } return { content: [ { type: 'text', text: responseText, }, ], }; } catch (error) { throw createEnhancedError(error, '获取表单字段'); } }
- src/index.ts:247-268 (registration)Tool registration in ListToolsResponse, defining name, description, and input schema.{ 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'], }, },
- src/index.ts:250-267 (schema)Input schema/JSON Schema for the get_form_fields tool parameters.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'], },
- src/client.ts:32-53 (helper)Core helper method in JianDaoYunClient that calls the JianDaoYun API to fetch form fields/widgets and transforms them to FormField[].async getFormFields(formId: string): Promise<FormField[]> { try { const response = await this.axios.post<ApiResponse<{ widgets: any[] }>>('/v5/app/entry/widget/list', { app_id: this.config.appId, entry_id: formId }); // 检查是否有错误响应格式 if (response.data.code !== undefined && response.data.code !== 0) { throw new Error(`Failed to get form fields: ${response.data.msg}`); } // API返回格式: {widgets: [...], sysWidgets: ...} const widgets = (response.data as any).widgets || []; return this.transformFields(Array.isArray(widgets) ? widgets : []); } catch (error) { if (axios.isAxiosError(error)) { throw new Error(`API request failed: ${error.response?.data?.msg || error.message}`); } throw error; } }
- src/index.ts:75-129 (helper)Helper function resolveFormId that smartly handles formId input: direct formId, appId (fetches forms), or passthrough.async function resolveFormId(inputId: string, appKey: string): Promise<{ formId: string; appId?: string; suggestions?: string[] }> { // 如果输入看起来像表单ID（通常24位字符），直接返回 if (inputId.length === 24 && /^[a-f0-9]{24}$/i.test(inputId)) { return { formId: inputId }; } // 尝试作为应用ID处理 const appList = await getAppList(appKey); const targetApp = appList.find(app => app.app_id === inputId); if (targetApp) { // 这是一个应用ID，需要获取其下的表单列表 try { const response = await axios.post( `${process.env.JIANDAOYUN_BASE_URL || 'https://api.jiandaoyun.com'}/api/v1/app/${inputId}/entry/list`, {}, { headers: { 'Authorization': `Bearer ${appKey}`, 'Content-Type': 'application/json' } } ); const forms = response.data || []; if (forms.length === 0) { throw new Error(`应用 "${targetApp.name}" 下没有找到可用的表单`); } // 如果只有一个表单，直接返回 if (forms.length === 1) { return { formId: forms[0].entry_id || forms[0]._id, appId: inputId }; } // 多个表单时，返回建议列表 const suggestions = forms.map((form: any) => `${form.name || '未命名表单'} (${form.entry_id || form._id})` ); return { formId: forms[0].entry_id || forms[0]._id, // 默认返回第一个 appId: inputId, suggestions }; } catch (error) { throw new Error(`无法获取应用 "${targetApp.name}" 下的表单列表: ${error instanceof Error ? error.message : '未知错误'}`); } } // 既不是标准表单ID也不是已知应用ID，直接尝试使用 return { formId: inputId }; }