ApiPost MCP

Instructions

Implementation Reference

• src/index.ts:882-902 (registration)

  Registration of the 'apipost_smart_create' tool in the tools list, including name, description, and inputSchema.
  { name: 'apipost_smart_create', description: 'API接口文档生成器（字段列表驱动）。规则：responses 只传 fields，不传 data；headers/query/body/cookies 统一用字段列表，嵌套用 .，数组用 []；example 填真实值（不要 JSON 字符串）；所有字段含父级都必须写 desc，父级需显式声明。例如：{"key":"data","desc":"返回体","type":"object"},{"key":"data.user","desc":"用户","type":"object"},{"key":"data.user.id","desc":"用户ID","type":"integer","example":1}', inputSchema: { type: 'object', properties: { method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], description: 'HTTP方法' }, url: { type: 'string', description: '接口URL路径' }, name: { type: 'string', description: '接口名称' }, parent_id: { type: 'string', description: '父目录ID，使用"0"表示根目录，默认为"0"' }, description: { type: 'string', description: '接口详细描述（可选）' }, headers: { type: 'string', description: 'Headers字段列表字符串，格式：[{"key":"X-Request-ID","type":"string","required":false,"example":"req-1","desc":"说明"}]' }, query: { type: 'string', description: 'Query字段列表字符串，格式同上。嵌套用 .，数组用 []（如 meta.flags.debug 或 items[].id）。' }, body: { type: 'string', description: 'Body字段列表字符串，仅用字段列表生成 raw/参数描述，example 用真实值，不要放 JSON 字符串。' }, cookies: { type: 'string', description: 'Cookies字段列表字符串，格式同上。' }, auth: { type: 'string', description: '认证配置JSON字符串（可选）。格式：{"type":"bearer","bearer":{"key":"your_token"}}' }, responses: { type: 'string', description: '响应字段列表字符串（必填 fields），格式：[{"name":"成功","status":200,"fields":[{"key":"code","type":"integer","example":0,"desc":"状态码"},{"key":"data.items[].id","type":"string","example":"1"}]}]' } }, required: ['method', 'url', 'name'], additionalProperties: false }
• src/index.ts:1395-1419 (handler)

  Handler implementation for 'apipost_smart_create'. Performs security check, builds API config and template, sends create request to ApiPost API, and returns success message with stats.
  case 'apipost_smart_create': if (!checkSecurityPermission('write')) { throw new Error(`🔒 安全模式 "${APIPOST_SECURITY_MODE}" 不允许创建操作。需要 "limited" 或 "full" 模式。`); } // 构建配置对象 const { config } = buildApiConfig(args); const template = generateApiTemplate(args.method, args.url, args.name, config); template.project_id = currentWorkspace.projectId; // 设置父目录ID template.parent_id = args.parent_id || '0'; const headerCount = config.headers?.length || 0; const queryCount = config.query?.length || 0; const bodyCount = config.body?.length || 0; const responseCount = config.responses?.length || 0; const createResult = await apiClient.post('/open/apis/create', template); if (createResult.data.code !== 0) { throw new Error(`创建失败: ${createResult.data.msg}`); } return { content: [{ type: 'text', text: `API创建成功!\n名称: ${args.name}\n方法: ${args.method}\nURL: ${args.url}\nID: ${createResult.data.data.target_id}\n\n字段统计:\n• Headers: ${headerCount}个\n• Query参数: ${queryCount}个\n• Body参数: ${bodyCount}个\n• 响应示例: ${responseCount}个` }] };
• src/index.ts:688-725 (helper)

  Helper function buildApiConfig: Parses input arguments into config object for headers, query, body, cookies, auth, responses, tracking which fields were provided.
  function buildApiConfig(args) { const config = {}; const providedFields = new Set(); if (args.description !== undefined) { config.description = args.description; providedFields.add('description'); } if (args.headers !== undefined) { config.headers = parseConfigParam(args.headers); ensureFieldsHaveDesc(config.headers, 'headers'); providedFields.add('headers'); } if (args.query !== undefined) { config.query = parseConfigParam(args.query); ensureFieldsHaveDesc(config.query, 'query'); providedFields.add('query'); } if (args.body !== undefined) { config.body = parseConfigParam(args.body); ensureFieldsHaveDesc(config.body, 'body'); providedFields.add('body'); } if (args.cookies !== undefined) { config.cookies = parseConfigParam(args.cookies); ensureFieldsHaveDesc(config.cookies, 'cookies'); providedFields.add('cookies'); } if (args.auth !== undefined) { config.auth = parseApiConfig(args.auth); providedFields.add('auth'); } if (args.responses !== undefined) { config.responses = parseConfigParam(args.responses); ensureResponsesFieldsHaveDesc(config.responses); providedFields.add('responses'); } return { config, providedFields }; }
