ACOMO MCP Server

Instructions

Implementation Reference

• src/server.ts:55-87 (handler)

  The core handler function for the "describe_api" tool. It retrieves the operation using findOperationById, handles missing operations, constructs an example complete URL from config baseUrl and path, and returns a formatted JSON response with operation details and raw spec.

  async ({ operationId }: { operationId: string }) => {
    const op = await findOperationById(operationId);
    if (!op)
      return {
        content: [
          { type: "text", text: `Unknown operationId: ${operationId}` },
        ],
        isError: true,
      };
    const cfg = getConfig();
    const base = cfg.baseUrl.replace(/\/$/, "");
    const completeUrl = `${base}${op.path.startsWith("/") ? "" : "/"}${op.path}`;
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              operationId: op.operationId,
              method: op.method,
              path: op.path,
              summary: op.summary,
              baseUrlExample: base,
              completeUrl,
              raw: op.raw,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/server.ts:53-53 (schema)

  Input schema definition using Zod, specifying 'operationId' as a required string parameter.

  inputSchema: { operationId: z.string() },

• src/server.ts:48-88 (registration)

  Registration of the "describe_api" MCP tool via server.registerTool, including title, description, schema, and inline handler.

  server.registerTool(
    "describe_api",
    {
      title: "Describe API",
      description: "operationIdの詳細（paths/method/要約/原文）を返す",
      inputSchema: { operationId: z.string() },
    },
    async ({ operationId }: { operationId: string }) => {
      const op = await findOperationById(operationId);
      if (!op)
        return {
          content: [
            { type: "text", text: `Unknown operationId: ${operationId}` },
          ],
          isError: true,
        };
      const cfg = getConfig();
      const base = cfg.baseUrl.replace(/\/$/, "");
      const completeUrl = `${base}${op.path.startsWith("/") ? "" : "/"}${op.path}`;
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                operationId: op.operationId,
                method: op.method,
                path: op.path,
                summary: op.summary,
                baseUrlExample: base,
                completeUrl,
                raw: op.raw,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

• src/openapi.ts:51-69 (helper)

  Supporting helper function that scans the OpenAPI specification to find and return the operation matching the given operationId, including raw operation object. Used directly in the describe_api handler.

  export async function findOperationById(
    operationId: string
  ): Promise<(Operation & { raw: any }) | null> {
    const spec = await loadOpenApi();
    for (const [path, methods] of Object.entries(spec.paths ?? {})) {
      for (const [method, op] of Object.entries(methods ?? {})) {
        if ((op as any)?.operationId === operationId) {
          return {
            operationId,
            method: method.toUpperCase(),
            path,
            summary: (op as any)?.summary,
            raw: op,
          };
        }
      }
    }
    return null;
  }