[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_156":157,"_158":159},"routes/_app.x.$handle.$name",{"_96":95,"_32":45,"_105":86,"_27":53,"_13":14,"_106":-5,"_11":107,"_108":109,"_110":111,"_112":113,"_114":115,"_20":-5,"_116":-5,"_117":-5,"_118":25,"_119":120,"_121":58,"_122":-5,"_123":-5,"_124":125},"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",11,"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)\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// This is a single-file HTTP val. See README-valtown.md for setup.\n//\n// Routes:\n// GET / -> health / status page\n// GET /authorize -> begin Xero OAuth (token-protected)\n// GET /callback -> Xero OAuth redirect target\n// GET /select-tenant?id=... -> switch org for multi-org accounts (token-protected)\n// POST / (any path) -> MCP JSON-RPC endpoint (token-protected)\n\nimport { blob } from \"https://esm.town/v/std/blob/main.ts\";\n\n// ----------------------------- config --------------------------------------\n\nconst AUTHORIZE_URL = \"https://login.xero.com/identity/connect/authorize\";\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_TOKENS_KEY = \"xero_mcp_tokens\";\nconst BLOB_STATE_KEY = \"xero_mcp_oauth_state\";\nconst DEFAULT_SCOPES =\n \"offline_access accounting.transactions accounting.settings.read\";\nconst PROTOCOL_VERSION = \"2025-06-18\";\nconst SERVER_INFO = { name: \"xero-mcp\", version: \"0.1.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\");\nconst redirectUri = () => \"https://geimanetc-xero-mcp.val.run/callback\";\n\n// ----------------------------- tokens --------------------------------------\n\ninterface Tokens {\n access_token: string;\n refresh_token: string;\n expires_at: number; // epoch ms\n tenant_id: string;\n tenant_name: string;\n scope?: string;\n}\n\nexport async function loadTokens(): Promise {\n try {\n const t = await blob.getJSON(BLOB_TOKENS_KEY);\n return (t as Tokens) ?? null;\n } catch {\n return null;\n }\n}\nexport async function saveTokens(t: Tokens): Promise {\n await blob.setJSON(BLOB_TOKENS_KEY, t);\n}\n\nfunction basicAuthHeader(): string {\n return \"Basic \" + btoa(`${clientId()}:${clientSecret()}`);\n}\n\nasync function refreshTokens(current: Tokens): 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: \"refresh_token\",\n refresh_token: current.refresh_token,\n }),\n });\n if (!resp.ok) {\n const text = await resp.text();\n throw new Error(\n `Failed to refresh Xero token (${resp.status}). Re-authorize at /authorize. ${\n text.slice(0, 300)\n }`,\n );\n }\n const data = await resp.json();\n const next: Tokens = {\n access_token: data.access_token,\n refresh_token: data.refresh_token,\n expires_at: Date.now() + Number(data.expires_in ?? 1800) * 1000,\n tenant_id: current.tenant_id,\n tenant_name: current.tenant_name,\n scope: data.scope ?? current.scope,\n };\n await saveTokens(next);\n return next;\n}\n\nasync function ensureTokens(): Promise {\n const t = await loadTokens();\n if (!t) {\n throw new Error(\n \"Not authorized with Xero yet. Visit /authorize?token=YOUR_TOKEN once to connect.\",\n );\n }\n if (Date.now() >= t.expires_at - TOKEN_SKEW_MS) return await refreshTokens(t);\n return t;\n}\n\nconst tenantId = (t: Tokens) => env(\"XERO_TENANT_ID\") || t.tenant_id;\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 ensureTokens();\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\": tenantId(t),\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 refreshTokens(t);\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(\n (t) => 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 ensureTokens();\n const accounts = await getAccounts();\n const tracking = await getTrackingCategories();\n return {\n connected: true,\n tenant_name: t.tenant_name,\n tenant_id: tenantId(t),\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 ) {\n return false;\n }\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 + OAuth -------------------------\n\nfunction checkAuth(req: Request, url: URL): boolean {\n const expected = authToken();\n if (!expected) return false; // misconfigured -> deny\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\nasync function handleHealth(url: URL): Promise {\n const authorized = !!(await loadTokens());\n const redirect = redirectUri();\n return htmlResponse(\n `

