Repository Public Research preview
1/**2 * =============================================================================3 * SP BOUCHER | SOFTWARE & RESEARCH4 * ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING5 * =============================================================================6 *7 * Project : LLM API toolkits8 * File : xlsx/mcp/test/protocol.test.mjs9 * Module : xlsx10 * Repository : https://git.spboucher.ai/llm-api-toolkits11 * Created : 2026-11-1012 * Last Modified : 2026-11-1013 *14 * Author : Simon-Pierre Boucher15 * Position : Professor of Finance16 * Institution : Université du Québec en Outaouais (UQO)17 * Organization : SP Boucher18 * Website : https://spboucher.ai19 * Git : https://git.spboucher.ai20 *21 * Preferred Contact: dev@spboucher.ai22 * Development : dev@spboucher.ai23 * Support : support@spboucher.ai24 * Security/Admin : admin@spboucher.ai25 *26 * Copyright (c) 202627 * Simon-Pierre Boucher28 * All rights reserved where applicable. This file is governed by the29 * applicable project license, copyright notices and relevant law.30 * Existing third-party rights and notices remain unaffected.31 *32 * License : None specified (no license file in this repository)33 *34 * Do not embed credentials, private keys, access tokens,35 * certificates or confidential personal information.36 *37 * =============================================================================38 * END OF SP BOUCHER SOURCE HEADER39 * =============================================================================40 */4142// The server as an MCP client sees it: official SDK client over stdio.43import assert from "node:assert/strict";44import { copyFileSync, existsSync, mkdtempSync, readFileSync, realpathSync, symlinkSync, writeFileSync } from "node:fs";45import { tmpdir } from "node:os";46import { dirname, join } from "node:path";47import { after, before, test } from "node:test";48import { fileURLToPath } from "node:url";49import { Client } from "@modelcontextprotocol/sdk/client/index.js";50import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";51import { VERSION } from "../server.mjs";52import { workbook, zip } from "./fixtures/xlsx-writer.mjs";5354const pkg = dirname(dirname(fileURLToPath(import.meta.url))), fx = join(pkg, "test", "fixtures");55const root = realpathSync(mkdtempSync(join(tmpdir(), "xlsx-audit-mcp-")));56for (const f of ["clean.xlsx", "defects.xlsx", "reference.xlsx", "submission.xlsx", "nocache.xlsx"]) copyFileSync(join(fx, f), join(root, f));57const outside = realpathSync(mkdtempSync(join(tmpdir(), "xlsx-audit-out-")));58copyFileSync(join(fx, "clean.xlsx"), join(outside, "secret.xlsx"));59symlinkSync(join(outside, "secret.xlsx"), join(root, "link.xlsx"));6061async function connect(serverPath = join(pkg, "server.mjs"), env = {}) {62 const transport = new StdioClientTransport({ command: process.execPath, args: [serverPath], env: { PATH: process.env.PATH, XLSX_AUDIT_ROOT: root, ...env }, stderr: "pipe" });63 const client = new Client({ name: "xlsx-audit-test", version: "1.0.0" });64 await client.connect(transport);65 return client;66}67let client;68before(async () => { client = await connect(); });69after(async () => { await client.close(); });70const call = async (name, args) => { const r = await client.callTool({ name, arguments: args }); return { ...r.structuredContent, isError: r.isError === true }; };7172const TOOLS = ["workbook_summary", "read_range", "list_formulas", "find_errors", "find_hardcoded", "formula_consistency", "find_circular", "trace_precedents", "trace_dependents", "check_controls", "recalc_check", "compare_workbooks", "grade_submission", "export_report"];7374test("the server announces itself and its fourteen tools, all annotated", async () => {75 assert.equal(client.getServerVersion().version, VERSION);76 assert.match(client.getInstructions(), /Excel is never started/);77 const { tools } = await client.listTools();78 assert.deepEqual(tools.map((t) => t.name), TOOLS);79 for (const t of tools) {80 assert.ok(t.description.length > 40, t.name);81 assert.ok(t.title, t.name);82 assert.equal(t.annotations.openWorldHint, false, t.name); // local files only, no network83 assert.equal(t.annotations.destructiveHint, false, t.name);84 assert.equal(t.annotations.readOnlyHint, !["grade_submission", "export_report"].includes(t.name), t.name);85 assert.equal(t.inputSchema.type, "object");86 }87 const manifest = JSON.parse(readFileSync(join(pkg, "agent-registry.json"), "utf8"));88 assert.deepEqual(manifest.mcp.tools.map((t) => t.name), TOOLS);89 assert.equal(manifest.version, VERSION);90 assert.equal(JSON.parse(readFileSync(join(pkg, "package.json"), "utf8")).version, VERSION);91});9293test("every audit tool answers over the protocol with exact findings", async () => {94 const s = await call("workbook_summary", { path: "defects.xlsx" });95 assert.deepEqual([s.totals.formulas, s.totals.error_cells, s.totals.circular_references], [60, 3, 1]);96 assert.match(s._notice, /not instructions/);97 assert.deepEqual((await call("find_errors", { path: "defects.xlsx" })).items.map((x) => x.ref), ["Outputs!B4", "Outputs!B6", "Outputs!B7"]);98 assert.deepEqual((await call("find_circular", { path: "defects.xlsx" })).items[0].loop, ["Calc!B9", "Calc!B10", "Calc!B9"]);99 assert.equal((await call("find_hardcoded", { path: "defects.xlsx" })).constants_where_a_formula_is_expected.items[0].ref, "Calc!D3");100 assert.equal((await call("formula_consistency", { path: "defects.xlsx" })).items[0].ref, "Calc!E4");101 assert.equal((await call("check_controls", { path: "defects.xlsx" })).failing_controls[0].ref, "Controls!E5");102 assert.equal((await call("recalc_check", { path: "clean.xlsx" })).verdict, "consistent_where_checked");103 assert.equal((await call("read_range", { path: "clean.xlsx", range: "Outputs!B1" })).cells[0].value, 552563.125);104 assert.equal((await call("list_formulas", { path: "clean.xlsx", sheet: "Outputs" })).formulas, 5);105 assert.equal((await call("trace_precedents", { path: "clean.xlsx", cell: "Outputs!B1" })).nodes[0].ref, "Calc!G3");106 assert.equal((await call("trace_dependents", { path: "clean.xlsx", cell: "Inputs!B6", depth: 1 })).count, 5);107 assert.deepEqual((await call("compare_workbooks", { reference: "reference.xlsx", submission: "submission.xlsx" })).counts, { right_by_formula: 21, right_but_typed_as_constant: 4, wrong: 31, missing: 1, unknown: 0 });108});109110test("grading over the protocol: inline rubric, rubric file, evidence file", async () => {111 const rubric = { items: [{ id: "units", range: "Calc!C2:F2", points: 4, formula_required: true }, { id: "costs", range: "Calc!B4:F4", points: 5 }, { id: "margin", range: "Calc!B5:F5", points: 4 }] };112 const g = await call("grade_submission", { reference: "reference.xlsx", submission: "submission.xlsx", rubric });113 assert.deepEqual([g.suggested_total, g.max_points], [6, 13]);114 assert.match(g.disclaimer, /human grader/);115 writeFileSync(join(root, "rubric.json"), JSON.stringify(rubric));116 const f = await call("grade_submission", { reference: "reference.xlsx", submission: "submission.xlsx", rubric_path: "rubric.json", output: "grade.md" });117 assert.equal(f.suggested_total, 6);118 assert.match(readFileSync(join(root, "grade.md"), "utf8"), /Suggested total: \*\*6 \/ 13\*\*/);119 const again = await call("grade_submission", { reference: "reference.xlsx", submission: "submission.xlsx", rubric, output: "grade.md" });120 assert.deepEqual([again.isError, again.error.code], [true, "exists"]);121 const bad = await call("grade_submission", { reference: "reference.xlsx", submission: "submission.xlsx", rubric: { items: [{ range: "B3", points: 1 }] } });122 assert.deepEqual([bad.isError, bad.error.code], [true, "rubric_invalid"]);123 const none = await call("grade_submission", { reference: "reference.xlsx", submission: "submission.xlsx" });124 assert.equal(none.error.code, "rubric_invalid");125});126127test("reports are written once, inside the root only", async () => {128 const r = await call("export_report", { path: "defects.xlsx", output: "report.md" });129 assert.equal(r.findings.errors, 3);130 assert.equal(r.written.path, join(root, "report.md"));131 assert.match(readFileSync(join(root, "report.md"), "utf8"), /^# Workbook audit: defects.xlsx/);132 assert.equal((await call("export_report", { path: "defects.xlsx", output: "report.md" })).error.code, "exists");133 assert.equal((await call("export_report", { path: "defects.xlsx", output: join(outside, "report.md") })).error.code, "outside_root");134 assert.ok(!existsSync(join(outside, "report.md")));135 const inline = await call("export_report", { path: "clean.xlsx", format: "json" });136 assert.equal(JSON.parse(inline.content).errors.error_cells, 0);137});138139test("hostile input comes back as a coded tool error, and the server stays up", async () => {140 writeFileSync(join(root, "garbage.xlsx"), "not a zip at all, sorry".repeat(4));141 writeFileSync(join(root, "traversal.xlsx"), workbook({ sheets: [{ name: "S", cells: { A1: 1 } }], extra: [{ name: "../../evil.xml", data: "<x/>" }] }));142 writeFileSync(join(root, "bomb.xlsx"), zip([{ name: "xl/workbook.xml", data: Buffer.alloc(140 * 1024 * 1024, 0x20), declaredSize: 64 }]));143 writeFileSync(join(root, "old.xls"), "x");144 const cases = [["garbage.xlsx", "not_a_zip"], ["traversal.xlsx", "zip_unsafe_name"], ["bomb.xlsx", "zip_limit"], ["old.xls", "unsupported_type"], ["missing.xlsx", "not_found"], ["link.xlsx", "outside_root"], [join(outside, "secret.xlsx"), "outside_root"], ["../" + outside.split("/").pop() + "/secret.xlsx", "outside_root"]];145 for (const [path, code] of cases) { const r = await call("workbook_summary", { path }); assert.deepEqual([r.isError, r.error.code], [true, code], path); }146 assert.ok(!existsSync(join(dirname(root), "evil.xml")) && !existsSync(join(root, "evil.xml")));147 assert.equal((await call("read_range", { path: "clean.xlsx", range: "Nope!A1" })).error.code, "sheet_not_found");148 assert.equal((await call("trace_precedents", { path: "clean.xlsx", cell: "Calc!A1:B2" })).error.code, "bad_range");149 assert.equal((await client.callTool({ name: "workbook_summary", arguments: {} })).isError, true); // schema violation is refused before the tool runs150 assert.equal((await call("workbook_summary", { path: "clean.xlsx" })).totals.formulas, 57); // still answering151});152153test("limits can be tightened by the operator", async () => {154 const strict = await connect(undefined, { XLSX_AUDIT_MAX_CELLS: "50", XLSX_AUDIT_MAX_FILE_MB: "1" });155 try {156 const r = await strict.callTool({ name: "workbook_summary", arguments: { path: "clean.xlsx" } });157 assert.deepEqual([r.isError, r.structuredContent.error.code], [true, "workbook_too_large"]);158 } finally { await strict.close(); }159});160161test("the server starts through a symlinked path", async () => {162 const dir = mkdtempSync(join(tmpdir(), "xlsx-audit-link-"));163 symlinkSync(pkg, join(dir, "pkg"));164 const c = await connect(join(dir, "pkg", "server.mjs"));165 try { assert.equal((await c.listTools()).tools.length, 14); assert.equal((await c.callTool({ name: "find_errors", arguments: { path: "clean.xlsx" } })).structuredContent.error_cells, 0); } finally { await c.close(); }166});167