mcp-yapi-server

Instructions

Implementation Reference

• src/index.ts:391-451 (handler)

  The main handler function for the 'yapi_get_interface_by_url' tool. It parses the provided YApi URL, temporarily sets the YApi base URL from the parsed URL, fetches the interface details, formats them, adds source URL info, and returns the JSON-formatted result. Handles errors appropriately.

  async (args: { url: string; token?: string }) => {
    try {
      // 解析URL
      const parsed = YApiUrlParser.parseInterfaceUrl(args.url);
      
      if (!parsed) {
        return {
          content: [
            {
              type: 'text',
              text: '错误: 无法解析YApi URL。请确保URL格式正确,例如: https://yapi.example.com/project/100/interface/api/12345',
            },
          ],
          isError: true,
        };
      }
  
      // 临时切换到URL中的baseUrl
      const originalBaseUrl = yapiClient['baseUrl'];
      yapiClient['baseUrl'] = parsed.baseUrl;
      yapiClient['client'].defaults.baseURL = parsed.baseUrl;
  
      try {
        const interfaceData = await yapiClient.getInterfaceDetails(
          parsed.interfaceId,
          args.token
        );
        const formatted = InterfaceFormatter.formatInterfaceDetails(interfaceData);
  
        // 添加URL信息
        const result = {
          ...formatted,
          source_url: args.url,
          yapi_server: parsed.baseUrl,
        };
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } finally {
        // 恢复原始baseUrl
        yapiClient['baseUrl'] = originalBaseUrl;
        yapiClient['client'].defaults.baseURL = originalBaseUrl;
      }
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `错误: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:385-390 (schema)

  Input schema definition using Zod for the tool, specifying 'url' as required string and 'token' as optional string.

    description: '通过YApi接口URL获取详细信息。支持直接粘贴YApi链接,如: https://yapi.example.com/project/100/interface/api/12345',
          inputSchema: {
      url: z.string().describe('YApi接口完整URL,例如: https://yapi.example.com/project/100/interface/api/12345'),
      token: z.string().optional().describe('访问令牌(可选,用于访问私有项目)'),
    },
  },

• src/index.ts:382-452 (registration)

  Registration of the 'yapi_get_interface_by_url' tool on the MCP server using server.registerTool, including name, schema, and inline handler.

  server.registerTool(
    'yapi_get_interface_by_url',
    {
      description: '通过YApi接口URL获取详细信息。支持直接粘贴YApi链接,如: https://yapi.example.com/project/100/interface/api/12345',
            inputSchema: {
        url: z.string().describe('YApi接口完整URL,例如: https://yapi.example.com/project/100/interface/api/12345'),
        token: z.string().optional().describe('访问令牌(可选,用于访问私有项目)'),
      },
    },
    async (args: { url: string; token?: string }) => {
      try {
        // 解析URL
        const parsed = YApiUrlParser.parseInterfaceUrl(args.url);
        
        if (!parsed) {
          return {
            content: [
              {
                type: 'text',
                text: '错误: 无法解析YApi URL。请确保URL格式正确,例如: https://yapi.example.com/project/100/interface/api/12345',
              },
            ],
            isError: true,
          };
        }
  
        // 临时切换到URL中的baseUrl
        const originalBaseUrl = yapiClient['baseUrl'];
        yapiClient['baseUrl'] = parsed.baseUrl;
        yapiClient['client'].defaults.baseURL = parsed.baseUrl;
  
        try {
          const interfaceData = await yapiClient.getInterfaceDetails(
            parsed.interfaceId,
            args.token
          );
          const formatted = InterfaceFormatter.formatInterfaceDetails(interfaceData);
  
          // 添加URL信息
          const result = {
            ...formatted,
            source_url: args.url,
            yapi_server: parsed.baseUrl,
          };
  
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(result, null, 2),
              },
            ],
          };
        } finally {
          // 恢复原始baseUrl
          yapiClient['baseUrl'] = originalBaseUrl;
          yapiClient['client'].defaults.baseURL = originalBaseUrl;
        }
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `错误: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/index.ts:326-346 (helper)

  YApiUrlParser.parseInterfaceUrl static method: Parses YApi interface URL to extract baseUrl, projectId, and interfaceId. Used in the handler to parse the input URL.

  static parseInterfaceUrl(url: string): { baseUrl: string; projectId: string; interfaceId: string } | null {
    try {
      const urlObj = new URL(url);
      const baseUrl = `${urlObj.protocol}//${urlObj.host}`;
      
      // 匹配路径: /project/{projectId}/interface/api/{interfaceId}
      const match = urlObj.pathname.match(/\/project\/(\d+)\/interface\/api\/(\d+)/);
      
      if (match) {
        return {
          baseUrl,
          projectId: match[1],
          interfaceId: match[2],
        };
      }
      
      return null;
    } catch (error) {
      return null;
    }
  }

• src/index.ts:181-204 (helper)

  InterfaceFormatter.formatInterfaceDetails static method: Formats raw YApi interface data into a structured object with request/response details. Called in the handler after fetching data.

  static formatInterfaceDetails(interfaceData: any): any {
    const requestParams = this.extractRequestParams(interfaceData);
    const responseInfo = this.extractResponseInfo(interfaceData);
  
    return {
      id: interfaceData._id,
      title: interfaceData.title,
      method: interfaceData.method,
      path: interfaceData.path,
      description: interfaceData.desc || '',
      status: interfaceData.status || 'undone',
      request: {
        params: requestParams,
        headers: this.extractHeaders(interfaceData),
        body: this.extractRequestBody(interfaceData),
      },
      response: responseInfo,
      markdown: interfaceData.markdown || '',
      project_id: interfaceData.project_id,
      catid: interfaceData.catid,
      uid: interfaceData.uid,
      add_time: interfaceData.add_time,
      up_time: interfaceData.up_time,
    };