[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_155":156,"_157":158},"routes/_app.x.$handle.$name",{"_95":94,"_32":45,"_104":85,"_27":53,"_13":14,"_105":-5,"_11":106,"_107":108,"_109":110,"_111":112,"_113":114,"_20":-5,"_115":-5,"_116":-5,"_117":25,"_118":119,"_120":58,"_121":-5,"_122":-5,"_123":124},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_43":44,"_32":45,"_38":46,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":31,"_57":58,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":25},"version",13,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":28,"_33":34,"_35":37,"_38":39,"_40":14,"_41":42,"_24":25},"previous",{"_30":31,"_32":28,"_33":34,"_35":36},"deleted",false,"deletedHere","path","xero-mcp.ts","latestPath","fileId","ba80d286-8174-11f1-bc6f-1607ee4eb77e","name","fileType","http","content","// Xero MCP server for Val Town (Deno / TypeScript) — Custom Connection edition\n//\n// A remote MCP server (Streamable HTTP transport) that reads and recodes Xero\n// bank transactions: change the account code and set/clear a tracking category\n// on a transaction's line items.\n//\n// Auth to Xero uses a Xero CUSTOM CONNECTION (OAuth2 client_credentials grant):\n// no redirect URI, no callback, no consent screen. The server exchanges the\n// client id + secret for a short-lived access token directly.\n//\n// Single-file HTTP val. See README-valtown.md for setup.\n//\n// Routes:\n// GET / -> health / status page\n// GET /check?token= -> mint a token and confirm the Xero connection\n// POST / (any path) -> MCP JSON-RPC endpoint (token-protected)\n\nimport { blob } from \"https://esm.town/v/std/blob\";\n\n// ----------------------------- config --------------------------------------\n\nconst TOKEN_URL = \"https://identity.xero.com/connect/token\";\nconst CONNECTIONS_URL = \"https://api.xero.com/connections\";\nconst API_BASE = \"https://api.xero.com/api.xro/2.0\";\nconst TOKEN_SKEW_MS = 120_000;\nconst BLOB_TOKEN_KEY = \"xero_mcp_cc_token\";\n// Custom connections do not use offline_access (no refresh token).\n// Granular scopes: banktransactions (read+write) covers recoding; settings.read\n// covers reading the chart of accounts and tracking categories.\nconst DEFAULT_SCOPES =\n \"accounting.banktransactions accounting.settings.read projects\";\nconst PROTOCOL_VERSION = \"2025-06-18\";\nconst SERVER_INFO = { name: \"xero-mcp\", version: \"0.2.0\" };\n\nfunction env(name: string): string | undefined {\n return Deno.env.get(name)?.trim() || undefined;\n}\nfunction requireEnv(name: string): string {\n const v = env(name);\n if (!v) throw new Error(`Missing required environment variable ${name}`);\n return v;\n}\nconst clientId = () => requireEnv(\"XERO_CLIENT_ID\");\nconst clientSecret = () => requireEnv(\"XERO_CLIENT_SECRET\");\nconst scopes = () => env(\"XERO_SCOPES\") || DEFAULT_SCOPES;\nconst authToken = () => env(\"MCP_AUTH_TOKEN\");\n\n// ----------------------------- token (client credentials) ------------------\n\ninterface CachedToken {\n access_token: string;\n expires_at: number; // epoch ms\n tenant_id: string;\n tenant_name: string;\n}\n\nexport async function saveCached(t: CachedToken): Promise {\n await blob.setJSON(BLOB_TOKEN_KEY, t);\n}\nasync function loadCached(): Promise {\n try {\n return ((await blob.getJSON(BLOB_TOKEN_KEY)) as CachedToken) ?? null;\n } catch {\n return null;\n }\n}\n\nfunction basicAuthHeader(): string {\n return \"Basic \" + btoa(`${clientId()}:${clientSecret()}`);\n}\n\nasync function mintToken(): Promise {\n const resp = await fetch(TOKEN_URL, {\n method: \"POST\",\n headers: {\n Authorization: basicAuthHeader(),\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n },\n body: new URLSearchParams({\n grant_type: \"client_credentials\",\n scope: scopes(),\n }),\n });\n if (!resp.ok) {\n const t = await resp.text();\n throw new Error(\n `Failed to get Xero token (${resp.status}). Check the client id/secret and ` +\n `that the custom connection is active with the right scopes. ${\n t.slice(0, 300)\n }`,\n );\n }\n const data = await resp.json();\n const access: string = data.access_token;\n\n // Resolve the single connected organisation (custom connection = one org).\n let tenant_id = env(\"XERO_TENANT_ID\") || \"\";\n let tenant_name = \"\";\n if (!tenant_id) {\n const cr = await fetch(CONNECTIONS_URL, {\n headers: {\n Authorization: `Bearer ${access}`,\n Accept: \"application/json\",\n },\n });\n const conns = cr.ok ? await cr.json() : [];\n const org = conns.find((c: any) => c.tenantType === \"ORGANISATION\") ??\n conns[0];\n if (!org) {\n throw new Error(\n \"Token obtained, but no organisation is connected to this custom connection. \" +\n \"Re-authorise the connection in the Xero developer portal.\",\n );\n }\n tenant_id = org.tenantId;\n tenant_name = org.tenantName ?? \"\";\n }\n\n const token: CachedToken = {\n access_token: access,\n expires_at: Date.now() + Number(data.expires_in ?? 1800) * 1000,\n tenant_id,\n tenant_name,\n };\n await saveCached(token);\n return token;\n}\n\nasync function getToken(force = false): Promise {\n if (!force) {\n const cached = await loadCached();\n if (\n cached && cached.tenant_id &&\n Date.now() < cached.expires_at - TOKEN_SKEW_MS\n ) {\n return cached;\n }\n }\n return await mintToken();\n}\n\n// ----------------------------- Xero API ------------------------------------\n\ninterface XeroReq {\n searchParams?: Record;\n body?: unknown;\n}\n\nasync function xeroFetch(\n method: string,\n path: string,\n opts: XeroReq = {},\n retried = false,\n): Promise {\n const t = await getToken();\n const u = new URL(path.startsWith(\"http\") ? path : `${API_BASE}${path}`);\n if (opts.searchParams) {\n for (const [k, v] of Object.entries(opts.searchParams)) {\n if (v !== undefined && v !== null && v !== \"\") {\n u.searchParams.set(k, String(v));\n }\n }\n }\n const headers: Record = {\n Authorization: `Bearer ${t.access_token}`,\n \"Xero-tenant-id\": t.tenant_id,\n Accept: \"application/json\",\n };\n if (opts.body !== undefined) headers[\"Content-Type\"] = \"application/json\";\n\n const resp = await fetch(u.toString(), {\n method,\n headers,\n body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,\n });\n\n if (resp.status === 401 && !retried) {\n await getToken(true); // force a fresh token and retry once\n return xeroFetch(method, path, opts, true);\n }\n if (resp.status === 429 && !retried) {\n const wait = Number(resp.headers.get(\"Retry-After\") ?? \"2\");\n await new Promise((r) => setTimeout(r, Math.min(wait, 30) * 1000));\n return xeroFetch(method, path, opts, true);\n }\n if (!resp.ok) {\n const text = await resp.text();\n throw new Error(\n `Xero API error ${resp.status} for ${method} ${path}: ${\n text.slice(0, 500)\n }`,\n );\n }\n if (resp.status === 204) return {};\n return await resp.json();\n}\n\nconst getAccounts = async () =>\n (await xeroFetch(\"GET\", \"/Accounts\")).Accounts ?? [];\nconst getTrackingCategories = async () =>\n (await xeroFetch(\"GET\", \"/TrackingCategories\")).TrackingCategories ?? [];\nconst getBankTransactions = async (where?: string, order?: string, page = 1) =>\n (await xeroFetch(\"GET\", \"/BankTransactions\", {\n searchParams: { where, order, page },\n }))\n .BankTransactions ?? [];\nasync function getBankTransaction(id: string) {\n const items =\n (await xeroFetch(\"GET\", `/BankTransactions/${id}`)).BankTransactions ?? [];\n if (!items.length) {\n throw new Error(`No bank transaction found with ID ${id}.`);\n }\n return items[0];\n}\nasync function updateBankTransaction(txn: any) {\n const data = await xeroFetch(\"POST\", \"/BankTransactions\", {\n body: { BankTransactions: [txn] },\n });\n const items = data.BankTransactions ?? [];\n if (!items.length) {\n throw new Error(\"Xero did not return the updated transaction.\");\n }\n return items[0];\n}\n\n// ----------------------------- operations (pure) ---------------------------\n\nconst MS_DATE = /\\/Date\$(-?\\d+)(?:[+-]\\d{4})?\$\\//;\n\nexport function parseXeroDate(v: unknown): string {\n if (v === null || v === undefined) return \"\";\n const s = String(v);\n const m = s.match(MS_DATE);\n if (m) return new Date(parseInt(m[1], 10)).toISOString().slice(0, 10);\n return s.slice(0, 10);\n}\n\nfunction isoToDateTimeCall(iso: string): string {\n const [y, m, d] = iso.split(\"-\");\n return `DateTime(${parseInt(y)}, ${parseInt(m)}, ${parseInt(d)})`;\n}\n\nexport function buildWhere(o: {\n fromDate?: string;\n toDate?: string;\n contactId?: string;\n txnType?: string;\n extra?: string;\n}): string | undefined {\n const c: string[] = [];\n if (o.fromDate) c.push(`Date >= ${isoToDateTimeCall(o.fromDate)}`);\n if (o.toDate) c.push(`Date <= ${isoToDateTimeCall(o.toDate)}`);\n if (o.contactId) c.push(`Contact.ContactID == Guid(\"${o.contactId}\")`);\n if (o.txnType) c.push(`Type == \"${o.txnType}\"`);\n if (o.extra) c.push(`(${o.extra})`);\n return c.length ? c.join(\" && \") : undefined;\n}\n\nexport const summarizeAccount = (a: any) => ({\n code: a.Code,\n name: a.Name,\n type: a.Type,\n class: a.Class,\n status: a.Status,\n tax_type: a.TaxType,\n description: a.Description,\n});\n\nexport const summarizeTrackingCategory = (tc: any) => ({\n tracking_category_id: tc.TrackingCategoryID,\n name: tc.Name,\n status: tc.Status,\n options: (tc.Options ?? []).map((o: any) => ({\n tracking_option_id: o.TrackingOptionID,\n name: o.Name,\n status: o.Status,\n })),\n});\n\nconst trackingDisplay = (list: any[]): string[] =>\n (list ?? []).map((t) => `${t.Name ?? \"?\"}: ${t.Option ?? \"?\"}`);\n\nexport const summarizeLineItem = (li: any) => ({\n line_item_id: li.LineItemID,\n description: li.Description,\n account_code: li.AccountCode,\n line_amount: li.LineAmount,\n tax_type: li.TaxType,\n tracking: trackingDisplay(li.Tracking),\n});\n\nexport function summarizeTransaction(txn: any, includeLines = false): any {\n const c = txn.Contact ?? {};\n const b = txn.BankAccount ?? {};\n const s: any = {\n bank_transaction_id: txn.BankTransactionID,\n type: txn.Type,\n date: parseXeroDate(txn.Date),\n contact: c.Name,\n reference: txn.Reference,\n total: txn.Total,\n status: txn.Status,\n is_reconciled: txn.IsReconciled,\n bank_account: b.Name,\n line_count: (txn.LineItems ?? []).length,\n };\n if (includeLines) s.line_items = (txn.LineItems ?? []).map(summarizeLineItem);\n return s;\n}\n\nexport function validateAccountCode(accounts: any[], code: string): any {\n const target = String(code).trim();\n for (const a of accounts) {\n if (String(a.Code ?? \"\").trim() === target) {\n if (a.Status && a.Status !== \"ACTIVE\") {\n throw new Error(\n `Account code ${target} (${a.Name}) is not ACTIVE (status: ${a.Status}).`,\n );\n }\n return a;\n }\n }\n const known = accounts\n .map((a) => a.Code)\n .filter(Boolean)\n .map(String)\n .sort()\n .slice(0, 40)\n .join(\", \");\n throw new Error(\n `Account code \"${target}\" was not found in the chart of accounts. Known codes include: ${known}`,\n );\n}\n\nexport function resolveTrackingRef(\n cats: any[],\n categoryName: string,\n optionName: string,\n): any {\n const cl = categoryName.trim().toLowerCase();\n for (const tc of cats) {\n if (String(tc.Name ?? \"\").trim().toLowerCase() !== cl) continue;\n for (const o of tc.Options ?? []) {\n if (\n String(o.Name ?? \"\").trim().toLowerCase() ===\n optionName.trim().toLowerCase()\n ) {\n return {\n TrackingCategoryID: tc.TrackingCategoryID,\n TrackingOptionID: o.TrackingOptionID,\n Name: tc.Name,\n Option: o.Name,\n };\n }\n }\n const valid = (tc.Options ?? [])\n .filter((o: any) => (o.Status ?? \"ACTIVE\") === \"ACTIVE\")\n .map((o: any) => o.Name)\n .join(\", \");\n throw new Error(\n `Option \"${optionName}\" not found in tracking category \"${tc.Name}\". Valid options: ${valid}`,\n );\n }\n const known = cats.map((t) => t.Name).join(\", \");\n throw new Error(\n `Tracking category \"${categoryName}\" not found. Known categories: ${\n known || \"(none)\"\n }`,\n );\n}\n\nfunction normalizeTracking(\n list: any[],\n): { TrackingCategoryID: string; TrackingOptionID: string }[] {\n const out: any[] = [];\n for (const t of list ?? []) {\n if (t.TrackingCategoryID && t.TrackingOptionID) {\n out.push({\n TrackingCategoryID: t.TrackingCategoryID,\n TrackingOptionID: t.TrackingOptionID,\n });\n }\n }\n return out;\n}\n\nfunction describeTrackingIds(tracking: any[], trackingRef: any): string[] {\n return tracking.map((t) => {\n const catId = t.TrackingCategoryID ?? \"\";\n if (trackingRef && catId === trackingRef.TrackingCategoryID) {\n return `${trackingRef.Name}: ${trackingRef.Option}`;\n }\n return `[category ${String(catId).slice(0, 8)}…]`;\n });\n}\n\nexport function buildUpdatedLineItems(\n existing: any[],\n o: {\n accountCode?: string;\n trackingRef?: any;\n clearTrackingCategoryId?: string;\n targetLineItemId?: string;\n },\n): { newItems: any[]; changes: any[] } {\n const {\n accountCode,\n trackingRef,\n clearTrackingCategoryId,\n targetLineItemId,\n } = o;\n if (\n targetLineItemId !== undefined &&\n !existing.some((li) => li.LineItemID === targetLineItemId)\n ) {\n throw new Error(\n `Line item \"${targetLineItemId}\" is not part of this transaction.`,\n );\n }\n const newItems: any[] = [];\n const changes: any[] = [];\n for (const li of existing) {\n const newLi: any = {};\n for (const [k, v] of Object.entries(li)) {\n if (k !== \"Tracking\" && k !== \"ValidationErrors\") newLi[k] = v;\n }\n let tracking = normalizeTracking(li.Tracking);\n const change: any = {\n line_item_id: li.LineItemID,\n description: li.Description,\n };\n let touched = false;\n const targeted = targetLineItemId === undefined ||\n li.LineItemID === targetLineItemId;\n\n if (targeted) {\n if (\n accountCode !== undefined &&\n String(li.AccountCode) !== String(accountCode)\n ) {\n change.account_code = { from: li.AccountCode, to: accountCode };\n newLi.AccountCode = accountCode;\n touched = true;\n }\n if (clearTrackingCategoryId) {\n const before = tracking.length;\n tracking = tracking.filter((t) =>\n t.TrackingCategoryID !== clearTrackingCategoryId\n );\n if (tracking.length !== before) touched = true;\n }\n if (trackingRef) {\n const catId = trackingRef.TrackingCategoryID;\n const optId = trackingRef.TrackingOptionID;\n const filtered = tracking.filter((t) => t.TrackingCategoryID !== catId);\n filtered.push({ TrackingCategoryID: catId, TrackingOptionID: optId });\n if (JSON.stringify(filtered) !== JSON.stringify(tracking)) {\n touched = true;\n }\n tracking = filtered;\n }\n }\n\n if (touched && (trackingRef || clearTrackingCategoryId)) {\n change.tracking = {\n from: trackingDisplay(li.Tracking),\n to: describeTrackingIds(tracking, trackingRef),\n };\n }\n\n newLi.Tracking = tracking;\n newItems.push(newLi);\n if (touched) changes.push(change);\n }\n return { newItems, changes };\n}\n\nexport function buildUpdatePayload(txn: any, newItems: any[]): any {\n const c = txn.Contact ?? {};\n const b = txn.BankAccount ?? {};\n const p: any = {\n BankTransactionID: txn.BankTransactionID,\n Type: txn.Type,\n Contact: { ContactID: c.ContactID },\n BankAccount: { AccountID: b.AccountID },\n Date: parseXeroDate(txn.Date),\n LineAmountTypes: txn.LineAmountTypes ?? \"Exclusive\",\n LineItems: newItems,\n };\n if (txn.Reference) p.Reference = txn.Reference;\n return p;\n}\n\n// ----------------------------- tools ---------------------------------------\n\ninterface Tool {\n name: string;\n description: string;\n inputSchema: any;\n handler: (args: any) => Promise;\n}\n\nasync function updateTransactionCoding(a: any): Promise {\n const {\n bank_transaction_id,\n account_code,\n tracking_category,\n tracking_option,\n clear_tracking_category,\n target_line_item_id,\n } = a ?? {};\n const dryRun = a?.dry_run ?? true;\n\n if (!account_code && !tracking_category && !clear_tracking_category) {\n throw new Error(\n \"Nothing to do: provide account_code, and/or tracking_category + tracking_option, and/or clear_tracking_category.\",\n );\n }\n if (Boolean(tracking_category) !== Boolean(tracking_option)) {\n throw new Error(\n \"tracking_category and tracking_option must be given together.\",\n );\n }\n\n const txn = await getBankTransaction(bank_transaction_id);\n\n let trackingRef: any;\n let clearId: string | undefined;\n if (tracking_category) {\n const cats = await getTrackingCategories();\n trackingRef = resolveTrackingRef(cats, tracking_category, tracking_option);\n }\n if (clear_tracking_category) {\n const cats = await getTrackingCategories();\n const match = cats.find(\n (t: any) =>\n String(t.Name ?? \"\").trim().toLowerCase() ===\n clear_tracking_category.trim().toLowerCase(),\n );\n if (!match) {\n throw new Error(\n `Tracking category \"${clear_tracking_category}\" not found.`,\n );\n }\n clearId = match.TrackingCategoryID;\n }\n if (account_code) {\n validateAccountCode(await getAccounts(), account_code);\n }\n\n const { newItems, changes } = buildUpdatedLineItems(txn.LineItems ?? [], {\n accountCode: account_code,\n trackingRef,\n clearTrackingCategoryId: clearId,\n targetLineItemId: target_line_item_id,\n });\n\n const preview: any = {\n bank_transaction_id,\n contact: (txn.Contact ?? {}).Name,\n date: parseXeroDate(txn.Date),\n total: txn.Total,\n is_reconciled: txn.IsReconciled,\n changes,\n };\n\n if (!changes.length) {\n preview.applied = false;\n preview.message =\n \"No changes needed; the transaction already has these values.\";\n return preview;\n }\n if (dryRun) {\n preview.applied = false;\n preview.message =\n \"Preview only. Re-run with dry_run=false to apply after the user confirms.\";\n return preview;\n }\n\n const payload = buildUpdatePayload(txn, newItems);\n try {\n const updated = await updateBankTransaction(payload);\n preview.applied = true;\n preview.message = \"Transaction updated in Xero.\";\n preview.result = summarizeTransaction(updated, true);\n } catch (e) {\n preview.applied = false;\n preview.error = e instanceof Error ? e.message : String(e);\n }\n return preview;\n}\n\nconst TOOLS: Tool[] = [\n {\n name: \"get_connection_status\",\n description:\n \"Confirm the server can reach Xero and report the connected organisation (tenant name, account count, tracking category count). Use first to verify the connection.\",\n inputSchema: {\n type: \"object\",\n properties: {},\n additionalProperties: false,\n },\n handler: async () => {\n const t = await getToken();\n const accounts = await getAccounts();\n const tracking = await getTrackingCategories();\n return {\n connected: true,\n tenant_name: t.tenant_name,\n tenant_id: t.tenant_id,\n account_count: accounts.length,\n tracking_category_count: tracking.length,\n };\n },\n },\n {\n name: \"list_accounts\",\n description:\n \"List the chart of accounts (valid account codes). Use to find the account code before recoding.\",\n inputSchema: {\n type: \"object\",\n properties: {\n active_only: {\n type: \"boolean\",\n default: true,\n description: \"Omit archived/deleted accounts.\",\n },\n account_type: {\n type: \"string\",\n description:\n \"Optional Xero account type filter, e.g. EXPENSE, DIRECTCOSTS, OVERHEADS.\",\n },\n },\n additionalProperties: false,\n },\n handler: async (a) => {\n const activeOnly = a?.active_only ?? true;\n const type = a?.account_type;\n const accounts = await getAccounts();\n return accounts\n .filter((x: any) => {\n if (\n activeOnly && !(x.Status === undefined || x.Status === \"ACTIVE\")\n ) return false;\n if (\n type &&\n String(x.Type ?? \"\").toUpperCase() !== String(type).toUpperCase()\n ) {\n return false;\n }\n return true;\n })\n .map(summarizeAccount);\n },\n },\n {\n name: \"list_tracking_categories\",\n description:\n \"List Xero tracking categories and their options. Use to find the exact category and option names before tagging.\",\n inputSchema: {\n type: \"object\",\n properties: {},\n additionalProperties: false,\n },\n handler: async () =>\n (await getTrackingCategories()).map(summarizeTrackingCategory),\n },\n {\n name: \"list_bank_transactions\",\n description:\n \"List bank (spend/receive money) transactions, newest first, 100 per page. Narrow with a date range.\",\n inputSchema: {\n type: \"object\",\n properties: {\n from_date: {\n type: \"string\",\n description: \"Inclusive start date YYYY-MM-DD.\",\n },\n to_date: {\n type: \"string\",\n description: \"Inclusive end date YYYY-MM-DD.\",\n },\n contact_id: {\n type: \"string\",\n description: \"Filter to a contact's ContactID.\",\n },\n txn_type: {\n type: \"string\",\n enum: [\"SPEND\", \"RECEIVE\"],\n description: \"Transaction type.\",\n },\n where: {\n type: \"string\",\n description: \"Advanced raw Xero filter, combined with the above.\",\n },\n page: { type: \"integer\", minimum: 1, default: 1 },\n },\n additionalProperties: false,\n },\n handler: async (a) => {\n const where = buildWhere({\n fromDate: a?.from_date,\n toDate: a?.to_date,\n contactId: a?.contact_id,\n txnType: a?.txn_type,\n extra: a?.where,\n });\n const page = a?.page ?? 1;\n const txns = await getBankTransactions(where, \"Date DESC\", page);\n return {\n page,\n count: txns.length,\n transactions: txns.map((t: any) => summarizeTransaction(t)),\n };\n },\n },\n {\n name: \"get_bank_transaction\",\n description:\n \"Get one bank transaction in full, including each line item's LineItemID, account code, and current tracking.\",\n inputSchema: {\n type: \"object\",\n properties: { bank_transaction_id: { type: \"string\" } },\n required: [\"bank_transaction_id\"],\n additionalProperties: false,\n },\n handler: async (a) =>\n summarizeTransaction(\n await getBankTransaction(a.bank_transaction_id),\n true,\n ),\n },\n {\n name: \"update_transaction_coding\",\n description:\n \"Recode a bank transaction: change its account code and/or tracking. DEFAULTS TO A DRY RUN. Always call once with dry_run=true, show the user the preview, and only call with dry_run=false after they confirm. By default applies to every line; pass target_line_item_id to change one line. Untouched lines, amounts, and tax are preserved.\",\n inputSchema: {\n type: \"object\",\n properties: {\n bank_transaction_id: { type: \"string\" },\n account_code: {\n type: \"string\",\n description: \"New account code for the targeted line(s).\",\n },\n tracking_category: {\n type: \"string\",\n description:\n \"Name of a tracking category to set (e.g. 'Project'). Must be given with tracking_option.\",\n },\n tracking_option: {\n type: \"string\",\n description: \"The option within that category (e.g. a project name).\",\n },\n clear_tracking_category: {\n type: \"string\",\n description:\n \"Name of a tracking category to remove from the targeted line(s).\",\n },\n target_line_item_id: {\n type: \"string\",\n description: \"Restrict the edit to one line item.\",\n },\n dry_run: {\n type: \"boolean\",\n default: true,\n description: \"When true (default), return a preview without writing.\",\n },\n },\n required: [\"bank_transaction_id\"],\n additionalProperties: false,\n },\n handler: (a) => updateTransactionCoding(a),\n },\n];\n\n// ----------------------------- MCP JSON-RPC --------------------------------\n\nconst rpcResult = (id: any, result: any) => ({ jsonrpc: \"2.0\", id, result });\nconst rpcError = (id: any, code: number, message: string) => ({\n jsonrpc: \"2.0\",\n id,\n error: { code, message },\n});\n\nexport async function handleRpc(msg: any): Promise {\n const { id, method, params } = msg ?? {};\n\n if (method === \"initialize\") {\n return rpcResult(id, {\n protocolVersion: params?.protocolVersion || PROTOCOL_VERSION,\n capabilities: { tools: {} },\n serverInfo: SERVER_INFO,\n });\n }\n if (typeof method === \"string\" && method.startsWith(\"notifications/\")) {\n return null;\n }\n if (method === \"ping\") return rpcResult(id, {});\n if (method === \"tools/list\") {\n return rpcResult(id, {\n tools: TOOLS.map((t) => ({\n name: t.name,\n description: t.description,\n inputSchema: t.inputSchema,\n })),\n });\n }\n if (method === \"tools/call\") {\n const tool = TOOLS.find((t) => t.name === params?.name);\n if (!tool) {\n return rpcResult(id, {\n content: [{ type: \"text\", text: `Unknown tool: ${params?.name}` }],\n isError: true,\n });\n }\n try {\n const out = await tool.handler(params?.arguments ?? {});\n return rpcResult(id, {\n content: [{ type: \"text\", text: JSON.stringify(out, null, 2) }],\n });\n } catch (e) {\n return rpcResult(id, {\n content: [\n {\n type: \"text\",\n text: `Error: ${e instanceof Error ? e.message : String(e)}`,\n },\n ],\n isError: true,\n });\n }\n }\n if (id === undefined || id === null) return null;\n return rpcError(id, -32601, `Method not found: ${method}`);\n}\n\n// ----------------------------- HTTP + auth ---------------------------------\n\nfunction checkAuth(req: Request, url: URL): boolean {\n const expected = authToken();\n if (!expected) return false;\n const q = url.searchParams.get(\"token\") ?? \"\";\n const auth = req.headers.get(\"Authorization\") ?? \"\";\n const bearer = auth.toLowerCase().startsWith(\"bearer \")\n ? auth.slice(7).trim()\n : \"\";\n return q === expected || bearer === expected;\n}\n\nconst jsonResponse = (obj: any, status = 200) =>\n new Response(JSON.stringify(obj), {\n status,\n headers: { \"Content-Type\": \"application/json\" },\n });\n\nconst escapeHtml = (s: string) =>\n String(s).replace(\n /[&<>\"']/g,\n (c) =>\n ({ \"&\": \"&\", \"<\": \"<\", \">\": \">\", '\"': \""\", \"'\": \"'\" })[\n c\n ]!,\n );\n\nconst htmlResponse = (body: string, status = 200) =>\n new Response(\n `${body}`,\n { status, headers: { \"Content-Type\": \"text/html; charset=utf-8\" } },\n );\n\nfunction handleHealth(): Response {\n const configured =\n !!(env(\"XERO_CLIENT_ID\") && env(\"XERO_CLIENT_SECRET\") && authToken());\n return htmlResponse(\n `

