mcp-openapi-runner

Instructions

Implementation Reference

• src/index.ts:55-63 (handler)

  Registration and handler implementation for the list_endpoints tool. It calls getEndpointSummaries to generate the output.

  server.tool(
    "list_endpoints",
    `List all available endpoints in the ${apiTitle}. ` +
      "Call this first to discover what operations are available and get their operationIds.",
    {},
    async () => ({
      content: [{ type: "text" as const, text: getEndpointSummaries(spec) }],
    })
  );

• src/endpoints.ts:48-101 (helper)

  Helper function that generates the formatted summary of endpoints for the list_endpoints tool.

  export function getEndpointSummaries(spec: OpenAPIV3.Document): string {
    const endpoints = getAllEndpoints(spec);
    const lines: string[] = [
      `# ${spec.info.title} (v${spec.info.version})`,
      "",
    ];
  
    if (spec.info.description) {
      lines.push(spec.info.description.split("\n")[0], "");
    }
  
    if (spec.servers?.[0]?.url) {
      lines.push(`Base URL: ${spec.servers[0].url}`, "");
    }
  
    // Group by first tag
    const byTag = new Map<string, EndpointInfo[]>();
    for (const ep of endpoints) {
      const tag = ep.operation.tags?.[0] ?? "General";
      if (!byTag.has(tag)) byTag.set(tag, []);
      byTag.get(tag)!.push(ep);
    }
  
    for (const [tag, eps] of byTag) {
      lines.push(`## ${tag}`);
      for (const ep of eps) {
        const summary = ep.operation.summary ?? ep.operation.description ?? "";
        lines.push(
          `- **${ep.operationId}** \`${ep.method.toUpperCase()} ${ep.path}\`${summary ? ` — ${summary}` : ""}`
        );
  
        const params = (ep.operation.parameters ?? []) as OpenAPIV3.ParameterObject[];
        const required = params.filter((p) => p.required).map((p) => `${p.name} (${p.in})`);
        const optional = params.filter((p) => !p.required).map((p) => `${p.name} (${p.in})`);
  
        if (required.length > 0) {
          lines.push(`  Required params: ${required.join(", ")}`);
        }
        if (optional.length > 0) {
          lines.push(`  Optional params: ${optional.join(", ")}`);
        }
  
        const requestBody = ep.operation.requestBody as OpenAPIV3.RequestBodyObject | undefined;
        if (requestBody) {
          const bodyRequired = requestBody.required ? " (required)" : " (optional)";
          lines.push(`  Request body${bodyRequired}`);
        }
      }
      lines.push("");
    }
  
    lines.push(`Total: ${endpoints.length} endpoint${endpoints.length !== 1 ? "s" : ""}`);
    return lines.join("\n");
  }