get_categories

Instructions

Implementation Reference

• src/tools/categories.ts:7-38 (registration)

  Registration of the 'get_categories' tool via server.registerTool with the name 'get_categories'. Registers the schema and the handler callback.

  export function registerCategorieTools(server: McpServer): void {
    server.registerTool(
      "get_categories",
      {
        description: "Get all category records",
        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)"),
          published: z.enum(["published"]).optional().describe("Show only published categories"),
          sort: z
            .array(z.enum(["position:asc", "position:desc"]))
            .optional()
            .describe(
              "Sort the results. Can change order by using `<sort_by>:<direction>` where `<direction>` is either `asc` or `desc`",
            ),
        },
      },
      async ({ cursor, per_page, published, sort }) => {
        try {
          const result = await apiList<EduframeRecord>("/categories", { cursor, per_page, published, sort });
          void logResponse("get_categories", { cursor, per_page, published, sort }, result);
          const toolResult = formatList(result.records, "categories");
          if (result.nextCursor) {
            toolResult.content.push({ type: "text", text: `\nNext page cursor: ${result.nextCursor}` });
          }
          return toolResult;
        } catch (error) {
          return formatError(error);
        }
      },
    );

• src/tools/categories.ts:10-23 (schema)

  Input schema for 'get_categories' tool defining cursor, per_page, published, and sort parameters using Zod validation.

  {
    description: "Get all category records",
    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)"),
      published: z.enum(["published"]).optional().describe("Show only published categories"),
      sort: z
        .array(z.enum(["position:asc", "position:desc"]))
        .optional()
        .describe(
          "Sort the results. Can change order by using `<sort_by>:<direction>` where `<direction>` is either `asc` or `desc`",
        ),
    },

• src/tools/categories.ts:25-37 (handler)

  Handler function for 'get_categories' tool. Calls apiList to GET /categories, logs the response, formats results with formatList, and returns paginated data with next cursor.

  async ({ cursor, per_page, published, sort }) => {
    try {
      const result = await apiList<EduframeRecord>("/categories", { cursor, per_page, published, sort });
      void logResponse("get_categories", { cursor, per_page, published, sort }, result);
      const toolResult = formatList(result.records, "categories");
      if (result.nextCursor) {
        toolResult.content.push({ type: "text", text: `\nNext page cursor: ${result.nextCursor}` });
      }
      return toolResult;
    } catch (error) {
      return formatError(error);
    }
  },

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

  The apiList helper function used by get_categories to perform a paginated GET request to the API.

  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/tools/index.ts:8-8 (helper)

  Import of registerCategorieTools which registers the get_categories tool.

  import { registerCategorieTools } from "./categories";