Xero MCP server (custom connection)

Status: ${\n configured ? \"configured\" : \"missing environment variables\"\n }.

No redirect URI needed — this uses a Xero custom connection (client credentials).

Verify the Xero link: /check?token=YOUR_TOKEN

MCP endpoint: POST to this URL with ?token=YOUR_TOKEN.

`,\n );\n}\n\nasync function handleCheck(req: Request, url: URL): Promise {\n if (!checkAuth(req, url)) {\n return new Response(\"Unauthorized\", { status: 401 });\n }\n try {\n const t = await getToken(true);\n const accounts = await getAccounts();\n return htmlResponse(\n `

Connected to Xero.

Organisation: ${escapeHtml(t.tenant_name || t.tenant_id)}

${accounts.length} accounts visible. You're ready to add the connector in Claude.

`,\n );\n } catch (e) {\n return htmlResponse(\n `

Not connected.

${\n        escapeHtml(e instanceof Error ? e.message : String(e))\n      }

`,\n 400,\n );\n }\n}\n\nexport default async function (req: Request): Promise {\n const url = new URL(req.url);\n try {\n if (req.method === \"GET\") {\n if (url.pathname === \"/check\") return await handleCheck(req, url);\n if (url.pathname === \"/\") return handleHealth();\n return new Response(\"Not found\", { status: 404 });\n }\n if (req.method === \"POST\") {\n if (!checkAuth(req, url)) {\n return jsonResponse(rpcError(null, -32001, \"Unauthorized\"), 401);\n }\n let payload: any;\n try {\n payload = await req.json();\n } catch {\n return jsonResponse(rpcError(null, -32700, \"Parse error\"), 400);\n }\n if (Array.isArray(payload)) {\n const results: any[] = [];\n for (const m of payload) {\n const r = await handleRpc(m);\n if (r) results.push(r);\n }\n return results.length\n ? jsonResponse(results)\n : new Response(null, { status: 202 });\n }\n const r = await handleRpc(payload);\n return r === null ? new Response(null, { status: 202 }) : jsonResponse(r);\n }\n return new Response(\"Method Not Allowed\", { status: 405 });\n } catch (e) {\n return jsonResponse(\n rpcError(null, -32603, e instanceof Error ? e.message : String(e)),\n 500,\n );\n }\n}","// Xero MCP server for Val Town (Deno / TypeScript) — Custom Connection edition\n//\n// A remote MCP server (Streamable HTTP transport) that reads and recodes Xero\n// bank transactions: change the account code and set/clear a tracking category\n// on a transaction's line items.\n//\n// Auth to Xero uses a Xero CUSTOM CONNECTION (OAuth2 client_credentials grant):\n// no redirect URI, no callback, no consent screen. The server exchanges the\n// client id + secret for a short-lived access token directly.\n//\n// Single-file HTTP val. See README-valtown.md for setup.\n//\n// Routes:\n// GET / -> health / status page\n// GET /check?token= -> mint a token and confirm the Xero connection\n// POST / (any path) -> MCP JSON-RPC endpoint (token-protected)\n\nimport { blob } from \"https://esm.town/v/std/blob\";\n\n// ----------------------------- config --------------------------------------\n\nconst TOKEN_URL = \"https://identity.xero.com/connect/token\";\nconst CONNECTIONS_URL = \"https://api.xero.com/connections\";\nconst API_BASE = \"https://api.xero.com/api.xro/2.0\";\nconst TOKEN_SKEW_MS = 120_000;\nconst BLOB_TOKEN_KEY = \"xero_mcp_cc_token\";\n// Custom connections do not use offline_access (no refresh token).\n// Granular scopes: banktransactions (read+write) covers recoding; settings.read\n// covers reading the chart of accounts and tracking categories.\nconst DEFAULT_SCOPES =\n \"accounting.banktransactions accounting.settings.read projects\";\nconst PROTOCOL_VERSION = \"2025-06-18\";\nconst SERVER_INFO = { name: \"xero-mcp\", version: \"0.2.0\" };\n\nfunction env(name: string): string | undefined {\n return Deno.env.get(name)?.trim() || undefined;\n}\nfunction requireEnv(name: string): string {\n const v = env(name);\n if (!v) throw new Error(`Missing required environment variable ${name}`);\n return v;\n}\nconst clientId = () => requireEnv(\"XERO_CLIENT_ID\");\nconst clientSecret = () => requireEnv(\"XERO_CLIENT_SECRET\");\nconst scopes = () => env(\"XERO_SCOPES\") || DEFAULT_SCOPES;\nconst authToken = () => env(\"MCP_AUTH_TOKEN\");\n\n// ----------------------------- token (client credentials) ------------------\n\ninterface CachedToken {\n access_token: string;\n expires_at: number; // epoch ms\n tenant_id: string;\n tenant_name: string;\n}\n\nexport async function saveCached(t: CachedToken): Promise {\n await blob.setJSON(BLOB_TOKEN_KEY, t);\n}\nasync function loadCached(): Promise {\n try {\n return ((await blob.getJSON(BLOB_TOKEN_KEY)) as CachedToken) ?? null;\n } catch {\n return null;\n }\n}\n\nfunction basicAuthHeader(): string {\n return \"Basic \" + btoa(`${clientId()}:${clientSecret()}`);\n}\n\nasync function mintToken(): Promise {\n const resp = await fetch(TOKEN_URL, {\n method: \"POST\",\n headers: {\n Authorization: basicAuthHeader(),\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n },\n body: new URLSearchParams({\n grant_type: \"client_credentials\",\n scope: scopes(),\n }),\n });\n if (!resp.ok) {\n const t = await resp.text();\n throw new Error(\n `Failed to get Xero token (${resp.status}). Check the client id/secret and ` +\n `that the custom connection is active with the right scopes. ${\n t.slice(0, 300)\n }`,\n );\n }\n const data = await resp.json();\n const access: string = data.access_token;\n\n // Resolve the single connected organisation (custom connection = one org).\n let tenant_id = env(\"XERO_TENANT_ID\") || \"\";\n let tenant_name = \"\";\n if (!tenant_id) {\n const cr = await fetch(CONNECTIONS_URL, {\n headers: {\n Authorization: `Bearer ${access}`,\n Accept: \"application/json\",\n },\n });\n const conns = cr.ok ? await cr.json() : [];\n const org = conns.find((c: any) => c.tenantType === \"ORGANISATION\") ??\n conns[0];\n if (!org) {\n throw new Error(\n \"Token obtained, but no organisation is connected to this custom connection. \" +\n \"Re-authorise the connection in the Xero developer portal.\",\n );\n }\n tenant_id = org.tenantId;\n tenant_name = org.tenantName ?? \"\";\n }\n\n const token: CachedToken = {\n access_token: access,\n expires_at: Date.now() + Number(data.expires_in ?? 1800) * 1000,\n tenant_id,\n tenant_name,\n };\n await saveCached(token);\n return token;\n}\n\nasync function getToken(force = false): Promise {\n if (!force) {\n const cached = await loadCached();\n if (\n cached && cached.tenant_id &&\n Date.now() < cached.expires_at - TOKEN_SKEW_MS\n ) {\n return cached;\n }\n }\n return await mintToken();\n}\n\n// ----------------------------- Xero API ------------------------------------\n\ninterface XeroReq {\n searchParams?: Record;\n body?: unknown;\n}\n\nasync function xeroFetch(\n method: string,\n path: string,\n opts: XeroReq = {},\n retried = false,\n): Promise {\n const t = await getToken();\n const u = new URL(path.startsWith(\"http\") ? path : `${API_BASE}${path}`);\n if (opts.searchParams) {\n for (const [k, v] of Object.entries(opts.searchParams)) {\n if (v !== undefined && v !== null && v !== \"\") {\n u.searchParams.set(k, String(v));\n }\n }\n }\n const headers: Record = {\n Authorization: `Bearer ${t.access_token}`,\n \"Xero-tenant-id\": t.tenant_id,\n Accept: \"application/json\",\n };\n if (opts.body !== undefined) headers[\"Content-Type\"] = \"application/json\";\n\n const resp = await fetch(u.toString(), {\n method,\n headers,\n body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,\n });\n\n if (resp.status === 401 && !retried) {\n await getToken(true); // force a fresh token and retry once\n return xeroFetch(method, path, opts, true);\n }\n if (resp.status === 429 && !retried) {\n const wait = Number(resp.headers.get(\"Retry-After\") ?? \"2\");\n await new Promise((r) => setTimeout(r, Math.min(wait, 30) * 1000));\n return xeroFetch(method, path, opts, true);\n }\n if (!resp.ok) {\n const text = await resp.text();\n throw new Error(\n `Xero API error ${resp.status} for ${method} ${path}: ${\n text.slice(0, 500)\n }`,\n );\n }\n if (resp.status === 204) return {};\n return await resp.json();\n}\n\nconst getAccounts = async () =>\n (await xeroFetch(\"GET\", \"/Accounts\")).Accounts ?? [];\nconst getTrackingCategories = async () =>\n (await xeroFetch(\"GET\", \"/TrackingCategories\")).TrackingCategories ?? [];\nconst getBankTransactions = async (where?: string, order?: string, page = 1) =>\n (await xeroFetch(\"GET\", \"/BankTransactions\", {\n searchParams: { where, order, page },\n }))\n .BankTransactions ?? [];\nasync function getBankTransaction(id: string) {\n const items =\n (await xeroFetch(\"GET\", `/BankTransactions/${id}`)).BankTransactions ?? [];\n if (!items.length) {\n throw new Error(`No bank transaction found with ID ${id}.`);\n }\n return items[0];\n}\nasync function updateBankTransaction(txn: any) {\n const data = await xeroFetch(\"POST\", \"/BankTransactions\", {\n body: { BankTransactions: [txn] },\n });\n const items = data.BankTransactions ?? [];\n if (!items.length) {\n throw new Error(\"Xero did not return the updated transaction.\");\n }\n return items[0];\n}\n\n// ----------------------------- operations (pure) ---------------------------\n\nconst MS_DATE = /\\/Date\$(-?\\d+)(?:[+-]\\d{4})?\$\\//;\n\nexport function parseXeroDate(v: unknown): string {\n if (v === null || v === undefined) return \"\";\n const s = String(v);\n const m = s.match(MS_DATE);\n if (m) return new Date(parseInt(m[1], 10)).toISOString().slice(0, 10);\n return s.slice(0, 10);\n}\n\nfunction isoToDateTimeCall(iso: string): string {\n const [y, m, d] = iso.split(\"-\");\n return `DateTime(${parseInt(y)}, ${parseInt(m)}, ${parseInt(d)})`;\n}\n\nexport function buildWhere(o: {\n fromDate?: string;\n toDate?: string;\n contactId?: string;\n txnType?: string;\n extra?: string;\n}): string | undefined {\n const c: string[] = [];\n if (o.fromDate) c.push(`Date >= ${isoToDateTimeCall(o.fromDate)}`);\n if (o.toDate) c.push(`Date <= ${isoToDateTimeCall(o.toDate)}`);\n if (o.contactId) c.push(`Contact.ContactID == Guid(\"${o.contactId}\")`);\n if (o.txnType) c.push(`Type == \"${o.txnType}\"`);\n if (o.extra) c.push(`(${o.extra})`);\n return c.length ? c.join(\" && \") : undefined;\n}\n\nexport const summarizeAccount = (a: any) => ({\n code: a.Code,\n name: a.Name,\n type: a.Type,\n class: a.Class,\n status: a.Status,\n tax_type: a.TaxType,\n description: a.Description,\n});\n\nexport const summarizeTrackingCategory = (tc: any) => ({\n tracking_category_id: tc.TrackingCategoryID,\n name: tc.Name,\n status: tc.Status,\n options: (tc.Options ?? []).map((o: any) => ({\n tracking_option_id: o.TrackingOptionID,\n name: o.Name,\n status: o.Status,\n })),\n});\n\nconst trackingDisplay = (list: any[]): string[] =>\n (list ?? []).map((t) => `${t.Name ?? \"?\"}: ${t.Option ?? \"?\"}`);\n\nexport const summarizeLineItem = (li: any) => ({\n line_item_id: li.LineItemID,\n description: li.Description,\n account_code: li.AccountCode,\n line_amount: li.LineAmount,\n tax_type: li.TaxType,\n tracking: trackingDisplay(li.Tracking),\n});\n\nexport function summarizeTransaction(txn: any, includeLines = false): any {\n const c = txn.Contact ?? {};\n const b = txn.BankAccount ?? {};\n const s: any = {\n bank_transaction_id: txn.BankTransactionID,\n type: txn.Type,\n date: parseXeroDate(txn.Date),\n contact: c.Name,\n reference: txn.Reference,\n total: txn.Total,\n status: txn.Status,\n is_reconciled: txn.IsReconciled,\n bank_account: b.Name,\n line_count: (txn.LineItems ?? []).length,\n };\n if (includeLines) s.line_items = (txn.LineItems ?? []).map(summarizeLineItem);\n return s;\n}\n\nexport function validateAccountCode(accounts: any[], code: string): any {\n const target = String(code).trim();\n for (const a of accounts) {\n if (String(a.Code ?? \"\").trim() === target) {\n if (a.Status && a.Status !== \"ACTIVE\") {\n throw new Error(\n `Account code ${target} (${a.Name}) is not ACTIVE (status: ${a.Status}).`,\n );\n }\n return a;\n }\n }\n const known = accounts\n .map((a) => a.Code)\n .filter(Boolean)\n .map(String)\n .sort()\n .slice(0, 40)\n .join(\", \");\n throw new Error(\n `Account code \"${target}\" was not found in the chart of accounts. Known codes include: ${known}`,\n );\n}\n\nexport function resolveTrackingRef(\n cats: any[],\n categoryName: string,\n optionName: string,\n): any {\n const cl = categoryName.trim().toLowerCase();\n for (const tc of cats) {\n if (String(tc.Name ?? \"\").trim().toLowerCase() !== cl) continue;\n for (const o of tc.Options ?? []) {\n if (\n String(o.Name ?? \"\").trim().toLowerCase() ===\n optionName.trim().toLowerCase()\n ) {\n return {\n TrackingCategoryID: tc.TrackingCategoryID,\n TrackingOptionID: o.TrackingOptionID,\n Name: tc.Name,\n Option: o.Name,\n };\n }\n }\n const valid = (tc.Options ?? [])\n .filter((o: any) => (o.Status ?? \"ACTIVE\") === \"ACTIVE\")\n .map((o: any) => o.Name)\n .join(\", \");\n throw new Error(\n `Option \"${optionName}\" not found in tracking category \"${tc.Name}\". Valid options: ${valid}`,\n );\n }\n const known = cats.map((t) => t.Name).join(\", \");\n throw new Error(\n `Tracking category \"${categoryName}\" not found. Known categories: ${\n known || \"(none)\"\n }`,\n );\n}\n\nfunction normalizeTracking(\n list: any[],\n): { TrackingCategoryID: string; TrackingOptionID: string }[] {\n const out: any[] = [];\n for (const t of list ?? []) {\n if (t.TrackingCategoryID && t.TrackingOptionID) {\n out.push({\n TrackingCategoryID: t.TrackingCategoryID,\n TrackingOptionID: t.TrackingOptionID,\n });\n }\n }\n return out;\n}\n\nfunction describeTrackingIds(tracking: any[], trackingRef: any): string[] {\n return tracking.map((t) => {\n const catId = t.TrackingCategoryID ?? \"\";\n if (trackingRef && catId === trackingRef.TrackingCategoryID) {\n return `${trackingRef.Name}: ${trackingRef.Option}`;\n }\n return `[category ${String(catId).slice(0, 8)}…]`;\n });\n}\n\nexport function buildUpdatedLineItems(\n existing: any[],\n o: {\n accountCode?: string;\n trackingRef?: any;\n clearTrackingCategoryId?: string;\n targetLineItemId?: string;\n },\n): { newItems: any[]; changes: any[] } {\n const {\n accountCode,\n trackingRef,\n clearTrackingCategoryId,\n targetLineItemId,\n } = o;\n if (\n targetLineItemId !== undefined &&\n !existing.some((li) => li.LineItemID === targetLineItemId)\n ) {\n throw new Error(\n `Line item \"${targetLineItemId}\" is not part of this transaction.`,\n );\n }\n const newItems: any[] = [];\n const changes: any[] = [];\n for (const li of existing) {\n const newLi: any = {};\n for (const [k, v] of Object.entries(li)) {\n if (k !== \"Tracking\" && k !== \"ValidationErrors\") newLi[k] = v;\n }\n let tracking = normalizeTracking(li.Tracking);\n const change: any = {\n line_item_id: li.LineItemID,\n description: li.Description,\n };\n let touched = false;\n const targeted = targetLineItemId === undefined ||\n li.LineItemID === targetLineItemId;\n\n if (targeted) {\n if (\n accountCode !== undefined &&\n String(li.AccountCode) !== String(accountCode)\n ) {\n change.account_code = { from: li.AccountCode, to: accountCode };\n newLi.AccountCode = accountCode;\n touched = true;\n }\n if (clearTrackingCategoryId) {\n const before = tracking.length;\n tracking = tracking.filter((t) =>\n t.TrackingCategoryID !== clearTrackingCategoryId\n );\n if (tracking.length !== before) touched = true;\n }\n if (trackingRef) {\n const catId = trackingRef.TrackingCategoryID;\n const optId = trackingRef.TrackingOptionID;\n const filtered = tracking.filter((t) => t.TrackingCategoryID !== catId);\n filtered.push({ TrackingCategoryID: catId, TrackingOptionID: optId });\n if (JSON.stringify(filtered) !== JSON.stringify(tracking)) {\n touched = true;\n }\n tracking = filtered;\n }\n }\n\n if (touched && (trackingRef || clearTrackingCategoryId)) {\n change.tracking = {\n from: trackingDisplay(li.Tracking),\n to: describeTrackingIds(tracking, trackingRef),\n };\n }\n\n newLi.Tracking = tracking;\n newItems.push(newLi);\n if (touched) changes.push(change);\n }\n return { newItems, changes };\n}\n\nexport function buildUpdatePayload(txn: any, newItems: any[]): any {\n const c = txn.Contact ?? {};\n const b = txn.BankAccount ?? {};\n const p: any = {\n BankTransactionID: txn.BankTransactionID,\n Type: txn.Type,\n Contact: { ContactID: c.ContactID },\n BankAccount: { AccountID: b.AccountID },\n Date: parseXeroDate(txn.Date),\n LineAmountTypes: txn.LineAmountTypes ?? \"Exclusive\",\n LineItems: newItems,\n };\n if (txn.Reference) p.Reference = txn.Reference;\n return p;\n}\n\n// ----------------------------- tools ---------------------------------------\n\ninterface Tool {\n name: string;\n description: string;\n inputSchema: any;\n handler: (args: any) => Promise;\n}\n\nasync function updateTransactionCoding(a: any): Promise {\n const {\n bank_transaction_id,\n account_code,\n tracking_category,\n tracking_option,\n clear_tracking_category,\n target_line_item_id,\n } = a ?? {};\n const dryRun = a?.dry_run ?? true;\n\n if (!account_code && !tracking_category && !clear_tracking_category) {\n throw new Error(\n \"Nothing to do: provide account_code, and/or tracking_category + tracking_option, and/or clear_tracking_category.\",\n );\n }\n if (Boolean(tracking_category) !== Boolean(tracking_option)) {\n throw new Error(\n \"tracking_category and tracking_option must be given together.\",\n );\n }\n\n const txn = await getBankTransaction(bank_transaction_id);\n\n let trackingRef: any;\n let clearId: string | undefined;\n if (tracking_category) {\n const cats = await getTrackingCategories();\n trackingRef = resolveTrackingRef(cats, tracking_category, tracking_option);\n }\n if (clear_tracking_category) {\n const cats = await getTrackingCategories();\n const match = cats.find(\n (t: any) =>\n String(t.Name ?? \"\").trim().toLowerCase() ===\n clear_tracking_category.trim().toLowerCase(),\n );\n if (!match) {\n throw new Error(\n `Tracking category \"${clear_tracking_category}\" not found.`,\n );\n }\n clearId = match.TrackingCategoryID;\n }\n if (account_code) {\n validateAccountCode(await getAccounts(), account_code);\n }\n\n const { newItems, changes } = buildUpdatedLineItems(txn.LineItems ?? [], {\n accountCode: account_code,\n trackingRef,\n clearTrackingCategoryId: clearId,\n targetLineItemId: target_line_item_id,\n });\n\n const preview: any = {\n bank_transaction_id,\n contact: (txn.Contact ?? {}).Name,\n date: parseXeroDate(txn.Date),\n total: txn.Total,\n is_reconciled: txn.IsReconciled,\n changes,\n };\n\n if (!changes.length) {\n preview.applied = false;\n preview.message =\n \"No changes needed; the transaction already has these values.\";\n return preview;\n }\n if (dryRun) {\n preview.applied = false;\n preview.message =\n \"Preview only. Re-run with dry_run=false to apply after the user confirms.\";\n return preview;\n }\n\n const payload = buildUpdatePayload(txn, newItems);\n try {\n const updated = await updateBankTransaction(payload);\n preview.applied = true;\n preview.message = \"Transaction updated in Xero.\";\n preview.result = summarizeTransaction(updated, true);\n } catch (e) {\n preview.applied = false;\n preview.error = e instanceof Error ? e.message : String(e);\n }\n return preview;\n}\n\nconst TOOLS: Tool[] = [\n {\n name: \"get_connection_status\",\n description:\n \"Confirm the server can reach Xero and report the connected organisation (tenant name, account count, tracking category count). Use first to verify the connection.\",\n inputSchema: {\n type: \"object\",\n properties: {},\n additionalProperties: false,\n },\n handler: async () => {\n const t = await getToken();\n const accounts = await getAccounts();\n const tracking = await getTrackingCategories();\n return {\n connected: true,\n tenant_name: t.tenant_name,\n tenant_id: t.tenant_id,\n account_count: accounts.length,\n tracking_category_count: tracking.length,\n };\n },\n },\n {\n name: \"list_accounts\",\n description:\n \"List the chart of accounts (valid account codes). Use to find the account code before recoding.\",\n inputSchema: {\n type: \"object\",\n properties: {\n active_only: {\n type: \"boolean\",\n default: true,\n description: \"Omit archived/deleted accounts.\",\n },\n account_type: {\n type: \"string\",\n description:\n \"Optional Xero account type filter, e.g. EXPENSE, DIRECTCOSTS, OVERHEADS.\",\n },\n },\n additionalProperties: false,\n },\n handler: async (a) => {\n const activeOnly = a?.active_only ?? true;\n const type = a?.account_type;\n const accounts = await getAccounts();\n return accounts\n .filter((x: any) => {\n if (\n activeOnly && !(x.Status === undefined || x.Status === \"ACTIVE\")\n ) return false;\n if (\n type &&\n String(x.Type ?? \"\").toUpperCase() !== String(type).toUpperCase()\n ) {\n return false;\n }\n return true;\n })\n .map(summarizeAccount);\n },\n },\n {\n name: \"list_tracking_categories\",\n description:\n \"List Xero tracking categories and their options. Use to find the exact category and option names before tagging.\",\n inputSchema: {\n type: \"object\",\n properties: {},\n additionalProperties: false,\n },\n handler: async () =>\n (await getTrackingCategories()).map(summarizeTrackingCategory),\n },\n {\n name: \"list_bank_transactions\",\n description:\n \"List bank (spend/receive money) transactions, newest first, 100 per page. Narrow with a date range.\",\n inputSchema: {\n type: \"object\",\n properties: {\n from_date: {\n type: \"string\",\n description: \"Inclusive start date YYYY-MM-DD.\",\n },\n to_date: {\n type: \"string\",\n description: \"Inclusive end date YYYY-MM-DD.\",\n },\n contact_id: {\n type: \"string\",\n description: \"Filter to a contact's ContactID.\",\n },\n txn_type: {\n type: \"string\",\n enum: [\"SPEND\", \"RECEIVE\"],\n description: \"Transaction type.\",\n },\n where: {\n type: \"string\",\n description: \"Advanced raw Xero filter, combined with the above.\",\n },\n page: { type: \"integer\", minimum: 1, default: 1 },\n },\n additionalProperties: false,\n },\n handler: async (a) => {\n const where = buildWhere({\n fromDate: a?.from_date,\n toDate: a?.to_date,\n contactId: a?.contact_id,\n txnType: a?.txn_type,\n extra: a?.where,\n });\n const page = a?.page ?? 1;\n const txns = await getBankTransactions(where, \"Date DESC\", page);\n return {\n page,\n count: txns.length,\n\n transactions: txns.map((t: any) => summarizeTransaction(t, true)),\n };\n },\n },\n {\n name: \"get_bank_transaction\",\n description:\n \"Get one bank transaction in full, including each line item's LineItemID, account code, and current tracking.\",\n inputSchema: {\n type: \"object\",\n properties: { bank_transaction_id: { type: \"string\" } },\n required: [\"bank_transaction_id\"],\n additionalProperties: false,\n },\n handler: async (a) =>\n summarizeTransaction(\n await getBankTransaction(a.bank_transaction_id),\n true,\n ),\n },\n {\n name: \"update_transaction_coding\",\n description:\n \"Recode a bank transaction: change its account code and/or tracking. DEFAULTS TO A DRY RUN. Always call once with dry_run=true, show the user the preview, and only call with dry_run=false after they confirm. By default applies to every line; pass target_line_item_id to change one line. Untouched lines, amounts, and tax are preserved.\",\n inputSchema: {\n type: \"object\",\n properties: {\n bank_transaction_id: { type: \"string\" },\n account_code: {\n type: \"string\",\n description: \"New account code for the targeted line(s).\",\n },\n tracking_category: {\n type: \"string\",\n description:\n \"Name of a tracking category to set (e.g. 'Project'). Must be given with tracking_option.\",\n },\n tracking_option: {\n type: \"string\",\n description: \"The option within that category (e.g. a project name).\",\n },\n clear_tracking_category: {\n type: \"string\",\n description:\n \"Name of a tracking category to remove from the targeted line(s).\",\n },\n target_line_item_id: {\n type: \"string\",\n description: \"Restrict the edit to one line item.\",\n },\n dry_run: {\n type: \"boolean\",\n default: true,\n description: \"When true (default), return a preview without writing.\",\n },\n },\n required: [\"bank_transaction_id\"],\n additionalProperties: false,\n },\n handler: (a) => updateTransactionCoding(a),\n },\n];\n\n// ----------------------------- MCP JSON-RPC --------------------------------\n\nconst rpcResult = (id: any, result: any) => ({ jsonrpc: \"2.0\", id, result });\nconst rpcError = (id: any, code: number, message: string) => ({\n jsonrpc: \"2.0\",\n id,\n error: { code, message },\n});\n\nexport async function handleRpc(msg: any): Promise {\n const { id, method, params } = msg ?? {};\n\n if (method === \"initialize\") {\n return rpcResult(id, {\n protocolVersion: params?.protocolVersion || PROTOCOL_VERSION,\n capabilities: { tools: {} },\n serverInfo: SERVER_INFO,\n });\n }\n if (typeof method === \"string\" && method.startsWith(\"notifications/\")) {\n return null;\n }\n if (method === \"ping\") return rpcResult(id, {});\n if (method === \"tools/list\") {\n return rpcResult(id, {\n tools: TOOLS.map((t) => ({\n name: t.name,\n description: t.description,\n inputSchema: t.inputSchema,\n })),\n });\n }\n if (method === \"tools/call\") {\n const tool = TOOLS.find((t) => t.name === params?.name);\n if (!tool) {\n return rpcResult(id, {\n content: [{ type: \"text\", text: `Unknown tool: ${params?.name}` }],\n isError: true,\n });\n }\n try {\n const out = await tool.handler(params?.arguments ?? {});\n return rpcResult(id, {\n content: [{ type: \"text\", text: JSON.stringify(out, null, 2) }],\n });\n } catch (e) {\n return rpcResult(id, {\n content: [\n {\n type: \"text\",\n text: `Error: ${e instanceof Error ? e.message : String(e)}`,\n },\n ],\n isError: true,\n });\n }\n }\n if (id === undefined || id === null) return null;\n return rpcError(id, -32601, `Method not found: ${method}`);\n}\n\n// ----------------------------- HTTP + auth ---------------------------------\n\nfunction checkAuth(req: Request, url: URL): boolean {\n const expected = authToken();\n if (!expected) return false;\n const q = url.searchParams.get(\"token\") ?? \"\";\n const auth = req.headers.get(\"Authorization\") ?? \"\";\n const bearer = auth.toLowerCase().startsWith(\"bearer \")\n ? auth.slice(7).trim()\n : \"\";\n return q === expected || bearer === expected;\n}\n\nconst jsonResponse = (obj: any, status = 200) =>\n new Response(JSON.stringify(obj), {\n status,\n headers: { \"Content-Type\": \"application/json\" },\n });\n\nconst escapeHtml = (s: string) =>\n String(s).replace(\n /[&<>\"']/g,\n (c) =>\n ({ \"&\": \"&\", \"<\": \"<\", \">\": \">\", '\"': \""\", \"'\": \"'\" })[\n c\n ]!,\n );\n\nconst htmlResponse = (body: string, status = 200) =>\n new Response(\n `${body}`,\n { status, headers: { \"Content-Type\": \"text/html; charset=utf-8\" } },\n );\n\nfunction handleHealth(): Response {\n const configured =\n !!(env(\"XERO_CLIENT_ID\") && env(\"XERO_CLIENT_SECRET\") && authToken());\n return htmlResponse(\n `

Diff · v13