list-manual-journals
Retrieve manual journals from Xero with optional filters by ID, date, or pagination to view specific entries or complete overviews.
Instructions
List all manual journals from Xero. Ask the user if they want to see a specific manual journal or all manual journals before running. Can optionally pass in manual journal ID to retrieve a specific journal, or a date to filter journals modified after that date. The response presents a complete overview of all manual journals currently registered in your Xero account, with their details. Ask the user if they want the next page of manual journals after running this tool if 10 manual journals are returned. If they want the next page, call this tool again with the next page number, modified date, and the manual journal ID if one was provided in the previous call.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| manualJournalId | No | Optional ID of the manual journal to retrieve | |
| modifiedAfter | No | Optional date YYYY-MM-DD to filter journals modified after this date | |
| page | No | Optional page number for pagination |
Implementation Reference
- The handler function for the 'list-manual-journals' MCP tool, which invokes the Xero-specific handler and formats the output as MCP content blocks.async (args) => { const response = await listXeroManualJournals( args?.page, args?.manualJournalId, args?.modifiedAfter, ); if (response.isError) { return { content: [ { type: "text" as const, text: `Error listing manual journals: ${response.error}`, }, ], }; } const manualJournals = response.result; return { content: [ { type: "text" as const, text: `Found ${manualJournals?.length || 0} manual journals:`, }, ...(manualJournals?.map((journal: ManualJournal) => ({ type: "text" as const, text: [ `Manual Journal ID: ${journal.manualJournalID}`, journal.narration ? `Description: ${journal.narration}` : "No description", journal.date ? `Date: ${journal.date}` : null, journal.journalLines ? journal.journalLines.map((line) => ({ type: "text" as const, text: [ `Line Amount: ${line.lineAmount}`, line.accountCode ? `Account Code: ${line.accountCode}` : "No account code", line.description ? `Description: ${line.description}` : "No description", line.taxType ? `Tax Type: ${line.taxType}` : "No tax type", `Tax Amount: ${line.taxAmount}`, ] .filter(Boolean) .join("\n"), })) : [{ type: "text" as const, text: "No journal lines" }], journal.lineAmountTypes ? `Line Amount Types: ${journal.lineAmountTypes}` : "No line amount types", journal.status ? `Status: ${journal.status}` : "No status", journal.url ? `URL: ${journal.url}` : "No URL", `Show on Cash Basis Reports: ${journal.showOnCashBasisReports}`, `Has Attachments: ${journal.hasAttachments}`, journal.updatedDateUTC ? `Last Updated: ${journal.updatedDateUTC.toLocaleDateString()}` : "No last updated date", ] .filter(Boolean) .join("\n"), })) || []), ], }; },
- Zod schema defining the input parameters for the 'list-manual-journals' tool.{ manualJournalId: z .string() .optional() .describe("Optional ID of the manual journal to retrieve"), modifiedAfter: z .string() .optional() .describe( "Optional date YYYY-MM-DD to filter journals modified after this date", ), page: z.number().optional().describe("Optional page number for pagination"), // TODO: where, order },
- src/tools/list/index.ts:32-58 (registration)Local registration of list tools including 'list-manual-journals' in the ListTools array.export const ListTools = [ ListAccountsTool, ListContactsTool, ListCreditNotesTool, ListInvoicesTool, ListItemsTool, ListManualJournalsTool, ListQuotesTool, ListTaxRatesTool, ListTrialBalanceTool, ListPaymentsTool, ListProfitAndLossTool, ListBankTransactionsTool, ListPayrollEmployeesTool, ListReportBalanceSheetTool, ListOrganisationDetailsTool, ListPayrollEmployeeLeaveTool, ListPayrollLeavePeriodsToolTool, ListPayrollEmployeeLeaveTypesTool, ListPayrollEmployeeLeaveBalancesTool, ListPayrollLeaveTypesTool, ListAgedReceivablesByContact, ListAgedPayablesByContact, ListPayrollTimesheetsTool, ListContactGroupsTool, ListTrackingCategoriesTool ];
- src/tools/tool-factory.ts:20-22 (registration)MCP server registration of all ListTools, including 'list-manual-journals'.ListTools.map((tool) => tool()).forEach((tool) => server.tool(tool.name, tool.description, tool.schema, tool.handler), );
- Supporting handler that fetches manual journals from the Xero API and handles errors.export async function listXeroManualJournals( page: number = 1, manualJournalId?: string, modifiedAfter?: string, ): Promise<XeroClientResponse<ManualJournal[]>> { try { const manualJournals = await getManualJournals( page, manualJournalId, modifiedAfter, ); return { result: manualJournals, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }