Create Transaction

Instructions

Implementation Reference

• src/tools/CreateTransactionTool.ts:43-93 (handler)

  The main execution function for the ynab_create_transaction tool. Converts dollar amounts to milliunits, builds a PostTransactionsWrapper, calls the YNAB API's createTransaction endpoint, and returns success/error responses.

  export async function execute(input: CreateTransactionInput, api: ynab.API) {
    try {
      const budgetId = getBudgetId(input.budgetId);
  
      if(!input.payeeId && !input.payeeName) {
        throw new Error("Either payeeId or payeeName must be provided");
      }
  
      const milliunitAmount = Math.round(input.amount * 1000);
  
      const transaction: ynab.PostTransactionsWrapper = {
        transaction: {
          account_id: input.accountId,
          date: input.date,
          amount: milliunitAmount,
          payee_id: input.payeeId,
          payee_name: input.payeeName,
          category_id: input.categoryId,
          memo: input.memo,
          cleared: input.cleared ? ynab.TransactionClearedStatus.Cleared : ynab.TransactionClearedStatus.Uncleared,
          approved: input.approved ?? false,
          flag_color: input.flagColor as ynab.TransactionFlagColor,
        }
      };
  
      const response = await api.transactions.createTransaction(
        budgetId,
        transaction
      );
  
      if (!response.data.transaction) {
        throw new Error("Failed to create transaction - no transaction data returned");
      }
  
      return {
        content: [{ type: "text" as const, text: JSON.stringify({
          success: true,
          transactionId: response.data.transaction.id,
          message: "Transaction created successfully",
        }, null, 2) }]
      };
    } catch (error) {
      console.error("Error creating transaction:", error);
      return {
        content: [{ type: "text" as const, text: JSON.stringify({
          success: false,
          error: getErrorMessage(error),
        }, null, 2) }]
      };
    }
  }

• src/tools/CreateTransactionTool.ts:7-19 (schema)

  Input schema definition using Zod, describing all optional and required parameters (budgetId, accountId, date, amount, payeeId, payeeName, categoryId, memo, cleared, approved, flagColor).

  export const inputSchema = {
    budgetId: z.string().optional().describe("The id of the budget to create the transaction in (optional, defaults to the budget set in the YNAB_BUDGET_ID environment variable)"),
    accountId: z.string().describe("The id of the account to create the transaction in"),
    date: z.string().describe("The date of the transaction in ISO format (e.g. 2024-03-24)"),
    amount: z.number().describe("The amount in dollars (e.g. 10.99)"),
    payeeId: z.string().optional().describe("The id of the payee (optional if payeeName is provided)"),
    payeeName: z.string().optional().describe("The name of the payee (optional if payeeId is provided)"),
    categoryId: z.string().optional().describe("The category id for the transaction (optional)"),
    memo: z.string().optional().describe("A memo/note for the transaction (optional)"),
    cleared: z.boolean().optional().describe("Whether the transaction is cleared (optional, defaults to false)"),
    approved: z.boolean().optional().describe("Whether the transaction is approved (optional, defaults to false)"),
    flagColor: z.string().optional().describe("The transaction flag color (red, orange, yellow, green, blue, purple) (optional)"),
  };

• src/tools/CreateTransactionTool.ts:21-33 (schema)

  TypeScript interface defining the shape of the CreateTransactionInput object used by the execute function.

  interface CreateTransactionInput {
    budgetId?: string;
    accountId: string;
    date: string;
    amount: number;
    payeeId?: string;
    payeeName?: string;
    categoryId?: string;
    memo?: string;
    cleared?: boolean;
    approved?: boolean;
    flagColor?: string;
  }

• src/index.ts:51-55 (registration)

  Registration of the tool with the MCP server using server.registerTool(), linking the name 'ynab_create_transaction' to the inputSchema and execute handler.

  server.registerTool(CreateTransactionTool.name, {
    title: "Create Transaction",
    description: CreateTransactionTool.description,
    inputSchema: CreateTransactionTool.inputSchema,
  }, async (input) => CreateTransactionTool.execute(input, api));

• dist/tools/errorUtils.js:5-35 (helper)

  Helper function getErrorMessage used to extract meaningful error messages from various error types including YNAB API error responses.

  export function getErrorMessage(error) {
      // Handle standard Error objects
      if (error instanceof Error) {
          return error.message;
      }
      // Handle YNAB API error responses which have the structure:
      // { error: { id: '...', name: '...', detail: '...' } }
      if (typeof error === 'object' &&
          error !== null &&
          'error' in error &&
          typeof error.error === 'object') {
          const ynabError = error.error;
          if (ynabError.detail) {
              return ynabError.detail;
          }
          if (ynabError.name) {
              return ynabError.name;
          }
      }
      // Fallback: try to stringify the error
      try {
          const stringified = JSON.stringify(error);
          if (stringified !== '{}') {
              return stringified;
          }
      }
      catch {
          // Ignore stringify errors
      }
      return 'Unknown error occurred';
  }