get_programs

Instructions

Implementation Reference

• src/tools/program_programs.ts:17-41 (handler)

  Registration and handler for the 'get_programs' tool. The handler calls apiList('/program/programs', {cursor, per_page}) to fetch paginated programs, logs the response, and formats the result via formatList().

  export function registerProgramProgramTools(server: McpServer): void {
    server.registerTool(
      "get_programs",
      {
        description: "Get all programs",
        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
        inputSchema: {
          cursor: z.string().optional().describe("Cursor for fetching the next page of results"),
          per_page: z.number().int().positive().optional().describe("Number of results per page (default: 25)"),
        },
      },
      async ({ cursor, per_page }) => {
        try {
          const result = await apiList<EduframeRecord>("/program/programs", { cursor, per_page });
          void logResponse("get_programs", { cursor, per_page }, result);
          const toolResult = formatList(result.records, "program programs");
          if (result.nextCursor) {
            toolResult.content.push({ type: "text", text: `\nNext page cursor: ${result.nextCursor}` });
          }
          return toolResult;
        } catch (error) {
          return formatError(error);
        }
      },
    );

• src/tools/program_programs.ts:23-26 (schema)

  Input schema for get_programs: optional cursor (string) for pagination and per_page (positive int, default 25).

  inputSchema: {
    cursor: z.string().optional().describe("Cursor for fetching the next page of results"),
    per_page: z.number().int().positive().optional().describe("Number of results per page (default: 25)"),
  },

• src/tools/index.ts:128-132 (registration)

  Central registration: registerProgramProgramTools is called from registerAllTools(), which iterates over all tool registrations and invokes them with the McpServer instance.

  export function registerAllTools(server: McpServer): void {
    for (const register of tools) {
      register(server);
    }
  }

• src/api.ts:122-137 (helper)

  The apiList() helper function performs a GET request to a paginated list endpoint, parses the Link header for cursor-based pagination, and returns records with nextCursor.

  export async function apiList<T>(path: string, query?: Record<string, QueryValue>): Promise<ListResult<T>> {
    const { token } = getConfig();
    const url = buildUrl(path, query);
  
    const response = await fetch(url.toString(), {
      method: "GET",
      headers: buildHeaders(token),
    });
  
    await checkResponse(response);
  
    const records = (await response.json()) as T[];
    const nextCursor = parseNextCursor(response.headers.get("Link"));
  
    return { records, nextCursor };
  }

• src/formatters.ts:40-60 (helper)

  The formatList() helper formats a list of records into a human-readable CallToolResult, displaying the count and JSON content.

  export function formatList(records: EduframeRecord[], resourceName: string): CallToolResult {
    if (records.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No ${resourceName} found.`,
          },
        ],
      };
    }
  
    return {
      content: [
        {
          type: "text",
          text: `Found ${records.length} ${resourceName}:\n\n${formatJSON(records)}${RESPONSE_LOG_HINT}`,
        },
      ],
    };
  }