List REST endpoints

Instructions

Implementation Reference

• src/lib/openapi.ts:44-69 (handler)

  Core handler: async function listEndpoints() that loads the OpenAPI spec, iterates over paths/methods, applies optional tag/pathContains filters, and returns a sorted array of EndpointSummary objects.

  export async function listEndpoints(filter?: {
    tag?: string;
    pathContains?: string;
  }): Promise<EndpointSummary[]> {
    const spec = await loadOpenApi();
    if (!spec?.paths) return [];
    const out: EndpointSummary[] = [];
    for (const [path, methods] of Object.entries(spec.paths)) {
      for (const [method, op] of Object.entries(methods)) {
        if (!["get", "post", "put", "patch", "delete", "options", "head"].includes(method)) continue;
        const summary: EndpointSummary = {
          method: method.toUpperCase(),
          path,
          operationId: op.operationId,
          summary: op.summary,
          tags: op.tags,
        };
        if (filter?.tag && !(op.tags ?? []).includes(filter.tag)) continue;
        if (filter?.pathContains && !path.toLowerCase().includes(filter.pathContains.toLowerCase())) continue;
        out.push(summary);
      }
    }
    return out.sort((a, b) =>
      a.path === b.path ? a.method.localeCompare(b.method) : a.path.localeCompare(b.path),
    );
  }

• src/server.ts:154-169 (handler)

  MCP tool handler: the callback lambda registered for 'list_endpoints' that calls listEndpoints() with filter params and formats the response as text.

    async ({ tag, pathContains }) => {
      const endpoints = await listEndpoints({ tag, pathContains });
      if (!endpoints.length) {
        return textResponse(
          "No endpoints found. The OpenAPI spec may not be bundled — read `api/openapi-status` for instructions.",
        );
      }
      const lines = endpoints.map(
        (e) =>
          `${e.method.padEnd(6)} ${e.path}${e.summary ? `  — ${e.summary}` : ""}${
            e.tags?.length ? `  [${e.tags.join(", ")}]` : ""
          }`,
      );
      return textResponse(lines.join("\n"));
    },
  );

• src/lib/openapi.ts:36-42 (schema)

  Type definition: EndpointSummary interface describing the shape of each returned endpoint (method, path, operationId, summary, tags).

  export interface EndpointSummary {
    method: string;
    path: string;
    operationId?: string;
    summary?: string;
    tags?: string[];
  }

• src/server.ts:146-152 (schema)

  Input schema: Zod schema for optional 'tag' and 'pathContains' parameters.

  inputSchema: {
    tag: z.string().optional().describe("Filter by OpenAPI tag (e.g. `Analysis`, `Sessions`)."),
    pathContains: z
      .string()
      .optional()
      .describe("Substring filter on the URL path (e.g. `analyze`)."),
  },

• src/server.ts:140-169 (registration)

  Registration: server.registerTool('list_endpoints', ...) which wires the tool name, description, input schema, and handler.

  server.registerTool(
    "list_endpoints",
    {
      title: "List REST endpoints",
      description:
        "List ProsodyAI REST API endpoints from the bundled OpenAPI spec. Optional filters by tag or path substring.",
      inputSchema: {
        tag: z.string().optional().describe("Filter by OpenAPI tag (e.g. `Analysis`, `Sessions`)."),
        pathContains: z
          .string()
          .optional()
          .describe("Substring filter on the URL path (e.g. `analyze`)."),
      },
    },
    async ({ tag, pathContains }) => {
      const endpoints = await listEndpoints({ tag, pathContains });
      if (!endpoints.length) {
        return textResponse(
          "No endpoints found. The OpenAPI spec may not be bundled — read `api/openapi-status` for instructions.",
        );
      }
      const lines = endpoints.map(
        (e) =>
          `${e.method.padEnd(6)} ${e.path}${e.summary ? `  — ${e.summary}` : ""}${
            e.tags?.length ? `  [${e.tags.join(", ")}]` : ""
          }`,
      );
      return textResponse(lines.join("\n"));
    },
  );