split_transaction

Instructions

Implementation Reference

• src/tools/transactions.ts:666-684 (handler)

  Handler for split_transaction tool: calls POST /transactions/split/{id} with child_transactions array. Returns the API response data on success.

  async ({ transaction_id, child_transactions }) => {
      try {
          const response = await api.post(
              `/transactions/split/${transaction_id}`,
              { child_transactions },
          );
  
          if (!response.ok) {
              return handleApiError(
                  response,
                  "Failed to split transaction",
              );
          }
  
          return dataResponse(await response.json());
      } catch (error) {
          return catchError(error, "Failed to split transaction");
      }
  },

• src/tools/transactions.ts:645-685 (registration)

  Registration of split_transaction tool on the MCP server, with description, input schema, and annotations.

  server.registerTool(
      "split_transaction",
      {
          description:
              "Split an existing transaction into 2-500 child transactions. The sum of child amounts must equal the parent's amount. After splitting, the parent is hidden from get_transactions and accessible via get_single_transaction (returns the parent with `children`).",
          inputSchema: {
              transaction_id: z.coerce
                  .number()
                  .describe("ID of the transaction to split."),
              child_transactions: z
                  .array(splitChildSchema)
                  .min(2)
                  .max(500)
                  .describe(
                      "Children to create. Sum of amounts must equal the parent's amount.",
                  ),
          },
          annotations: {
              idempotentHint: false,
          },
      },
      async ({ transaction_id, child_transactions }) => {
          try {
              const response = await api.post(
                  `/transactions/split/${transaction_id}`,
                  { child_transactions },
              );
  
              if (!response.ok) {
                  return handleApiError(
                      response,
                      "Failed to split transaction",
                  );
              }
  
              return dataResponse(await response.json());
          } catch (error) {
              return catchError(error, "Failed to split transaction");
          }
      },
  );

• src/tools/transactions.ts:23-51 (schema)

  Zod schema for each child transaction in the split, defining amount (required), payee, date, category_id, tag_ids, and notes (all optional except amount).

  const splitChildSchema = z.object({
      amount: z.coerce
          .number()
          .describe(
              "Amount of this split. Sum of all children must equal the parent's amount.",
          ),
      payee: z
          .string()
          .max(140)
          .optional()
          .describe("Defaults to the parent's payee."),
      date: z
          .string()
          .regex(/^\d{4}-\d{2}-\d{2}$/, "Must be YYYY-MM-DD format")
          .optional()
          .describe("Defaults to the parent's date."),
      category_id: z.coerce
          .number()
          .optional()
          .describe(
              "Category ID. Defaults to parent's category. Cannot be a category group.",
          ),
      tag_ids: z.array(z.coerce.number()).optional(),
      notes: z
          .string()
          .max(350)
          .optional()
          .describe("Defaults to the parent's notes."),
  });

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

  API helper object providing post method used by split_transaction handler (calls POST /transactions/split/{id}).

  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),
  };