ApiPost MCP

Instructions

Implementation Reference

• src/index.ts:924-944 (registration)

  Registration of the 'apipost_update' tool in the MCP server, including name, description, and detailed inputSchema for parameters like target_id, name, method, url, etc.
  name: 'apipost_update', description: '修改API接口文档。规则同创建：responses 只用 fields（必填），不要传 data；headers/query/body/cookies 统一用字段列表，嵌套用 .，数组用 []，example 填真实值；所有字段含父级必须写 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: { target_id: { type: 'string', description: '要修改的接口ID' }, name: { type: 'string', description: '新的接口名称（可选）' }, method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], description: '新的HTTP方法（可选）' }, url: { type: 'string', description: '新的接口URL（可选）' }, description: { type: 'string', description: '接口详细描述（可选）。提供空字符串""可清空描述' }, headers: { type: 'string', description: 'Headers参数JSON数组字符串（可选）。提供"[]"可删除所有headers。格式：[{"key":"Content-Type","desc":"内容类型","type":"string","required":true,"example":"application/json"}]' }, query: { type: 'string', description: 'Query参数JSON数组字符串（可选）。提供"[]"可删除所有query参数。格式：[{"key":"page","desc":"页码","type":"integer","required":false,"example":"1"}]' }, body: { type: 'string', description: 'Body参数JSON数组字符串（可选）。提供"[]"可删除所有body参数。格式：[{"key":"name","desc":"用户名","type":"string","required":true,"example":"张三"}]' }, cookies: { type: 'string', description: 'Cookies参数JSON数组字符串（可选）。提供"[]"可删除所有cookies。格式：[{"key":"session_id","desc":"会话ID","type":"string","required":false,"example":"abc123"}]' }, auth: { type: 'string', description: '认证配置JSON字符串（可选）。提供"{}"可删除认证配置。格式：{"type":"bearer","bearer":{"key":"your_token"}}' }, responses: { type: 'string', description: '响应示例JSON数组字符串（可选）。提供"[]"可删除所有响应示例。格式：[{"name":"成功响应","status":200,"data":{"code":0},"fields":[{"key":"code","desc":"状态码","type":"integer","example":"0"}]}]' } }, required: ['target_id'], additionalProperties: false } },
• src/index.ts:1493-1608 (handler)

  The core handler for 'apipost_update' tool. Checks permissions, retrieves existing API details via '/open/apis/details', merges provided arguments with original config using helpers like buildApiConfig and normalizeResponses, constructs update payload, performs API update via '/open/apis/update', and returns formatted success response with modification summary.
  case 'apipost_update': if (!checkSecurityPermission('write')) { throw new Error(`🔒 安全模式 "${APIPOST_SECURITY_MODE}" 不允许修改操作。需要 "limited" 或 "full" 模式。`); } const targetId = args.target_id; const newName = args.name; const newMethod = args.method; const newUrl = args.url ? applyUrlPrefix(args.url) : undefined; if (!targetId) { throw new Error('请提供要修改的API接口ID'); } // 获取原接口信息 const getResult = await apiClient.post('/open/apis/details', { project_id: currentWorkspace.projectId, target_ids: [targetId] }); if (getResult.data.code !== 0) { throw new Error(`获取接口详情失败: ${getResult.data.msg}`); } const originalApi = getResult.data.data.list[0]; // 获取数组中的第一个接口 if (!originalApi) { throw new Error(`未找到接口详情 (ID: ${targetId})。可能原因：1) 接口不存在 2) 无权限访问 3) 接口已被删除。请检查接口ID是否正确。`); } // 构建增量更新配置对象 const { config: newConfig, providedFields } = buildApiConfig(args); const mergedDescription = providedFields.has('description') ? newConfig.description : (originalApi.description || ''); const mergedRequest = { auth: providedFields.has('auth') ? (newConfig.auth || { type: 'inherit' }) : (originalApi.request?.auth || { type: 'inherit' }), pre_tasks: originalApi.request?.pre_tasks || [], post_tasks: originalApi.request?.post_tasks || [], header: { parameter: providedFields.has('headers') ? convertParams(newConfig.headers || []) : (originalApi.request?.header?.parameter || []) }, query: { query_add_equal: originalApi.request?.query?.query_add_equal ?? 1, parameter: providedFields.has('query') ? convertParams(newConfig.query || []) : (originalApi.request?.query?.parameter || []) }, body: providedFields.has('body') ? buildBodySection(newConfig.body || []) : (originalApi.request?.body || buildBodySection([])), cookie: { cookie_encode: originalApi.request?.cookie?.cookie_encode ?? 1, parameter: providedFields.has('cookies') ? convertParams(newConfig.cookies || []) : (originalApi.request?.cookie?.parameter || []) }, restful: originalApi.request?.restful || { parameter: [] } }; const responseSection = providedFields.has('responses') ? normalizeResponses(newConfig.responses, { fallbackExamples: [], useDefaultWhenMissing: false, keepEmpty: true, isCheckResult: originalApi.response?.is_check_result ?? 1 }) : { example: originalApi.response?.example || [], is_check_result: originalApi.response?.is_check_result ?? 1 }; const updateTemplate = { project_id: currentWorkspace.projectId, target_id: targetId, parent_id: originalApi.parent_id || '0', target_type: originalApi.target_type || 'api', name: newName || originalApi.name, method: newMethod || originalApi.method, url: newUrl || originalApi.url, protocol: originalApi.protocol || 'http/1.1', description: mergedDescription, version: (originalApi.version || 0) + 1, mark_id: originalApi.mark_id || '1', is_force: originalApi.is_force ?? -1, sort: originalApi.sort ?? 0, status: originalApi.status ?? 1, is_deleted: originalApi.is_deleted ?? -1, is_conflicted: originalApi.is_conflicted ?? -1, request: mergedRequest, response: responseSection, attribute_info: originalApi.attribute_info || {}, tags: originalApi.tags || [] }; // 执行修改 const updateResult = await apiClient.post('/open/apis/update', updateTemplate); if (updateResult.data.code !== 0) { throw new Error(`修改失败: ${updateResult.data.msg}`); } // 统计修改的字段 const changedFields = []; if (newName && newName !== originalApi.name) changedFields.push('名称'); if (newMethod && newMethod !== originalApi.method) changedFields.push('方法'); if (newUrl && newUrl !== originalApi.url) changedFields.push('URL'); // 检查是否有配置相关的更新 if (providedFields.size > 0) changedFields.push('配置'); const changedFieldsText = changedFields.length > 0 ? `\n修改字段: ${changedFields.join(', ')}` : '\n仅更新版本'; let updateText = `接口修改成功!\n接口ID: ${targetId}\n`; if (newName) updateText += `新名称: ${newName}\n`; if (newMethod) updateText += `新方法: ${newMethod}\n`; if (newUrl) updateText += `新URL: ${newUrl}\n`; updateText += `版本: v${updateTemplate.version}\n修改字段: ${changedFields.join(', ') || '仅更新版本'}`; return { content: [{ type: 'text', text: updateText }] };
• src/index.ts:688-725 (helper)

  Helper function buildApiConfig used by apipost_update to parse and validate tool input parameters into structured config, ensuring all fields have descriptions.
  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:282-352 (helper)

  Helper function normalizeResponses crucial for processing responses in apipost_update, converting user-provided fields to ApiPost-compatible example structures.
  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 }; }