Money Lover MCP Server

Instructions

Implementation Reference

• src/server.js:411-449 (registration)

  Registration of the 'add_transaction' MCP tool, including inline schema and handler function.

  server.registerTool(
    'add_transaction',
    {
      title: 'Add Transaction',
      description: 'Create a new transaction in a wallet.',
      inputSchema: {
        ...tokenArgument,
        walletId: z.string().min(1).describe('Wallet identifier'),
        categoryId: z.string().min(1).describe('Category identifier'),
        amount: z.string().min(1).describe('Transaction amount as string'),
        note: z.string().optional().describe('Optional transaction note'),
        date: z
          .string()
          .regex(/\d{4}-\d{2}-\d{2}/)
          .describe('Display date in YYYY-MM-DD format'),
        with: z
          .array(z.string())
          .optional()
          .describe('Optional array of related parties')
      }
    },
    async ({ token, ...payload }) => {
      try {
        const data = await runWithClient(token, client =>
          client.addTransaction({
            walletId: payload.walletId,
            categoryId: payload.categoryId,
            amount: payload.amount,
            note: payload.note,
            date: payload.date,
            with: payload.with
          })
        );
        return formatSuccess(data ?? {});
      } catch (error) {
        return formatError(error instanceof Error ? error : new Error(String(error)));
      }
    }
  );

• src/server.js:432-448 (handler)

  The MCP handler function for 'add_transaction' tool. It resolves the client using the token, calls client.addTransaction with the payload, and formats the success/error response.

  async ({ token, ...payload }) => {
    try {
      const data = await runWithClient(token, client =>
        client.addTransaction({
          walletId: payload.walletId,
          categoryId: payload.categoryId,
          amount: payload.amount,
          note: payload.note,
          date: payload.date,
          with: payload.with
        })
      );
      return formatSuccess(data ?? {});
    } catch (error) {
      return formatError(error instanceof Error ? error : new Error(String(error)));
    }
  }

• src/server.js:416-430 (schema)

  Input schema for the 'add_transaction' tool using Zod validation for parameters like walletId, categoryId, amount, note, date, and with.

  inputSchema: {
    ...tokenArgument,
    walletId: z.string().min(1).describe('Wallet identifier'),
    categoryId: z.string().min(1).describe('Category identifier'),
    amount: z.string().min(1).describe('Transaction amount as string'),
    note: z.string().optional().describe('Optional transaction note'),
    date: z
      .string()
      .regex(/\d{4}-\d{2}-\d{2}/)
      .describe('Display date in YYYY-MM-DD format'),
    with: z
      .array(z.string())
      .optional()
      .describe('Optional array of related parties')
  }

• src/moneyloverClient.js:147-165 (handler)

  Core implementation of addTransaction in MoneyloverClient class. Validates params, maps to API payload, and performs POST request to '/transaction/add' endpoint.

  async addTransaction(params) {
    if (!params || typeof params !== 'object') {
      throw new Error('params is required');
    }
  
    const payload = {
      with: Array.isArray(params.with) ? params.with : [],
      account: ensureString(params.walletId ?? params.WalletID, 'walletId'),
      category: ensureString(params.categoryId ?? params.CategoryID, 'categoryId'),
      amount: ensureString(params.amount ?? params.Amount, 'amount'),
      note: typeof params.note === 'string' ? params.note : params.Note ?? '',
      displayDate: ensureDateString(params.date ?? params.Date)
    };
  
    return this.#post('/transaction/add', {
      body: JSON.stringify(payload),
      headers: { 'Content-Type': 'application/json' }
    });
  }