Xero MCP server

Status: ${authorized ? \"authorized\" : \"not authorized\"}.

Register this exact redirect URI in your Xero app (Configuration → OAuth 2.0 redirect URIs):
\n ${escapeHtml(redirect)}

Then authorize once at /authorize?token=YOUR_TOKEN.

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

`,\n );\n}\n\nasync function handleAuthorize(req: Request, url: URL): Promise {\n if (!checkAuth(req, url)) {\n return new Response(\"Unauthorized\", { status: 401 });\n }\n const state = crypto.randomUUID();\n await blob.setJSON(BLOB_STATE_KEY, { state, ts: Date.now() });\n const p = new URLSearchParams({\n response_type: \"code\",\n client_id: clientId(),\n redirect_uri: redirectUri(),\n scope: scopes(),\n state,\n });\n return Response.redirect(`${AUTHORIZE_URL}?${p.toString()}`, 302);\n}\n\nasync function handleCallback(_req: Request, url: URL): Promise {\n const code = url.searchParams.get(\"code\");\n const state = url.searchParams.get(\"state\");\n const err = url.searchParams.get(\"error\");\n if (err) {\n return htmlResponse(\n `

Authorization failed

${escapeHtml(err)}

`,\n 400,\n );\n }\n\n let stored: any = null;\n try {\n stored = await blob.getJSON(BLOB_STATE_KEY);\n } catch { /* ignore */ }\n if (!code || !state || !stored || stored.state !== state) {\n return htmlResponse(\n \"

Invalid or expired authorization.

Start again at /authorize.

\",\n 400,\n );\n }\n try {\n await blob.delete(BLOB_STATE_KEY);\n } catch { /* ignore */ }\n\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: \"authorization_code\",\n code,\n redirect_uri: redirectUri(),\n }),\n });\n if (!resp.ok) {\n const t = await resp.text();\n return htmlResponse(\n `

Token exchange failed (${resp.status})

${\n        escapeHtml(t.slice(0, 500))\n      }

`,\n 400,\n );\n }\n const data = await resp.json();\n\n const connResp = await fetch(CONNECTIONS_URL, {\n headers: {\n Authorization: `Bearer ${data.access_token}`,\n Accept: \"application/json\",\n },\n });\n const connections = connResp.ok ? await connResp.json() : [];\n const orgs = connections.filter((c: any) => c.tenantType === \"ORGANISATION\");\n const chosen = orgs[0] ?? connections[0];\n if (!chosen) {\n return htmlResponse(\n \"

No Xero organisation connected to this app.

\",\n 400,\n );\n }\n\n await saveTokens({\n access_token: data.access_token,\n refresh_token: data.refresh_token,\n expires_at: Date.now() + Number(data.expires_in ?? 1800) * 1000,\n tenant_id: chosen.tenantId,\n tenant_name: chosen.tenantName ?? \"\",\n scope: data.scope,\n });\n\n let extra = \"\";\n if (orgs.length > 1) {\n const items = orgs\n .map((c: any) =>\n `

${escapeHtml(c.tenantName)} — ${\n escapeHtml(c.tenantId)\n }

`\n )\n .join(\"\");\n extra =\n `

Multiple organisations found; using ${\n escapeHtml(chosen.tenantName)\n }. ` +\n `To switch, open /select-tenant?token=YOUR_TOKEN&id=TENANT_ID:

${items}`;\n }\n return htmlResponse(\n `

Xero connected.

Organisation: ${\n escapeHtml(chosen.tenantName)\n }. You can close this tab.

${extra}`,\n );\n}\n\nasync function handleSelectTenant(req: Request, url: URL): Promise {\n if (!checkAuth(req, url)) {\n return new Response(\"Unauthorized\", { status: 401 });\n }\n const id = url.searchParams.get(\"id\");\n if (!id) return htmlResponse(\"

Missing id.

\", 400);\n const t = await ensureTokens();\n const connResp = await fetch(CONNECTIONS_URL, {\n headers: {\n Authorization: `Bearer ${t.access_token}`,\n Accept: \"application/json\",\n },\n });\n const connections = connResp.ok ? await connResp.json() : [];\n const match = connections.find((c: any) => c.tenantId === id);\n if (!match) {\n return htmlResponse(\n \"

That tenant id is not connected to this app.

\",\n 400,\n );\n }\n t.tenant_id = match.tenantId;\n t.tenant_name = match.tenantName ?? \"\";\n await saveTokens(t);\n return htmlResponse(\n `

Switched to ${escapeHtml(t.tenant_name)}.

`,\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 === \"/authorize\") return await handleAuthorize(req, url);\n if (url.pathname === \"/callback\") return await handleCallback(req, url);\n if (url.pathname === \"/select-tenant\") {\n return await handleSelectTenant(req, url);\n }\n if (url.pathname === \"/\") return await handleHealth(url);\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 = \"accounting.banktransactions accounting.settings.read\";\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({ grant_type: \"client_credentials\", scope: scopes() }),\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. ${t.slice(0, 300)}`,\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: { Authorization: `Bearer ${access}`, Accept: \"application/json\" },\n });\n const conns = cr.ok ? await cr.json() : [];\n const org = conns.find((c: any) => c.tenantType === \"ORGANISATION\") ?? 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 (cached && cached.tenant_id && Date.now() < cached.expires_at - TOKEN_SKEW_MS) {\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 !== \"\") u.searchParams.set(k, String(v));\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}: ${text.slice(0, 500)}`,\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\", { searchParams: { where, order, page } }))\n .BankTransactions ?? [];\nasync function getBankTransaction(id: string) {\n const items =\n (await xeroFetch(\"GET\", `/BankTransactions/${id}`)).BankTransactions ?? [];\n if (!items.length) throw new Error(`No bank transaction found with ID ${id}.`);\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) throw new Error(\"Xero did not return the updated transaction.\");\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 (String(o.Name ?? \"\").trim().toLowerCase() === optionName.trim().toLowerCase()) {\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: ${known || \"(none)\"}`,\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 { accountCode, trackingRef, clearTrackingCategoryId, targetLineItemId } = o;\n if (\n targetLineItemId !== undefined &&\n !existing.some((li) => li.LineItemID === targetLineItemId)\n ) {\n throw new Error(`Line item \"${targetLineItemId}\" is not part of this transaction.`);\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 = { line_item_id: li.LineItemID, description: li.Description };\n let touched = false;\n const targeted = targetLineItemId === undefined || li.LineItemID === targetLineItemId;\n\n if (targeted) {\n if (accountCode !== undefined && String(li.AccountCode) !== String(accountCode)) {\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) => t.TrackingCategoryID !== clearTrackingCategoryId);\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)) touched = true;\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(\"tracking_category and tracking_option must be given together.\");\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(`Tracking category \"${clear_tracking_category}\" not found.`);\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 = \"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: { type: \"object\", properties: {}, additionalProperties: false },\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 (activeOnly && !(x.Status === undefined || x.Status === \"ACTIVE\")) return false;\n if (type && String(x.Type ?? \"\").toUpperCase() !== String(type).toUpperCase()) {\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: { type: \"object\", properties: {}, additionalProperties: false },\n handler: async () => (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: { type: \"string\", description: \"Inclusive start date YYYY-MM-DD.\" },\n to_date: { type: \"string\", description: \"Inclusive end date YYYY-MM-DD.\" },\n contact_id: { type: \"string\", description: \"Filter to a contact's ContactID.\" },\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(await getBankTransaction(a.bank_transaction_id), true),\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: \"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/\")) return null;\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 { type: \"text\", text: `Error: ${e instanceof Error ? e.message : String(e)}` },\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 \") ? auth.slice(7).trim() : \"\";\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(/[&<>\"']/g, (c) =>\n ({ \"&\": \"&\", \"<\": \"<\", \">\": \">\", '\"': \""\", \"'\": \"'\" })[c]!,\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 = !!(env(\"XERO_CLIENT_ID\") && env(\"XERO_CLIENT_SECRET\") && authToken());\n return htmlResponse(\n `

Xero MCP server (custom connection)

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

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)) return new Response(\"Unauthorized\", { status: 401 });\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.

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

`,\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 ? jsonResponse(results) : 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(rpcError(null, -32603, e instanceof Error ? e.message : String(e)), 500);\n }\n}","createdAt",["D",1784314101280],"branchVersion","branchId","09b797b6-33c6-437d-a046-f4cb82f3054e","id","648f2694-962f-44ff-82b5-9f0daef3c693","xero-mcp",["D",1784247377015],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","","imageUrl","b0eca1f1-eb8b-4439-9e77-2e33cff232d5","pinnedFileId","pinPreview",true,"pinMigrated","screenshotVersion","likeCount",0,"orgId","019f6d6d-668f-7668-bade-51c428a6baeb","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_96":95,"_104":100},"org",{"_96":95,"_97":98,"_99":100,"_18":55,"_101":102,"_103":25},"branch",{"_13":85,"_32":86,"_43":42,"_87":44,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":45,"_94":95},"isOwned",13,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","geimanetc","handle","displayName","Connor Geiman","avatar","https://lh3.googleusercontent.com/a/ACg8ocJr69X2wgFGIcHE7Fpik8kWjYfNy_Yl_cccJrXF8kFKWY7-eQ=s96-c","tier","free","canRestrictVals","profileImageUrl","branchName","adoptOrgId",{"_43":44,"_32":45,"_38":152,"_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":153,"_80":154,"_82":155,"_84":25},"tree",[147],"files",[147],"counts",{"_135":62,"_136":137,"_138":62,"_139":140,"_141":142},"contents",[126],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_43":127,"_32":28,"_30":31,"_128":-5,"_41":42,"_40":14,"_129":25,"_38":130,"_13":131,"_33":34,"_35":37,"_24":25,"_132":133,"_27":134},"0d7f5afc-27bb-48ff-af0b-58bf7844d974","parentId","latest",["D",1784314101280],10,"label","geimanetc-xero-mcp",[28],"pulls","branches",1,"forks","envVars",{"_143":145,"_146":62},"connections",{"_143":62,"_144":62},"count","unfilledCount",4,"emptyCount",{"_43":127,"_32":28,"_30":31,"_128":-5,"_41":42,"_40":14,"_129":25,"_38":148,"_13":131,"_33":34,"_35":37,"_24":25,"_132":133,"_149":150,"_27":151},["D",1784314101280],"children",[],[28],["D",1784247377015],{"_96":95,"_104":100},{"_96":95,"_97":98,"_99":100,"_18":55,"_101":102,"_103":25},{"_13":85,"_32":86,"_43":42,"_87":44,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":45,"_94":95},"ctx",{"_78":-5,"_123":189,"_190":191,"_192":193,"_194":25,"_195":25,"_196":25,"_197":58,"_198":-5,"_199":-7,"_200":-7,"_201":62,"_202":25,"_203":25,"_204":-5,"_205":25,"_206":25,"_207":25,"_208":-5},"ENV",{"_160":161,"_162":163,"_164":86,"_165":166,"_167":168,"_169":170,"_171":172,"_173":174,"_175":176,"_177":178,"_179":180,"_181":182,"_183":184,"_185":186,"_187":188},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v11