Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(mcp-host): keep reporting a sheet's ignored fields when images move onto it

marcoteb8fe8f0d07cf6
diff --git a/mcp-host/src/workflow/__tests__/ignoredArguments.contract.test.ts b/mcp-host/src/workflow/__tests__/ignoredArguments.contract.test.ts
new file mode 100644
index 000000000..69b5982b4
--- /dev/null
+++ b/mcp-host/src/workflow/__tests__/ignoredArguments.contract.test.ts
@@ -0,0 +1,200 @@
+// Every generator reports each argument it does not read. The note is built
+// from getters on the undeclared arguments (schemaArguments.ts), so a reader
+// that copies or spreads an object would read them all and hide them; this
+// contract puts an undeclared key in every object the schema closes and
+// expects each one named.
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+import { INTERNAL_TOOLS } from '../internalTools'
+import { unknownArguments } from '../schemaArguments'
+
+type SchemaNode = {
+ type?: unknown
+ properties?: Record<string, SchemaNode>
+ items?: SchemaNode
+ anyOf?: SchemaNode[]
+ additionalProperties?: unknown
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function branchFor(node: SchemaNode | undefined, value: unknown): SchemaNode | undefined {
+ if (!node?.anyOf) return node
+ const type = Array.isArray(value) ? 'array' : isRecord(value) ? 'object' : undefined
+ return node.anyOf.find(branch => {
+ const t = branch.type
+ return type !== undefined && (Array.isArray(t) ? t.includes(type) : t === type)
+ })
+}
+
+/** `value` with an undeclared `unreadN` key added to every object its schema closes. */
+function withUndeclaredKeys(schema: SchemaNode, value: unknown): unknown {
+ let n = 0
+ const visit = (raw: SchemaNode | undefined, item: unknown): unknown => {
+ const node = branchFor(raw, item)
+ if (Array.isArray(item)) return item.map(entry => visit(node?.items, entry))
+ if (!isRecord(item)) return item
+ if (!node?.properties || node.additionalProperties !== undefined) return item
+ const out: Record<string, unknown> = {}
+ for (const [key, entry] of Object.entries(item)) out[key] = visit(node.properties[key], entry)
+ out[`unread${n++}`] = 1
+ return out
+ }
+ return visit(schema, value)
+}
+
+/** The note prepared() adds for `ignored`. */
+function note(ignored: string[]): string {
+ const listed = ignored.slice(0, 10).map(name => `'${name}'`)
+ if (ignored.length > 10) listed.push(`and ${ignored.length - 10} more`)
+ return `Ignored arguments this tool does not read: ${listed.join(', ')}.`
+}
+
+const CALLS: Array<[string, Record<string, unknown>]> = [
+ ['clerum__generate_markdown', { filename: 'i.md', content: '# T' }],
+ [
+ 'clerum__generate_pdf',
+ {
+ filename: 'i.pdf',
+ title: 'T',
+ body: 'x',
+ branding: { companyName: 'A' },
+ tables: [{ headers: ['a'], rows: [['1']] }],
+ },
+ ],
+ [
+ 'clerum__generate_docx',
+ {
+ filename: 'i.docx',
+ title: 'T',
+ body: 'x',
+ branding: { companyName: 'A' },
+ tables: [{ headers: ['a'], rows: [['1']] }],
+ },
+ ],
+ [
+ 'clerum__generate_xlsx',
+ {
+ filename: 'i.xlsx',
+ branding: { companyName: 'A' },
+ sheets: [
+ {
+ name: 'S',
+ rows: [
+ ['a', 'b'],
+ [1, 2],
+ ],
+ titleRow: { text: 'T' },
+ conditionalFormatting: [
+ { column: 'a', rules: [{ greaterThan: 0, fillColor: '#dcfce7' }] },
+ ],
+ },
+ { name: 'Two', rows: [['c'], [3]] },
+ ],
+ },
+ ],
+ [
+ 'clerum__generate_pptx',
+ {
+ filename: 'i.pptx',
+ branding: { companyName: 'A' },
+ slides: [
+ { layout: 'title-bullets', title: 'T', bullets: ['a'] },
+ {
+ layout: 'title-chart',
+ title: 'C',
+ chart: {
+ type: 'bar',
+ labels: ['a'],
+ datasets: [{ label: 'S', data: [{ label: 'a', value: 1 }] }],
+ },
+ },
+ { layout: 'kpis', title: 'K', kpis: [{ label: 'R', value: '1' }] },
+ { layout: 'title-table', title: 'Tb', table: { headers: ['a'], rows: [['1']] } },
+ ],
+ },
+ ],
+ [
+ 'clerum__generate_chart',
+ {
+ filename: 'i.png',
+ type: 'bar',
+ data: { labels: ['a', 'b'], datasets: [{ label: 'S', data: [{ label: 'a', value: 1 }, 2] }] },
+ },
+ ],
+ [
+ 'clerum__generate_chart',
+ {
+ filename: 's.png',
+ type: 'scatter',
+ data: { datasets: [{ label: 'S', data: [{ x: 1, y: 2 }] }] },
+ },
+ ],
+ [
+ 'clerum__generate_dashboard',
+ {
+ filename: 'i',
+ data: {
+ title: 'I',
+ kpis: [{ label: 'R', value: 1 }],
+ charts: [{ type: 'bar', labels: ['a'], datasets: [{ label: 'x', data: [1] }] }],
+ tables: [{ headers: ['a'], rows: [[1]] }],
+ },
+ },
+ ],
+]
+
+describe('every argument a generator does not read is named', () => {
+ let dir: string
+
+ beforeEach(() => {
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'clerum-ignored-args-'))
+ })
+
+ afterEach(() => {
+ fs.rmSync(dir, { recursive: true, force: true })
+ })
+
+ it.each(CALLS)('%s', async (name, args) => {
+ const tool = INTERNAL_TOOLS.find(t => t.name === name)!
+ const sent = withUndeclaredKeys(tool.parameters as SchemaNode, args) as Record<string, unknown>
+ const expected = unknownArguments(tool.parameters, sent)
+ // Witness: only the added keys are undeclared, and every nested object
+ // the schema closes got one (markdown has only the top level).
+ expect(expected.every(entry => /unread\d+$/.test(entry))).toBe(true)
+ expect(expected.some(entry => /[.[]/.test(entry))).toBe(name !== 'clerum__generate_markdown')
+
+ const result = await tool.execute(sent, dir)
+ expect(result.success, result.error).toBe(true)
+ expect(result.content).toContain(note(expected))
+ })
+
+ it('names the fields of the first sheet when top-level images are moved onto it', async () => {
+ // A 1x1 PNG in the output folder, named as the generators take images.
+ fs.writeFileSync(
+ path.join(dir, 'dot.png'),
+ Buffer.from(
+ 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+ 'base64'
+ )
+ )
+ const tool = INTERNAL_TOOLS.find(t => t.name === 'clerum__generate_xlsx')!
+ const sent = withUndeclaredKeys(tool.parameters as SchemaNode, {
+ filename: 'a.xlsx',
+ sheets: [{ name: 'S', rows: [['a'], [1]] }],
+ images: ['dot.png'],
+ }) as Record<string, unknown>
+ // Top-level images is not in the schema but is read, as an alias.
+ const expected = unknownArguments(tool.parameters, sent).filter(entry => entry !== 'images')
+ expect(expected).toContain('sheets[0].unread0')
+
+ const result = await tool.execute(sent, dir)
+ expect(result.success, result.error).toBe(true)
+ expect(result.content).toContain('placed on the first sheet')
+ expect(result.content).toContain(note(expected))
+ })
+})
diff --git a/mcp-host/src/workflow/xlsxWorkbook.ts b/mcp-host/src/workflow/xlsxWorkbook.ts
index 83a05328e..d0ef314c9 100644
--- a/mcp-host/src/workflow/xlsxWorkbook.ts
+++ b/mcp-host/src/workflow/xlsxWorkbook.ts
@@ -623,7 +623,19 @@ export async function buildXlsxWorkbook(
if (topLevelImagesPlaced(args)) {
const first = sheets[0] as Record<string, unknown>
const own = Array.isArray(first.images) ? first.images : []
- sheets = [{ ...first, images: [...own, ...(args.images as unknown[])] }, ...sheets.slice(1)]
+ // A copy of the sheet's property descriptors, not of its values: a spread
+ // would read every field, and a field read counts as used (prepared()).
+ const moved = Object.defineProperties({}, Object.getOwnPropertyDescriptors(first)) as Record<
+ string,
+ unknown
+ >
+ Object.defineProperty(moved, 'images', {
+ value: [...own, ...(args.images as unknown[])],
+ enumerable: true,
+ writable: true,
+ configurable: true,
+ })
+ sheets = [moved, ...sheets.slice(1)]
warnings.push(
'images belongs inside each sheet (sheets[i].images); the top-level images were placed on the first sheet.'
)