get_all_categories

Instructions

Implementation Reference

• src/tools/categories.ts:12-60 (registration)

  The tool 'get_all_categories' is registered via registerCategoryTools on the McpServer. The registration is triggered at server startup in src/index.ts (line 26).

  export function registerCategoryTools(server: McpServer) {
      server.registerTool(
          "get_all_categories",
          {
              description:
                  "Get a list of all categories associated with the user's account. Returns categories in alphabetical order.",
              inputSchema: {
                  format: z
                      .enum(["flattened", "nested"])
                      .optional()
                      .describe(
                          "If `flattened`, returns a singular array of categories. If `nested`, returns top-level categories (either category groups or categories not part of a category group) in an array, with subcategories nested within the category group under the property children. Defaults to flattened.",
                      ),
                  is_group: z
                      .boolean()
                      .optional()
                      .describe(
                          "If true, returns only category groups. If false, returns only categories that are not category groups.",
                      ),
              },
              annotations: {
                  readOnlyHint: true,
              },
          },
          async ({ format, is_group }) => {
              try {
                  const params = new URLSearchParams();
                  if (format) params.append("format", format);
                  if (is_group !== undefined)
                      params.append("is_group", String(is_group));
  
                  const qs = params.toString();
                  const response = await api.get(
                      `/categories${qs ? `?${qs}` : ""}`,
                  );
  
                  if (!response.ok) {
                      return handleApiError(
                          response,
                          "Failed to get all categories",
                      );
                  }
  
                  return dataResponse(await response.json());
              } catch (error) {
                  return catchError(error, "Failed to get all categories");
              }
          },
      );

• src/tools/categories.ts:15-35 (schema)

  Input validation schema for 'get_all_categories' using Zod. Accepts optional 'format' (flattened|nested) and optional 'is_group' (boolean).

  {
      description:
          "Get a list of all categories associated with the user's account. Returns categories in alphabetical order.",
      inputSchema: {
          format: z
              .enum(["flattened", "nested"])
              .optional()
              .describe(
                  "If `flattened`, returns a singular array of categories. If `nested`, returns top-level categories (either category groups or categories not part of a category group) in an array, with subcategories nested within the category group under the property children. Defaults to flattened.",
              ),
          is_group: z
              .boolean()
              .optional()
              .describe(
                  "If true, returns only category groups. If false, returns only categories that are not category groups.",
              ),
      },
      annotations: {
          readOnlyHint: true,
      },
  },

• src/tools/categories.ts:36-59 (handler)

  Handler function for 'get_all_categories'. Makes a GET request to /categories with optional query params (format, is_group), then returns the JSON response via dataResponse.

  async ({ format, is_group }) => {
      try {
          const params = new URLSearchParams();
          if (format) params.append("format", format);
          if (is_group !== undefined)
              params.append("is_group", String(is_group));
  
          const qs = params.toString();
          const response = await api.get(
              `/categories${qs ? `?${qs}` : ""}`,
          );
  
          if (!response.ok) {
              return handleApiError(
                  response,
                  "Failed to get all categories",
              );
          }
  
          return dataResponse(await response.json());
      } catch (error) {
          return catchError(error, "Failed to get all categories");
      }
  },

• src/api.ts:146-153 (helper)

  The 'api.get' helper used by the handler sends a GET request with retry logic, timeout, and authorization header to the LunchMoney API.

  export const api = {
      get: (path: string) => apiRequest("GET", path),
      post: (path: string, body?: unknown) => apiRequest("POST", path, body),
      put: (path: string, body: unknown) => apiRequest("PUT", path, body),
      delete: (path: string, body?: unknown) => apiRequest("DELETE", path, body),
      upload: (path: string, formData: FormData) =>
          apiUpload("POST", path, formData),
  };

• src/format.ts:1-18 (helper)

  The 'dataResponse' helper formats the API response data into TOON format for the MCP tool output.

  import { encode } from "@toon-format/toon";
  
  function stripNulls(value: unknown): unknown {
      if (value === null) return undefined;
      if (Array.isArray(value)) return value.map(stripNulls);
      if (typeof value === "object") {
          const result: Record<string, unknown> = {};
          for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
              if (v !== null) result[k] = stripNulls(v);
          }
          return result;
      }
      return value;
  }
  
  export function formatData(data: unknown): string {
      return encode(stripNulls(data));
  }