• src/index.ts:727-763 (helper)

  Helper function generateApiTemplate: Constructs the full ApiPost API object template from method, url, name, and config, including request/response structures.
  function generateApiTemplate(method, url, name, config = {}) { return { target_id: generateId(), target_type: 'api', parent_id: '0', name, method, url: applyUrlPrefix(url), protocol: 'http/1.1', description: config.description || `${name} - ${method} ${url}`, version: 3, mark_id: 1, is_force: -1, request: { auth: config.auth || { type: 'inherit' }, pre_tasks: config.pre_tasks || [], post_tasks: config.post_tasks || [], header: { parameter: convertParams(config.headers || []) }, query: { query_add_equal: 1, parameter: convertParams(config.query || []) }, body: buildBodySection(config.body || []), cookie: { cookie_encode: 1, parameter: convertParams(config.cookies || []) }, restful: { parameter: convertParams(config.restful || []) } }, response: normalizeResponses(config.responses, { useDefaultWhenMissing: true, keepEmpty: true, isCheckResult: 1 }), attribute_info: config.attribute_info || {}, tags: config.tags || [] };
• src/index.ts:282-352 (helper)

  Helper function normalizeResponses: Normalizes response configurations from input to ApiPost expected format, handling fields lists, generating examples and schemas.
  function normalizeResponses(responses, options = {}) { const { fallbackExamples = [], useDefaultWhenMissing = true, keepEmpty = true, isCheckResult = 1 } = options; const hasInput = Array.isArray(responses); const inputLength = hasInput ? responses.length : 0; // 用户显式提供了空数组并且允许保留空响应 if (hasInput && inputLength === 0) { return { example: keepEmpty ? [] : fallbackExamples, is_check_result: isCheckResult }; } // 未提供响应，使用回退或默认 if (!hasInput) { if (fallbackExamples.length > 0) { return { example: fallbackExamples, is_check_result: isCheckResult }; } if (!useDefaultWhenMissing) { return { example: [], is_check_result: isCheckResult }; } const defaultData = generateResponseData(undefined); return { example: [{ example_id: '1', raw: JSON.stringify(defaultData, null, 4), raw_parameter: [], headers: [], expect: { code: '200', content_type: 'application/json', is_default: 1, mock: JSON.stringify(defaultData), name: '成功响应', schema: { type: 'object', properties: {} }, verify_type: 'schema', sleep: 0 } }], is_check_result: isCheckResult }; } // 已经是 ApiPost 的响应结构，直接透传 if (responses.some(isApiPostResponseExample)) { return { example: responses, is_check_result: isCheckResult }; } // 简化格式 -> ApiPost 兼容格式 const converted = responses.map((resp, index) => ({ example_id: String(index + 1), raw: (() => { const fields = Array.isArray(resp.fields) ? resp.fields : []; if (fields.length === 0) { throw new Error('responses.fields 必填且不能为空，data 字段已禁用，请提供字段列表'); } const expandedFields = expandFieldListWithParents(fields); const descMap = buildDescMap(expandedFields); const rawData = buildJsonFromFieldList(expandedFields); return APIPOST_INLINE_COMMENTS && expandedFields.length > 0 ? stringifyWithComments(rawData, descMap) : JSON.stringify(rawData, null, 4); })(), raw_parameter: convertParams(expandFieldListWithParents(resp.fields || [])), headers: [], expect: { code: String(resp.status ?? 200), content_type: 'application/json', is_default: index === 0 ? 1 : -1, mock: JSON.stringify(buildJsonFromFieldList(expandFieldListWithParents(resp.fields || []))), name: resp.name || (index === 0 ? '成功响应' : `响应${index + 1}`), schema: resp.schema || { type: 'object', properties: {} }, verify_type: 'schema', sleep: 0 } })); return { example: converted, is_check_result: isCheckResult }; }