graph-excel-mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # graph-excel-mcp
 
-MCP server for reading and editing Excel workbooks on SharePoint, OneDrive or Teams through Microsoft Graph, without a browser. It has no dependencies and needs Node 18 or later.
+MCP server for reading and editing Excel workbooks on SharePoint, OneDrive or Teams through Microsoft Graph, without a browser. It is written in TypeScript, has no runtime dependencies, and runs on Node 18 or later.
 
 It is built for workbooks that several people edit at once:
 
@@ -20,7 +20,9 @@ claude mcp add --scope user graph-excel -- npx -y graph-excel-mcp
 { "mcpServers": { "graph-excel": { "command": "npx", "args": ["-y", "graph-excel-mcp"] } } }
 ```
 
-**Claude Desktop extension / Claude plugin (Cowork):** clone the repo and run `npm run pack`. This builds `build/graph-excel-mcp-<version>.mcpb` and the `plugin/` folder. The plugin folder contains the server and a `graph-excel` skill.
+**Claude Desktop extension:** download `graph-excel-mcp-<version>.mcpb` from the [latest release](https://github.com/mickey-ichi/graph-excel-mcp/releases/latest) and open it.
+
+**Claude plugin (Cowork, Claude Code):** install the `plugin/` folder of this repo. It contains the server and a `graph-excel` skill.
 
 ## Sign in
 
@@ -48,6 +50,37 @@ Instead of pasting the SharePoint URL every time, you can add aliases to `~/.gra
 - Every call runs inside a workbook session. Sessionless calls on large workbooks can time out with a 504 even though the write was applied.
 - Line breaks are sent as `\n`, which Excel stores as `\r\n`. If you write `\r\n` directly, the cell ends up with a stray `_x000D_`.
 
+## Development
+
+Development needs Node 22.18 or later, which runs the `.ts` sources directly.
+
+| Command | What it does |
+|---|---|
+| `npm run mcp` / `npm run login` | Runs the server or the terminal sign-in from `src/` |
+| `npm run typecheck` | Runs `tsc` in strict mode with no emit |
+| `npm test` | Runs offline tests: range parsing, update composition, and the MCP handshake on `src/` and `dist/` |
+| `npm run build` | Compiles `src/` to `dist/`, which is what npm, the `.mcpb` and the plugin run |
+| `npm run pack` | Builds, then writes `build/*.mcpb` (gitignored) and `plugin/` (committed) |
+
+Layout:
+
+| Path | Contents |
+|---|---|
+| `src/graph.ts` | Auth and the Graph client |
+| `src/excel.ts` | Workbook operations |
+| `src/mcp.ts` | Tools and the JSON-RPC server |
+| `src/cli.ts` | Entry point |
+
+## Release
+
+Bump `version` in `package.json`, run `npm run pack`, commit, then push a matching tag:
+
+```bash
+git tag v0.3.1 && git push origin v0.3.1
+```
+
+The `Publish` workflow runs the tests, publishes to npm through trusted publishing (no token or OTP; provenance attached) and creates a GitHub release with the `.mcpb` attached.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Entry point: `graph-excel-mcp` serves MCP over stdio; `graph-excel-mcp login` signs in from a terminal.
+import { cliLogin } from "./graph.js";
+import { serve } from "./mcp.js";
+if (process.argv[2] === "login") {
+    cliLogin().catch((e) => {
+        console.error(e.message);
+        process.exit(1);
+    });
+}
+else {
+    serve();
+}

package/dist/excel.js

