Money Manager MCP Server

Instructions

Implementation Reference

• src/tools/handlers.ts:164-223 (handler)

  The core handler function for the transaction_list tool. Validates input using TransactionListInputSchema, calls the Money Manager API /getDataByPeriod endpoint with XML parsing, transforms raw XML response into structured TransactionListResponse including count and array of transactions.

  export async function handleTransactionList(
    httpClient: HttpClient,
    input: unknown,
  ): Promise<TransactionListResponse> {
    const validated = TransactionListInputSchema.parse(input);
  
    const params: Record<string, string | undefined> = {
      startDate: validated.startDate,
      endDate: validated.endDate,
      mbid: validated.mbid,
      assetId: validated.assetId,
    };
  
    const rawResponse = await httpClient.getXml<RawTransactionXmlResponse>(
      "/getDataByPeriod",
      params,
    );
  
    // Handle case where response is empty or dataset is missing/empty
    if (!rawResponse || !rawResponse.dataset) {
      return { count: 0, transactions: [] };
    }
  
    // Handle case where dataset is an empty string (can happen with empty XML elements)
    // When xml2js parses <dataset results="0"></dataset> with ignoreAttrs:true,
    // it returns { dataset: "" } instead of { dataset: { results: "0" } }
    if (typeof rawResponse.dataset === "string") {
      return { count: 0, transactions: [] };
    }
  
    // Parse the XML response
    const count = parseInt(rawResponse.dataset?.results || "0", 10);
    let transactions: Transaction[] = [];
  
    if (rawResponse.dataset?.row) {
      const rows = Array.isArray(rawResponse.dataset.row)
        ? rawResponse.dataset.row
        : [rawResponse.dataset.row];
  
      transactions = rows.map((row: RawTransactionRow) => ({
        id: row.id,
        mbDate: row.mbDate,
        assetId: row.assetId,
        toAssetId: row.toAssetId,
        targetAssetId: row.targetAssetId,
        payType: row.payType,
        mcid: row.mcid,
        mbCategory: row.mbCategory,
        mcscid: row.mcscid,
        subCategory: row.subCategory,
        mbContent: row.mbContent,
        mbCash: parseFloat(row.mbCash) || 0,
        inOutCode: row.inOutCode,
        inOutType: row.inOutType,
        mbDetailContent: row.mbDetailContent,
      }));
    }
  
    return { count, transactions };
  }

• src/schemas/index.ts:92-101 (schema)

  Zod input validation schema for transaction_list tool defining required startDate, endDate, mbid and optional assetId.

   * Input schema for transaction_list tool
   */
  export const TransactionListInputSchema = z.object({
    startDate: DateSchema,
    endDate: DateSchema,
    mbid: MbidSchema,
    assetId: z.string().optional(),
  });
  
  export type TransactionListInput = z.infer<typeof TransactionListInputSchema>;

• src/index.ts:47-71 (registration)

  MCP tool registration in the main server file, defining the tool name, description, and JSON schema for listTools response.

    name: "transaction_list",
    description: "Lists transactions within a date range.",
    inputSchema: {
      type: "object" as const,
      properties: {
        startDate: {
          type: "string",
          description: "Start date (YYYY-MM-DD)",
        },
        endDate: {
          type: "string",
          description: "End date (YYYY-MM-DD)",
        },
        mbid: {
          type: "string",
          description: "Money book ID",
        },
        assetId: {
          type: "string",
          description: "Optional: Filter by asset ID",
        },
      },
      required: ["startDate", "endDate", "mbid"],
    },
  },

• src/tools/handlers.ts:797-797 (registration)

  Internal handler registry mapping 'transaction_list' to its handler function for dynamic execution.

  transaction_list: handleTransactionList,

• src/types/index.ts:84-87 (schema)

  TypeScript interface defining the output shape of transaction_list tool response.

  export interface TransactionListResponse {
    count: number;
    transactions: Transaction[];
  }