YAPI MCP Server

Instructions

Implementation Reference

• src/index.ts:697-709 (handler)

  Handler function that executes yapi_import_data tool - makes POST request to /api/open/import_data with type, json, and merge parameters, using yapiRequestWithFallback for automatic project token retry
  case "yapi_import_data": { result = await yapiRequestWithFallback( "/api/open/import_data", "POST", () => ({ type: args.type, json: args.json, merge: args.merge || "normal", }), args.project ); break; }
• src/index.ts:258-286 (schema)

  Tool schema definition for yapi_import_data - defines input parameters including url (optional), project (optional), type (required: swagger/postman/har/json), json (required), and merge (optional: normal/good/merge)
  { name: "yapi_import_data", description: "导入接口数据到 YAPI", inputSchema: { type: "object", properties: { url: urlParamDef, project: { type: ["number", "string"], description: projectParamDesc, }, type: { type: "string", description: "导入类型，如：swagger、postman、har、json", enum: ["swagger", "postman", "har", "json"], }, json: { type: "string", description: "导入的 JSON 数据", }, merge: { type: "string", description: "合并模式：normal(普通)、good(智能合并)、merge(完全覆盖)", enum: ["normal", "good", "merge"], }, }, required: ["type", "json"], }, },
• src/index.ts:176-215 (helper)

  Helper function yapiRequestWithFallback - handles automatic retry across all configured project tokens when token error occurs, supports optional project specification
  async function yapiRequestWithFallback( endpoint: string, method: "GET" | "POST", buildParams: (project: ProjectConfig) => Record<string, unknown> | undefined, specifiedProject?: unknown ): Promise<unknown> { // 如果明确指定了项目，直接使用该项目 if (specifiedProject !== undefined && specifiedProject !== null && specifiedProject !== "") { const project = getProjectConfig(specifiedProject); return yapiRequest(endpoint, method, buildParams(project), project.token); } if (projects.length === 0) { throw new Error( "未配置任何项目，请设置 YAPI_PROJECTS 环境变量，格式: projectId1:token1,projectId2:token2" ); } // 依次尝试所有项目的 token for (const project of projects) { try { const result = await yapiRequest( endpoint, method, buildParams(project), project.token ); if (!isTokenError(result)) { return result; } } catch { // 请求失败，尝试下一个项目 continue; } } throw new Error( `所有已配置项目的 token 均无法访问此接口，已尝试项目: ${projects.map((p) => p.id).join(", ")}` ); }
• src/index.ts:136-164 (helper)

  Helper function parseYapiUrl - extracts projectId, interfaceId, and catId from YAPI interface URLs, used to auto-populate parameters when url is provided
  // 解析 YAPI URL，提取项目 ID、接口 ID、分类 ID function parseYapiUrl(url: string): { projectId?: number; interfaceId?: number; catId?: number; } { const result: { projectId?: number; interfaceId?: number; catId?: number } = {}; // 匹配项目 ID: /project/{projectId} const projectMatch = url.match(/\/project\/(\d+)/); if (projectMatch) { result.projectId = Number(projectMatch[1]); } // 匹配分类 ID: /interface/api/cat_{catId} const catMatch = url.match(/\/interface\/api\/cat_(\d+)/); if (catMatch) { result.catId = Number(catMatch[1]); } else { // 匹配接口 ID: /interface/api/{interfaceId} const interfaceMatch = url.match(/\/interface\/api\/(\d+)/); if (interfaceMatch) { result.interfaceId = Number(interfaceMatch[1]); } } return result; }
• src/index.ts:87-134 (helper)

  Core helper function yapiRequest - wraps HTTP requests to YAPI API with token authentication, handles GET/POST methods and parameter serialization
  async function yapiRequest( endpoint: string, method: "GET" | "POST" = "GET", params?: Record<string, unknown>, token?: string ): Promise<unknown> { if (!YAPI_BASE_URL) { throw new Error("YAPI_BASE_URL 环境变量未配置"); } if (!token) { throw new Error("token 未提供"); } const url = new URL(endpoint, YAPI_BASE_URL); const options: RequestInit = { method, headers: { "Content-Type": "application/json", }, }; if (method === "GET") { // GET 请求时将参数添加到 URL if (params) { Object.entries(params).forEach(([key, value]) => { if (value !== undefined && value !== null) { url.searchParams.append(key, String(value)); } }); } url.searchParams.append("token", token); } else { // POST 请求时将参数放在 body 中 url.searchParams.append("token", token); if (params) { options.body = JSON.stringify(params); } } const response = await fetch(url.toString(), options); if (!response.ok) { throw new Error(`YAPI 请求失败: ${response.status} ${response.statusText}`); } return response.json(); }