SPB Git

Repository Public Research preview

protocol.test.mjs 11.0 KB 167 lines javascript

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
Files main
Menu

Theme