@@ -0,0 +1,372 @@
+// Excel-on-SharePoint operations with the guards shared test/spec workbooks need:
+// workbook sessions (sessionless calls on big files time out), base checks before writing,
+// read-back hash verification after writing, dry runs until send=true.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { HOME, graph, GraphError, resolveUrl, wb } from "./graph.js";
+export const SEP = "-----update-----";
+const BATCH_MAX = 20;
+const SESSION_IDLE_MS = 4 * 60 * 1000; // Graph drops idle persistent sessions after ~5 min
+// Workbook aliases: $GRAPH_EXCEL_HOME/workbooks.json (see workbooks.example.json).
+const ALIAS_FILES = [path.join(HOME, "workbooks.json")];
+// ---------- helpers ----------
+export const hash = (v) => crypto.createHash("sha256").update(String(v ?? "")).digest("hex").slice(0, 12);
+const normEol = (s) => String(s ?? "").replace(/\r\n/g, "\n");
+const preview = (v, n = 80) => {
+    const s = String(v ?? "").replace(/\r?\n/g, "⏎");
+    return s.length > n ? `${s.slice(0, n)}… (${s.length} chars)` : s;
+};
+const colNum = (letters) => [...letters].reduce((n, c) => n * 26 + c.charCodeAt(0) - 64, 0);
+const colName = (n) => {
+    let s = "";
+    for (; n > 0; n = Math.floor((n - 1) / 26))
+        s = String.fromCharCode(65 + ((n - 1) % 26)) + s;
+    return s;
+};
+const ADDR = /^([A-Z]{1,3})([1-9][0-9]{0,6})(?::([A-Z]{1,3})([1-9][0-9]{0,6}))?$/;
+export function parseRange(address) {
+    const a = String(address ?? "").trim().toUpperCase().replace(/\$/g, "");
+    const m = a.match(ADDR);
+    if (!m)
+        throw new Error(`Invalid range "${address}" (use one contiguous range like H60 or H60:J60)`);
+    const c1 = colNum(m[1]), r1 = Number(m[2]);
+    const c2 = m[3] ? colNum(m[3]) : c1, r2 = m[4] ? Number(m[4]) : r1;
+    if (c2 < c1 || r2 < r1)
+        throw new Error(`Invalid range "${address}" (top-left first)`);
+    return { address: a, c1, r1, rows: r2 - r1 + 1, cols: c2 - c1 + 1 };
+}
+const cellAddr = (rg, i, j) => `${colName(rg.c1 + j)}${rg.r1 + i}`;
+function to2d(values, rg, name) {
+    let grid;
+    if (!Array.isArray(values))
+        grid = [[values]];
+    else if (!Array.isArray(values[0]))
+        grid = rg.rows === 1 ? [values] : values.map((v) => [v]);
+    else
+        grid = values;
+    if (grid.length !== rg.rows || grid.some((r) => !Array.isArray(r) || r.length !== rg.cols))
+        throw new Error(`${name} for ${rg.address} must be ${rg.rows}×${rg.cols}`);
+    return grid;
+}
+function matches(current, expected) {
+    if (expected === null || expected === undefined)
+        return true;
+    const e = String(expected);
+    if (e.startsWith("sha256:")) {
+        const want = e.slice(7);
+        return want.length >= 8 && (hash(current).startsWith(want) || hash(normEol(current)).startsWith(want));
+    }
+    return String(current ?? "") === e || normEol(current) === normEol(e);
+}
+const items = new Map(); // file ref -> driveItem
+const sessions = new Map(); // workbook path -> session
+function aliases() {
+    const all = {};
+    for (const f of ALIAS_FILES) {
+        try {
+            Object.assign(all, JSON.parse(fs.readFileSync(f, "utf8")));
+        }
+        catch {
+            // no alias file
+        }
+    }
+    return all;
+}
+async function item(file) {
+    const ref = String(file ?? "").trim();
+    if (!ref)
+        throw new Error("Missing file (SharePoint URL, alias from ~/.graph-excel/workbooks.json, or driveId:itemId)");
+    const cached = items.get(ref);
+    if (cached)
+        return cached;
+    let it;
+    const alias = aliases()[ref];
+    if (alias)
+        it = { id: alias.itemId, name: alias.name, parentReference: { driveId: alias.driveId } };
+    else if (/^https:\/\//.test(ref))
+        it = await resolveUrl(ref);
+    else if (/^b![^:]+:[A-Z0-9]+$/.test(ref)) {
+        const [driveId, id] = ref.split(":");
+        it = { id, parentReference: { driveId } };
+    }
+    else
+        throw new Error(`Unknown workbook "${ref}" — pass the SharePoint URL or an alias: ${Object.keys(aliases()).join(", ") || "(none)"}`);
+    items.set(ref, it);
+    return it;
+}
+async function session(base, { fresh = false } = {}) {
+    const s = sessions.get(base);
+    if (!fresh && s && Date.now() - s.last < SESSION_IDLE_MS) {
+        s.last = Date.now();
+        return s.id;
+    }
+    const { id } = await graph("POST", `${base}/createSession`, { persistChanges: true }, { retries: 2 });
+    sessions.set(base, { id, last: Date.now() });
+    return id;
+}
+const sessionLost = (e) => e instanceof GraphError && /session/i.test(e.message) && [400, 404, 410].includes(e.status);
+// Workbook context: call(method, relUrl, body) and batch(requests) inside a session, re-opened once if it expired.
+async function open(file) {
+    const it = await item(file);
+    const base = wb(it);
+    const withSession = async (fn) => {
+        try {
+            return await fn(await session(base));
+        }
+        catch (e) {
+            if (!sessionLost(e))
+                throw e;
+            return fn(await session(base, { fresh: true }));
+        }
+    };
+    const sheetUrl = (sheet) => {
+        if (!sheet)
+            throw new Error("Missing sheet name");
+        return `${base}/worksheets('${encodeURIComponent(String(sheet).replace(/'/g, "''"))}')`;
+    };
+    const rangeUrl = (sheet, address) => `${sheetUrl(sheet)}/range(address='${address}')`;
+    const call = (method, url, body, opts = {}) => withSession((sid) => graph(method, url, body, { ...opts, session: sid }));
+    // requests -> responses in the same order. Retryable read failures are retried one by one; writes are never
+    // blindly retried here (callers verify by reading back).
+    async function batch(requests) {
+        const out = [];
+        for (let i = 0; i < requests.length; i += BATCH_MAX) {
+            const chunk = requests.slice(i, i + BATCH_MAX);
+            const res = await withSession((sid) => graph("POST", "/$batch", {
+                requests: chunk.map((r, k) => ({
+                    id: String(k + 1),
+                    method: r.method,
+                    url: r.url,
+                    headers: { "Content-Type": "application/json", "workbook-session-id": sid },
+                    ...(r.body === undefined ? {} : { body: r.body }),
+                })),
+            }, { retries: 1 }));
+            const byId = new Map(res.responses.map((r) => [r.id, r]));
+            for (let k = 0; k < chunk.length; k++) {
+                let r = byId.get(String(k + 1)) ?? { status: 500, body: { error: { message: "missing batch response" } } };
+                if (r.status >= 400 && chunk[k].method === "GET" && [429, 502, 503, 504].includes(r.status)) {
+                    try {
+                        r = { status: 200, body: await call("GET", chunk[k].url) };
+                    }
+                    catch (e) {
+                        r = { status: e instanceof GraphError ? e.status : 500, body: { error: { message: e.message } } };
+                    }
+                }
+                out.push(r);
+            }
+        }
+        return out;
+    }
+    const ok = (r, what) => {
+        if (r.status >= 400)
+            throw new Error(`${what}: ${r.status} ${JSON.stringify(r.body?.error ?? r.body).slice(0, 300)}`);
+        return r.body;
+    };
+    return { it, base, sheetUrl, rangeUrl, call, batch, ok };
+}
+async function readValues(wbx, sheet, ranges) {
+    const res = await wbx.batch(ranges.map((rg) => ({ method: "GET", url: `${wbx.rangeUrl(sheet, rg.address)}?$select=address,values` })));
+    return res.map((r, i) => wbx.ok(r, `read ${ranges[i].address}`).values);
+}
+async function readFills(wbx, sheet, addresses) {
+    const res = await wbx.batch(addresses.map((a) => ({ method: "GET", url: `${wbx.rangeUrl(sheet, a)}/format/fill` })));
+    return res.map((r, i) => wbx.ok(r, `read fill ${addresses[i]}`).color || null);
+}
+// ---------- operations ----------
+export async function resolve({ file }) {
+    const wbx = await open(file);
+    const full = await graph("GET", `/drives/${wbx.it.parentReference.driveId}/items/${wbx.it.id}?$select=name,webUrl,lastModifiedDateTime,lastModifiedBy`);
+    const ws = await wbx.call("GET", `${wbx.base}/worksheets?$select=name,position,visibility`);
+    const used = await wbx.batch(ws.value.map((w) => ({ method: "GET", url: `${wbx.sheetUrl(w.name)}/usedRange(valuesOnly=true)?$select=address` })));
+    return {
+        name: full.name,
+        driveId: wbx.it.parentReference.driveId,
+        itemId: wbx.it.id,
+        webUrl: full.webUrl,
+        lastModified: `${full.lastModifiedDateTime} by ${full.lastModifiedBy?.user?.displayName ?? "?"}`,
+        sheets: ws.value.map((w, i) => ({
+            position: w.position,
+            name: w.name,
+            ...(w.visibility !== "Visible" ? { visibility: w.visibility } : {}),
+            usedRange: used[i].status < 400 ? String(used[i].body.address).replace(/^.*!/, "") : null,
+        })),
+    };
+}
+export async function readRange({ file, sheet, range, fills = false, hashOnly = false }) {
+    const rg = parseRange(range);
+    const wbx = await open(file);
+    const [values] = await readValues(wbx, sheet, [rg]);
+    const cells = [];
+    values.forEach((row, i) => row.forEach((v, j) => cells.push({ address: cellAddr(rg, i, j), hash: `sha256:${hash(v)}`, ...(hashOnly ? { length: String(v).length } : { value: v }) })));
+    if (fills) {
+        if (cells.length > 400)
+            throw new Error("fills=true is limited to 400 cells per call");
+        const colors = await readFills(wbx, sheet, cells.map((c) => c.address));
+        cells.forEach((c, k) => (c.fill = colors[k]));
+    }
+    return { sheet, range: rg.address, cells };
+}
+// Each block is one contiguous range. A block whose current content does not match `expected` is skipped as a
+// conflict (never partially written).
+export async function writeValues({ file, sheet, writes, send = false }) {
+    if (!Array.isArray(writes) || !writes.length)
+        throw new Error("writes must be a non-empty array");
+    const plan = writes.map((w) => {
+        const rg = parseRange(w.range);
+        const values = to2d(w.values, rg, "values").map((row) => row.map((v) => (typeof v === "string" ? normEol(v) : v)));
+        return { rg, values, expected: w.expected === undefined ? null : to2d(w.expected, rg, "expected") };
+    });
+    const wbx = await open(file);
+    const current = await readValues(wbx, sheet, plan.map((p) => p.rg));
+    const report = plan.map((p, k) => {
+        const conflicts = [];
+        const changes = [];
+        p.values.forEach((row, i) => row.forEach((v, j) => {
+            const cur = current[k][i][j];
+            const addr = cellAddr(p.rg, i, j);
+            if (p.expected && !matches(cur, p.expected[i][j]))
+                conflicts.push({ address: addr, current: preview(cur), currentHash: `sha256:${hash(cur)}` });
+            if (String(cur ?? "") !== String(v ?? ""))
+                changes.push({ address: addr, from: preview(cur), to: preview(v) });
+        }));
+        return { range: p.rg.address, status: conflicts.length ? "conflict" : changes.length ? "will-write" : "unchanged", conflicts, changes };
+    });
+    if (!send)
+        return { dryRun: true, sheet, blocks: report, note: "Nothing written. Call again with send=true after the user approved." };
+    const todo = plan.map((p, k) => ({ p, r: report[k] })).filter(({ r }) => r.status === "will-write");
+    const res = await wbx.batch(todo.map(({ p }) => ({ method: "PATCH", url: wbx.rangeUrl(sheet, p.rg.address), body: { values: p.values } })));
+    // Read back everything (a 504 may still have applied the write), retry once what didn't land.
+    let after = await readValues(wbx, sheet, todo.map(({ p }) => p.rg));
+    const landed = (k) => todo[k].p.values.every((row, i) => row.every((v, j) => normEol(after[k][i][j]) === normEol(v)));
+    const retry = todo.map((_, k) => k).filter((k) => !landed(k) && res[k].status >= 500);
+    if (retry.length) {
+        await wbx.batch(retry.map((k) => ({ method: "PATCH", url: wbx.rangeUrl(sheet, todo[k].p.rg.address), body: { values: todo[k].p.values } })));
+        after = await readValues(wbx, sheet, todo.map(({ p }) => p.rg));
+    }
+    todo.forEach(({ p, r }, k) => {
+        const bad = [];
+        p.values.forEach((row, i) => row.forEach((v, j) => {
+            const got = after[k][i][j];
+            if (String(got) === String(v) || normEol(got) === normEol(v))
+                return;
+            bad.push({ address: cellAddr(p.rg, i, j), wanted: preview(v), got: preview(got) });
+        }));
+        r.status = bad.length ? "written-mismatch" : "written-verified";
+        if (bad.length)
+            r.mismatches = bad;
+        if (res[k].status >= 400 && !bad.length)
+            r.note = `request returned ${res[k].status} but the read-back matches`;
+        if (res[k].status >= 400 && bad.length)
+            r.error = JSON.stringify(res[k].body?.error ?? res[k].body).slice(0, 300);
+        r.hashes = after[k].flat().map((v) => `sha256:${hash(v)}`);
+    });
+    return { dryRun: false, sheet, blocks: report };
+}
+export function composeUpdate(cur, text, mode = "replace") {
+    const s = String(cur ?? "");
+    if (!s.trim())
+        throw new Error("cell is empty — there is no original part to keep; use write_values");
+    if (s.includes("\r\n"))
+        return composeUpdate(normEol(s), text, mode);
+    // Graph returns line breaks as \n and Excel stores a written \n as \r\n; a written \r\n would be stored
+    // with a stray _x000D_, so always compose with \n.
+    const eol = "\n";
+    const body = normEol(text).replace(/\s+$/, "");
+    const idx = s.indexOf(SEP);
+    if (idx < 0) {
+        const head = s.replace(/\s+$/, "") + eol + eol + SEP;
+        return { head, next: head + eol + body };
+    }
+    const head = s.slice(0, idx + SEP.length);
+    if (mode === "append") {
+        const old = s.slice(head.length).replace(/^\s+/, "").replace(/\s+$/, "");
+        return { head, next: head + eol + (old ? old + eol : "") + body };
+    }
+    return { head, next: head + eol + body };
+}
+export async function appendUpdate({ file, sheet, row, update, expected = {}, mode = "replace", fill = "#FFFF00", fillRange, send = false }) {
+    const r = Number(row);
+    if (!Number.isInteger(r) || r < 1)
+        throw new Error("row must be a positive integer");
+    const keys = Object.keys(update ?? {});
+    const cols = keys.map((c) => c.toUpperCase());
+    if (!cols.length || cols.some((c) => !/^[A-Z]{1,3}$/.test(c)))
+        throw new Error('update must map column letters to text, e.g. {"H": "..."}');
+    if (!["replace", "append"].includes(mode))
+        throw new Error('mode must be "replace" or "append"');
+    const wbx = await open(file);
+    const current = (await readValues(wbx, sheet, cols.map((c) => parseRange(`${c}${r}`)))).map((v) => v[0][0]);
+    const exp = Object.fromEntries(Object.entries(expected ?? {}).map(([k, v]) => [k.toUpperCase(), v]));
+    const cells = cols.map((c, k) => {
+        const cur = current[k];
+        const address = `${c}${r}`;
+        if (exp[c] !== undefined && !matches(cur, exp[c]))
+            return { address, status: "conflict", current: preview(cur), currentHash: `sha256:${hash(cur)}` };
+        const { head, next } = composeUpdate(cur, update[keys[k]], mode);
+        return { address, status: next === String(cur) ? "unchanged" : "will-write", head, next, cur };
+    });
+    const fr = parseRange(fillRange || `${colName(Math.min(...cols.map(colNum)))}${r}:${colName(Math.max(...cols.map(colNum)))}${r}`);
+    const shown = () => cells.map((c) => c.status === "conflict"
+        ? c
+        : { address: c.address, status: c.status, from: preview(c.cur, 60), updatePart: preview(c.next.slice(c.next.indexOf(SEP)), 300) });
+    if (!send) {
+        const [fillNow] = fill ? await readFills(wbx, sheet, [fr.address]) : [null];
+        return {
+            dryRun: true,
+            sheet,
+            row: r,
+            cells: shown(),
+            fill: fill ? { range: fr.address, from: fillNow, to: fill } : null,
+            note: "Nothing written. Call again with send=true after the user approved.",
+        };
+    }
+    if (cells.some((c) => c.status === "conflict"))
+        return { dryRun: false, written: false, sheet, row: r, cells: shown(), note: "Conflict: someone changed a cell since the base was read — nothing written." };
+    const planned = cells;
+    const todo = planned.filter((c) => c.status === "will-write");
+    const result = todo.length
+        ? await writeValues({ file, sheet, send: true, writes: todo.map((c) => ({ range: c.address, values: c.next, expected: c.cur === null ? null : String(c.cur) })) })
+        : { blocks: [] };
+    const after = (await readValues(wbx, sheet, planned.map((c) => parseRange(c.address)))).map((v) => v[0][0]);
+    const out = planned.map((c, k) => {
+        const block = result.blocks.find((b) => b.range === c.address);
+        return {
+            address: c.address,
+            status: block ? block.status : c.status,
+            originalKept: normEol(after[k]).startsWith(normEol(c.head)),
+            hash: `sha256:${hash(after[k])}`,
+            ...(block?.conflicts.length ? { conflicts: block.conflicts } : {}),
+            ...(block?.mismatches ? { mismatches: block.mismatches } : {}),
+        };
+    });
+    let fillResult = null;
+    if (fill && out.every((c) => c.originalKept && c.status !== "conflict")) {
+        fillResult = (await setFill({ file, sheet, ranges: [fr.address], color: fill, send: true })).ranges[0];
+    }
+    return { dryRun: false, sheet, row: r, cells: out, fill: fillResult };
+}
+/** color: "#FFFF00" etc., or null to clear the fill. */
+export async function setFill({ file, sheet, ranges, color = null, send = false }) {
+    if (!Array.isArray(ranges) || !ranges.length)
+        throw new Error("ranges must be a non-empty array of contiguous ranges");
+    const rgs = ranges.map(parseRange);
+    if (color !== null && !/^#[0-9A-Fa-f]{6}$/.test(String(color)))
+        throw new Error('color must be like "#FFFF00", or null to clear');
+    const want = color === null ? null : String(color).toUpperCase();
+    const wbx = await open(file);
+    const before = await readFills(wbx, sheet, rgs.map((r) => r.address));
+    const rows = rgs.map((r, k) => ({ range: r.address, from: before[k] ?? "(none or mixed)", to: want ?? "(cleared)" }));
+    if (!send)
+        return { dryRun: true, sheet, ranges: rows, note: "Nothing written. Call again with send=true after the user approved." };
+    await wbx.batch(rgs.map((r) => want === null
+        ? { method: "POST", url: `${wbx.rangeUrl(sheet, r.address)}/format/fill/clear`, body: {} }
+        : { method: "PATCH", url: `${wbx.rangeUrl(sheet, r.address)}/format/fill`, body: { color: want } }));
+    const after = await readFills(wbx, sheet, rgs.map((r) => r.address));
+    rows.forEach((row, k) => {
+        const got = after[k] ? after[k].toUpperCase() : null;
+        row.now = got ?? "(none)";
+        row.status = got === want ? "verified" : "mismatch";
+    });
+    return { dryRun: false, sheet, ranges: rows };
+}

package/dist/graph.js

@@ -0,0 +1,152 @@
+// Minimal Microsoft Graph client for editing SharePoint Excel files. Zero dependencies.
+// Auth: OAuth device code flow with the Microsoft Graph PowerShell public client; the refresh token is kept in
+// $GRAPH_EXCEL_HOME/token.json (default ~/.graph-excel, chmod 600) so it survives extension/plugin updates.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const CLIENT_ID = "14d82eec-204b-4c2f-b7e8-296a70dab67e"; // Microsoft Graph PowerShell
+const TENANT = "organizations";
+const SCOPE = "https://graph.microsoft.com/Files.ReadWrite.All offline_access openid profile";
+const AUTH = `https://login.microsoftonline.com/${TENANT}/oauth2/v2.0`;
+// Hosts such as Claude Desktop may pass an unfilled template ("${user_config.x}") or "" — treat as unset.
+const usable = (v) => (v && !v.startsWith("${") ? v : undefined);
+export const HOME = usable(process.env.GRAPH_EXCEL_HOME) ?? path.join(os.homedir(), ".graph-excel");
+const TOKEN_FILE = path.join(HOME, "token.json");
+function loadToken() {
+    try {
+        return JSON.parse(fs.readFileSync(TOKEN_FILE, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function saveToken(res, previous = {}) {
+    let account = previous.account;
+    if (res.id_token) {
+        try {
+            const claims = JSON.parse(Buffer.from(res.id_token.split(".")[1], "base64url").toString());
+            account = claims.preferred_username || claims.upn || account;
+        }
+        catch {
+            // keep the previous account name
+        }
+    }
+    const refresh_token = res.refresh_token ?? previous.refresh_token;
+    if (!refresh_token)
+        throw new Error("Microsoft did not return a refresh token");
+    const t = {
+        account,
+        access_token: res.access_token,
+        refresh_token,
+        expires_at: Date.now() + (Number(res.expires_in) - 120) * 1000,
+    };
+    fs.mkdirSync(HOME, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(TOKEN_FILE, JSON.stringify(t, null, 2), { mode: 0o600 });
+    fs.chmodSync(TOKEN_FILE, 0o600);
+    return t;
+}
+async function post(url, form) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(form),
+    });
+    return { ok: res.ok, body: await res.json().catch(() => ({})) };
+}
+async function refresh(t) {
+    const r = await post(`${AUTH}/token`, { client_id: CLIENT_ID, grant_type: "refresh_token", refresh_token: t.refresh_token, scope: SCOPE });
+    return r.ok ? saveToken(r.body, t) : null;
+}
+let refreshing = null;
+export async function silentToken() {
+    let t = loadToken();
+    if (!t?.refresh_token)
+        return null;
+    if (!t.access_token || Date.now() >= t.expires_at) {
+        const current = t;
+        refreshing ??= refresh(current).finally(() => (refreshing = null));
+        t = await refreshing;
+    }
+    return t && { token: t.access_token, account: t.account, expiresOn: new Date(t.expires_at).toISOString() };
+}
+export async function getToken() {
+    const t = await silentToken();
+    if (!t)
+        throw new Error("Not signed in to Microsoft Graph: call login_status (or run `graph-excel-mcp login`)");
+    return t.token;
+}
+// Starts a device code login. Resolves with the sign-in message right away; `done` settles when the user
+// finishes signing in (token saved) or the code expires.
+let pendingLogin = null;
+export async function startLogin() {
+    if (pendingLogin)
+        return pendingLogin;
+    const r = await post(`${AUTH}/devicecode`, { client_id: CLIENT_ID, scope: SCOPE });
+    if (!r.ok)
+        throw new Error(`Device code request failed: ${r.body.error_description || JSON.stringify(r.body)}`);
+    const { device_code, message, interval = 5, expires_in = 900 } = r.body;
+    const done = (async () => {
+        const deadline = Date.now() + expires_in * 1000;
+        let wait = interval * 1000;
+        while (Date.now() < deadline) {
+            await new Promise((s) => setTimeout(s, wait));
+            const p = await post(`${AUTH}/token`, { client_id: CLIENT_ID, grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code });
+            if (p.ok)
+                return saveToken(p.body);
+            if (p.body.error === "slow_down")
+                wait += 5000;
+            else if (p.body.error !== "authorization_pending")
+                throw new Error(p.body.error_description || p.body.error);
+        }
+        throw new Error("Device code expired before sign-in finished");
+    })().finally(() => (pendingLogin = null));
+    done.catch(() => { });
+    pendingLogin = { message, done };
+    return pendingLogin;
+}
+// Terminal sign-in (`graph-excel-mcp login`).
+export async function cliLogin() {
+    const t = await silentToken();
+    if (t)
+        return void console.log(`SIGNED_IN ${t.account}`);
+    const { message, done } = await startLogin();
+    console.log(message);
+    const saved = await done;
+    console.log(`SIGNED_IN ${saved.account}`);
+}
+const RETRYABLE = new Set([429, 502, 503, 504]);
+export class GraphError extends Error {
+    status;
+    constructor(method, url, status, text) {
+        super(`${method} ${url} -> ${status}: ${text.slice(0, 500)}`);
+        this.status = status;
+    }
+}
+export async function graph(method, url, body, { session, retries = method === "GET" ? 3 : 0 } = {}) {
+    const token = await getToken();
+    const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+    if (session)
+        headers["workbook-session-id"] = session;
+    for (let attempt = 0;; attempt++) {
+        const res = await fetch(url.startsWith("http") ? url : `https://graph.microsoft.com/v1.0${url}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        if (res.ok)
+            return text ? JSON.parse(text) : null;
+        if (attempt < retries && RETRYABLE.has(res.status)) {
+            const wait = Number(res.headers.get("retry-after")) * 1000 || 1000 * 2 ** attempt;
+            await new Promise((r) => setTimeout(r, wait));
+            continue;
+        }
+        throw new GraphError(method, url, res.status, text);
+    }
+}
+// Sharing / web URL -> driveItem (driveId + id)
+export async function resolveUrl(webUrl) {
+    const enc = "u!" + Buffer.from(webUrl).toString("base64").replace(/=+$/, "").replace(/\//g, "_").replace(/\+/g, "-");
+    return graph("GET", `/shares/${enc}/driveItem`);
+}
+export const wb = (item) => `/drives/${item.parentReference.driveId}/items/${item.id}/workbook`;