JianDaoYun MCP Server

Instructions

Implementation Reference

• src/client.ts:32-53 (handler)

  Core handler function that executes the API call to retrieve form fields from JianDaoYun and transforms the response into FormField array.

  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/client.ts:55-72 (helper)

  Helper function to recursively transform API widget data into standardized FormField objects.

  private transformFields(widgets: any[]): FormField[] {
    return widgets.map(widget => {
      const field: FormField = {
        key: widget.name,
        name: widget.label,
        type: this.mapFieldType(widget.type),
        required: widget.required || false
      };
  
      if (widget.type === 'subform' && widget.items) {
        field.subForm = {
          fields: this.transformFields(widget.items)
        };
      }
  
      return field;
    });
  }

• src/client.ts:74-98 (helper)

  Helper function to map JianDaoYun API field types to standardized field types.

  private mapFieldType(apiType: string): string {
    const typeMap: { [key: string]: string } = {
      'text': 'text',
      'textarea': 'text',
      'number': 'number',
      'date': 'date',
      'datetime': 'datetime',
      'sn': 'serial_no',
      'address': 'address',
      'location': 'location',
      'image': 'image',
      'file': 'file',
      'single_select': 'select',
      'multiple_select': 'multi_select',
      'checkbox': 'checkbox',
      'radio': 'radio',
      'user': 'user',
      'dept': 'dept',
      'subform': 'subform',
      'formula': 'formula',
      'phone': 'phone'
    };
  
    return typeMap[apiType] || 'text';
  }

• src/index.ts:248-268 (registration)

  MCP tool registration defining the 'get_form_fields' tool 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:526-567 (handler)

  MCP server request handler for executing the get_form_fields tool, including parameter validation, client instantiation, form ID resolution, and response formatting.

  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/types.ts:7-15 (schema)

  TypeScript interface defining the structure of form fields returned by the tool.

  export interface FormField {
    key: string;
    name: string;
    type: string;
    required?: boolean;
    subForm?: {
      fields: FormField[];
    };
  }