APISIX-MCP

Instructions

Implementation Reference

• src/tools/common.ts:17-33 (handler)

  Inline asynchronous handler function for the 'get_resource' tool. Retrieves a specific resource by ID or lists resources with optional pagination and filters by constructing the appropriate Admin API path and delegating to makeAdminAPIRequest.

  server.tool("get_resource", "Get resource details by ID or list all resources", GetResourceSchema.shape, async (args) => {
    if (args.id) {
      return await makeAdminAPIRequest(`/${args.type}/${args.id}`);
    } else {
      let query = "";
      if (args.name) {
        query += `&name=${args.name}`;
      }
      if (args.labels) {
        query += `&labels=${args.labels}`;
      }
      if (args.uri) {
        query += `&uri=${args.uri}`;
      }
      return await makeAdminAPIRequest(`/${args.type}?page=${args.page}&page_size=${args.page_size}${query}`);
    }
  });

• src/schemas/common.ts:31-37 (schema)

  Zod schema defining the input parameters for the get_resource tool: optional 'id' for specific resource, required 'type', pagination ('page', 'page_size'), and filters ('name', 'labels', 'uri'). Composed from PaginationSchema and FilterSchema.

  export const GetResourceSchema = z
    .object({
      id: z.string().optional().describe("resource id"),
      type: ResourceTypeSchema.describe("resource type"),
    })
    .merge(PaginationSchema)
    .merge(FilterSchema);

• src/utils/adminAPI.ts:11-80 (helper)

  Supporting utility function makeAdminAPIRequest that performs HTTP requests to the APISIX Admin API with authentication, used by the get_resource handler to fetch resource data and handles both success and error responses formatting them as MCP CallToolResult.

  export async function makeAdminAPIRequest(
    path: string,
    method: string = "GET",
    data?: object
  ): Promise<CallToolResult> {
    const baseUrl = `${APISIX_SERVER_HOST}:${APISIX_ADMIN_API_PORT}${APISIX_ADMIN_API_PREFIX}`;
    const url = `${baseUrl}${path}`;
  
    try {
      const response = await axios({
        method,
        url,
        data,
        headers: {
          "X-API-KEY": APISIX_ADMIN_KEY,
          "Content-Type": "application/json",
        },
      });
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(response.data, null, 2),
          },
        ],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        console.error(`Request failed: ${method} ${url}`);
        console.error(
          `Status: ${error.response?.status}, Error: ${error.message}`
        );
  
        if (error.response?.data) {
          try {
            const stringifiedData = JSON.stringify(error.response.data);
            console.error(`Response data: ${stringifiedData}`);
          } catch {
            console.error(`Response data: [Cannot parse as JSON]`);
          }
        }
  
        return {
          isError: true,
          content: [
            {
              type: "text",
              text: JSON.stringify(
                `Status: ${error.response?.status}\nMessage: ${error.message}
  Data:\n${JSON.stringify(error.response?.data || {}, null, 2)}`,
                null,
                2
              ),
            },
          ],
        };
      } else {
        return {
          isError: true,
          content: [
            {
              type: "text",
              text: JSON.stringify(error, null, 2),
            },
          ],
        };
      }
    }
  }

• src/tools/common.ts:17-33 (registration)

  Registration of the get_resource tool on the MCP server using server.tool, specifying name, description, input schema, and inline handler function.

  server.tool("get_resource", "Get resource details by ID or list all resources", GetResourceSchema.shape, async (args) => {
    if (args.id) {
      return await makeAdminAPIRequest(`/${args.type}/${args.id}`);
    } else {
      let query = "";
      if (args.name) {
        query += `&name=${args.name}`;
      }
      if (args.labels) {
        query += `&labels=${args.labels}`;
      }
      if (args.uri) {
        query += `&uri=${args.uri}`;
      }
      return await makeAdminAPIRequest(`/${args.type}?page=${args.page}&page_size=${args.page_size}${query}`);
    }
  });