{"_id":"@betteroffice/agents","_rev":"4-a08b9a4930f4ba8b46c31f50a49e3b1a","name":"@betteroffice/agents","dist-tags":{"latest":"0.3.0"},"versions":{"0.0.0-stage":{"name":"@betteroffice/agents","version":"0.0.0-stage","_id":"@betteroffice/agents@0.0.0-stage","stub":true,"maintainers":[{"name":"eliahilse","email":"elia@eliahilse.com"}],"dist":{"shasum":"925a5250553815a050a51ef0551a5ab519c786d6","tarball":"https://registry.npmjs.org/@betteroffice/agents/-/agents-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-d731z/iS/a14MCXjxQoUyPF7jK50LhXEH0dzehWavec4K3I+LTaQQTBItvGGhXBg8P6bZ0koPBys6oD5nBj9mA==","signatures":[{"sig":"MEUCIQD4oe/0zpyFUU/Hf4+Lrnc8g9Aul/Jks75JOaV/SxsKTQIgLWHvOs/WqcV4FjiC94HQWaxKsOObF5QcLNr6sGxvvu0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":342},"_npmUser":{"name":"eliahilse","email":"elia@eliahilse.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.0":{"name":"@betteroffice/agents","version":"0.1.0","license":"Apache-2.0","_id":"@betteroffice/agents@0.1.0","maintainers":[{"name":"eliahilse","email":"elia@eliahilse.com"}],"homepage":"https://github.com/openooxml/betteroffice#readme","bugs":{"url":"https://github.com/openooxml/betteroffice/issues"},"bin":{"betteroffice-mcp":"dist/cli.js"},"dist":{"shasum":"f73cd6461b6712b2bf16956ccbdcd88476031daa","tarball":"https://registry.npmjs.org/@betteroffice/agents/-/agents-0.1.0.tgz","fileCount":15,"integrity":"sha512-n3ENXZFQ8gjz0ukljaTnkQSzDjEMSx49auXXQmxISbI2VFLuubkMH53uQHGzRcLTi+mWf6sTXEN94KEG0yCacg==","signatures":[{"sig":"MEUCIG9mDZKkYQO+3cB0ohXUCY3WFCu1nj4TJucXtK8Agx7kAiEA37ybFJSp6j9U6pIUkH/kTB4iLrba2Z6XUQvJO3mvF6M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCUge2HHu2Ber7BdXaOYBFKXskhOfbHHE9gKEz4nZbFOwIgRYaF0Ihz7v5myROY+rMppHHGk4yAP/6iWOSRNha1UIs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":299257},"main":"./dist/index.js","type":"module","_from":"file:/Users/eliahilse/.claude/jobs/9a86fd2d/tmp/wt/agents-pack/.probe/out/betteroffice-agents-0.1.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./mcp":{"types":"./dist/mcp.d.ts","import":"./dist/mcp.js"},"./render":{"types":"./dist/render.d.ts","import":"./dist/render.js"}},"scripts":{"test":"bun test","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"eliahilse","email":"elia@eliahilse.com"},"_resolved":"/Users/eliahilse/.claude/jobs/9a86fd2d/tmp/wt/agents-pack/.probe/out/betteroffice-agents-0.1.0.tgz","_integrity":"sha512-n3ENXZFQ8gjz0ukljaTnkQSzDjEMSx49auXXQmxISbI2VFLuubkMH53uQHGzRcLTi+mWf6sTXEN94KEG0yCacg==","repository":{"url":"git+https://github.com/openooxml/betteroffice.git","type":"git","directory":"packages/agents"},"_npmVersion":"11.12.1","description":"Search, inspect, propose, preview, and export Office document edits through typed tools and MCP.","directories":{},"sideEffects":false,"_nodeVersion":"24.15.0","dependencies":{"zod":"^4.0.0","jszip":"3.10.1","image-size":"^2.0.2","@napi-rs/canvas":"^0.1.80","@betteroffice/docx":"^0.5.0","@betteroffice/pptx":"^0.3.0","@betteroffice/xlsx":"^0.4.0","@betteroffice/fonts":"^0.4.1","@modelcontextprotocol/sdk":"~1.32.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","@types/bun":"^1.3.14","typescript":"^6.0.3","@types/node":"^26.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agents_0.1.0_1792761214340_0.2677030174712809","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@betteroffice/agents","version":"0.2.0","keywords":["docx","xlsx","pptx","ooxml","office","mcp","agents","ai"],"author":{"name":"OpenOOXML"},"license":"Apache-2.0","_id":"@betteroffice/agents@0.2.0","maintainers":[{"name":"eliahilse","email":"elia@eliahilse.com"}],"homepage":"https://betteroffice.dev/","bugs":{"url":"https://github.com/openooxml/betteroffice/issues"},"bin":{"betteroffice-mcp":"dist/cli.js"},"dist":{"shasum":"75b5001e106a76f481f40a19bd8a7cc472ea7527","tarball":"https://registry.npmjs.org/@betteroffice/agents/-/agents-0.2.0.tgz","fileCount":16,"integrity":"sha512-0pJ2R/YUo2c4qkZtqwm7cyevwEy66Ok2sOH5EfldHR/H92twm4DyFCM9vBz461ZAycR/Nq1M5dnMapGZzNwOPQ==","signatures":[{"sig":"MEQCIGT6Grg++DYhSvJGjMW6ojHbZ3aPmL9Ven+42gfpEawpAiAnRhz7m6TrUTpIpkzTigUAMT/n1Jwsgtch0Z9ym6sjHg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIHDiDxusSoOB9Z+TJ7e1D/voNTlbvls4zk4SybWJ6eR3AiEAzJVzOksAtohZieBdqLZaPhlh2khyM0ALBTpnR9/Pw08=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@betteroffice%2fagents@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":356765},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./mcp":{"types":"./dist/mcp.d.ts","import":"./dist/mcp.js"},"./render":{"types":"./dist/render.d.ts","import":"./dist/render.js"}},"gitHead":"8639d649b72f0fa24b91d7c8c46e1fc9dfebcac6","scripts":{"test":"bun test","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"732bc031-77bf-4dc4-a1a8-6ce73a814ea0"}},"repository":{"url":"git+https://github.com/openooxml/betteroffice.git","type":"git","directory":"packages/agents"},"_npmVersion":"11.19.0","description":"Search, inspect, propose, preview, and export Office document edits through typed tools and MCP.","directories":{},"sideEffects":false,"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.6.6","jszip":"3.10.1","image-size":"^2.0.2","@napi-rs/canvas":"^0.1.80","@betteroffice/docx":"^0.5.0","@betteroffice/pptx":"^0.5.0","@betteroffice/xlsx":"^0.5.0","@betteroffice/fonts":"^0.4.1","@modelcontextprotocol/sdk":"~1.32.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","@types/bun":"^1.3.14","typescript":"^6.0.3","@types/node":"^26.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agents_0.2.0_1792976596019_0.12842402055921198","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"@betteroffice/agents@0.3.0","bin":{"betteroffice-mcp":"dist/cli.js"},"bugs":{"url":"https://github.com/openooxml/betteroffice/issues"},"dist":{"shasum":"fb86f22275e9f4c3c88134813abbb7c8aa2380b0","tarball":"https://registry.npmjs.org/@betteroffice/agents/-/agents-0.3.0.tgz","fileCount":16,"integrity":"sha512-WlYphtJgjbuWY/ACNMCkeEWVLDPTTRdWgB1KLXSfVYX7AwT8y94J3dEV5wNbAXFpYdzMR/TBrg5pXHQucn3AYA==","signatures":[{"sig":"MEYCIQCfIfORABWCQ1akRBnyZok8I2be/sHErMnx/ZjyYARj4AIhAKUPhVVynqbcE4L3ykIvXw8EgSkFEuZ2elj/sWNX/RhL","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDYKTVbmmP5zEzsu0v63CccSdI8dO/BYgSr8BV/WZC+CgIhAPix8KtnhZ6JpipwhgMIxO/ToEyo1txrcGawb9FgzJck"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@betteroffice%2fagents@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":366502},"main":"./dist/index.js","name":"@betteroffice/agents","type":"module","types":"./dist/index.d.ts","author":{"name":"OpenOOXML"},"engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./mcp":{"types":"./dist/mcp.d.ts","import":"./dist/mcp.js"},"./render":{"types":"./dist/render.d.ts","import":"./dist/render.js"}},"gitHead":"4e982c3aea0065578604c3fe7727938533888f66","license":"Apache-2.0","scripts":{"test":"bun test","build":"tsup","typecheck":"tsc --noEmit"},"version":"0.3.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"732bc031-77bf-4dc4-a1a8-6ce73a814ea0"}},"homepage":"https://betteroffice.dev/","keywords":["docx","xlsx","pptx","ooxml","office","mcp","agents","ai"],"repository":{"url":"git+https://github.com/openooxml/betteroffice.git","type":"git","directory":"packages/agents"},"_npmVersion":"11.19.0","description":"Search, inspect, propose, preview, and export Office document edits through typed tools and MCP.","directories":{},"maintainers":[{"name":"eliahilse","email":"elia@eliahilse.com"}],"sideEffects":false,"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.6.6","jszip":"3.10.1","image-size":"^2.0.2","@napi-rs/canvas":"^0.1.80","@betteroffice/docx":"^0.5.1","@betteroffice/pptx":"^0.5.1","@betteroffice/xlsx":"^0.5.1","@betteroffice/fonts":"^0.4.2","@modelcontextprotocol/sdk":"~1.32.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","@types/bun":"^1.3.14","typescript":"^6.0.3","@types/node":"^26.0.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agents_0.3.0_1793100482507_0.7911460552802709"}}},"time":{"created":"2026-10-23T13:11:57.595Z","modified":"2026-10-27T11:28:03.151Z","0.0.0-stage":"2026-10-23T13:11:57.595Z","0.1.0":"2026-10-23T13:13:34.517Z","0.2.0":"2026-10-26T01:03:16.113Z","0.3.0":"2026-10-27T11:28:02.630Z"},"bugs":{"url":"https://github.com/openooxml/betteroffice/issues"},"author":{"name":"OpenOOXML"},"license":"Apache-2.0","homepage":"https://betteroffice.dev/","keywords":["docx","xlsx","pptx","ooxml","office","mcp","agents","ai"],"repository":{"url":"git+https://github.com/openooxml/betteroffice.git","type":"git","directory":"packages/agents"},"description":"Search, inspect, propose, preview, and export Office document edits through typed tools and MCP.","maintainers":[{"name":"eliahilse","email":"elia@eliahilse.com"}],"readme":"# @betteroffice/agents\n\nSearch, read, edit and preview DOCX, XLSX and PPTX files from an agent, through a TypeScript SDK\nor the `betteroffice-mcp` server. Agents work on large files the way they work on source code:\ngrep, read a small region, make an exact edit, check the result, export.\n\nNo model provider, API key or agent framework is required.\n\n## Install\n\n```bash\nbun add @betteroffice/agents\n```\n\nRequires Node.js 22 or later.\n\n## Usage\n\n### MCP server\n\n```bash\nbunx --package @betteroffice/agents betteroffice-mcp --root /absolute/path/to/documents\n```\n\nThe server speaks MCP over stdin/stdout, so connect it from an MCP client. For example, with Codex:\n\n```bash\ncodex mcp add betteroffice -- /absolute/path/to/node_modules/.bin/betteroffice-mcp --root /absolute/path/to/documents\n```\n\n| flag | description |\n| --- | --- |\n| `--root <directory>` | Required. Every file path is resolved against it, including symlinks. |\n| `--read-only` | Exposes only the inspection tools: no proposals, edits, acceptance or export. |\n\nExports always write a new file and never overwrite an existing one. Path checks are not an\noperating-system sandbox, so use a workspace directory you control.\n\n### SDK\n\n```ts\nimport { readFile, writeFile } from 'node:fs/promises';\nimport { openDocx } from '@betteroffice/agents';\nimport { renderDocxPage } from '@betteroffice/agents/render';\n\nconst doc = await openDocx(await readFile('report.docx'), {\n  name: 'report.docx',\n  renderer: renderDocxPage,\n});\n\ntry {\n  const [hit] = doc.grep({ query: '€4.2 million' }).matches;\n  if (!hit) throw new Error('Revenue text not found');\n  const proposal = doc.propose({\n    author: 'report-agent',\n    note: 'Update the executive summary revenue',\n    edits: [{ match: hit.match, newText: '€5.1 million' }],\n  });\n\n  const preview = await doc.render(1, proposal.id);\n  await writeFile('preview.png', preview.png);\n  console.log(doc.review(proposal.id), await doc.verify(proposal.id));\n  await writeFile('report-revised.docx', await doc.export(proposal.id), { flag: 'wx' });\n} finally {\n  doc.close();\n}\n```\n\nExporting a pending proposal leaves the document unchanged. To apply it, call\n`await doc.accept(proposal.id)` and then `doc.export()` without an ID. For Word tracked changes,\ncall `doc.accept(id, { tracked: true, date: '2026-09-27T12:00:00Z' })`.\n\n## Entry points\n\n| export | description |\n| --- | --- |\n| `openDocx(bytes, { name?, renderer? })` | Opens a DOCX file in its own session. |\n| `attachDocx(session, options?)` | Wraps a live editor's `YrsSession`. Closing the adapter leaves the session open. |\n| `openXlsx(bytes, { name?, wasm? })` | Opens an XLSX workbook: cell reads and cell proposals. |\n| `attachXlsx(handle, options?)` | Wraps a live `WorkbookHandle`. |\n| `openPptx(bytes, { name?, wasm? })` | Opens a PPTX presentation: outline, slide reads, text proposals, atomic `edit` batches and `preview`. |\n| `attachPptx(handle, options?)` | Wraps a live `PresentationHandle`. |\n| `renderDocxPage` (from `@betteroffice/agents/render`) | Node canvas renderer for DOCX page previews. |\n| `renderPptxSlide` | Node canvas renderer for PPTX slide previews. |\n| `createOfficeMcpServer({ root, renderer?, readOnly? })` (from `@betteroffice/agents/mcp`) | The MCP server, for hosts that connect their own transport. |\n\nDOCX and PPTX documents stage text edits with `grep`, `read` and `propose`; workbooks use\n`readCells` and `proposeCells` instead. All adapters share `review`, `accept`, `reject`, `verify`,\n`export` and `close`. `openXlsx` and `openPptx` load the bundled WebAssembly in Node; in a\nbrowser, pass the module bytes as `wasm`. DOCX previews in a browser need a custom\n`DocumentRenderer` instead of the Node canvas renderer.\n\n## MCP tools\n\n| tool | purpose |\n| --- | --- |\n| `office_files` | List DOCX, XLSX and PPTX files, subdirectories and open document IDs. |\n| `office_open` | Open a file and return its document ID, format and capabilities. |\n| `office_outline` | Page through DOCX paragraphs, PPTX slide paragraphs or XLSX sheets. |\n| `office_grep` | Literal search with context; returns match IDs or cell handles. |\n| `office_read` | Read a paragraph or a cell field; DOCX reads include run formatting. |\n| `office_cells` | XLSX: read an A1 range with values, formulas and cell handles. |\n| `office_propose` | DOCX/PPTX: stage 1-32 text replacements as `{ match, newText }`. |\n| `office_propose_cells` | XLSX: stage 1-32 whole-cell inputs or formulas. |\n| `office_review` | List proposals or show one proposal's before/after changes. |\n| `office_accept` | Apply a proposal as one undo step; DOCX can keep it as tracked changes. |\n| `office_reject` | Discard a pending proposal. |\n| `office_render` | DOCX: PNG of a current or proposed page. |\n| `office_verify` | Save and reopen in memory; reports which checks ran. |\n| `office_export` | Write accepted edits or a pending proposal to a new file. |\n| `office_close` | Release an open document and its proposals. |\n| `docx_edit` | DOCX: atomic direct edits of paragraph styles, bold/italic/underline, paragraphs, table rows, cell merges, comments (add, reply, resolve or reopen) and page setup with `insert_section_break` and `set_section`; `runFormat: 'anchor'` copies the first plain run on insertion. |\n| `xlsx_outline`, `xlsx_read_range` | XLSX: sheets, used ranges, tables and defined names; range reads with a version. |\n| `xlsx_write_range`, `xlsx_format`, `xlsx_sort` | XLSX: versioned value and formula writes, formatting and sorting. |\n| `xlsx_list_defined_names`, `xlsx_edit_defined_names` | XLSX: list complete names with pagination; set or delete workbook and sheet scoped names atomically, including hidden flags. |\n| `xlsx_edit_grid`, `xlsx_edit_sheets` | XLSX: insert or delete rows and columns; add, rename, delete or move sheets. |\n| `xlsx_set_auto_filter` | XLSX: set, extend or remove a sheet's filter buttons; table filters are refused. |\n| `xlsx_list_charts`, `xlsx_read_chart_text`, `xlsx_edit_charts` | XLSX: inspect charts on worksheets and chartsheets and page through complete titles, names and references; replace or remove titles and edit series names, category refs and value refs atomically. |\n| `xlsx_list_conditional_formats`, `xlsx_read_conditional_format_formula`, `xlsx_edit_conditional_formats` | XLSX: list bounded rule previews and page through complete formulas; add or delete `cellIs` and `expression` rules with a differential format. |\n| `xlsx_find_replace`, `xlsx_preview` | XLSX: find and replace displayed text; PNG of a range. |\n| `pptx_outline`, `pptx_read_slide` | PPTX: slides, layouts and shapes; shape tree, paragraphs, runs and notes. `office_outline` with `story: 'comments'` lists discussions; `office_read` reads full comment text. |\n| `pptx_edit`, `pptx_preview` | PPTX: atomic text, slide, layout mapping, shape, image, notes, comment (`add_comment`, `reply_comment`, `resolve_comment`) and table structure edits (`insert_table_row`, `delete_table_row`, `insert_table_column`, `delete_table_column`); PNG of a slide. |\n\n## Edits and references\n\n- References (`ref`, `match`, `revision`, `version`) belong to the open session. Reopening a file\n  creates new ones. Page, slide and paragraph numbers are one-based; text offsets are zero-based.\n- DOCX and PPTX search is literal and case-insensitive by default. XLSX `office_grep` searches\n  displayed values case-sensitively.\n- A proposal holds 1-32 separate replacements and is validated on a temporary copy before one\n  atomic update. A changed target makes it stale (`STALE_TARGET`): read again and propose again.\n- New text takes the formatting of the first replaced character. To keep several styles in a\n  paragraph, replace the individual spans instead of the whole paragraph.\n- Paragraph breaks, inline embeds and existing tracked changes are protected from text proposals.\n- A committed XLSX or PPTX edit invalidates all outstanding handles, cursors and proposals for that\n  file.\n- Results are paginated (`nextCursor`, `nextOffset`, `nextStart`). A page of results is never an\n  exhaustive search.\n\n## Limits\n\n- Reads return at most 16,000 UTF-16 units and 100 formatting runs; lists return at most 100 items.\n- The MCP server opens at most 10 files of up to 64 MiB each and keeps at most 64 proposals per\n  document. All state is in memory: export before closing the client.\n- MCP messages over stdin are capped at 1 MiB.\n- `verify` confirms that the saved file reopens. It does not check visual fidelity or whether the\n  edit is semantically correct; use reads and previews for that.\n- Previews use the BetterOffice layout engine and bundled fonts and are not pixel-identical to\n  Office. Install `@betteroffice/fonts-cjk` for CJK glyphs.\n\n## Documentation\n\n- [Agents guide](https://docs.betteroffice.dev/docs/agents)\n- [`@betteroffice/docx`](https://www.npmjs.com/package/@betteroffice/docx)\n- [`@betteroffice/xlsx`](https://www.npmjs.com/package/@betteroffice/xlsx)\n- [`@betteroffice/pptx`](https://www.npmjs.com/package/@betteroffice/pptx)\n- [Format eval suite](https://github.com/openooxml/betteroffice/blob/main/eval/README.md)\n- [Repository](https://github.com/openooxml/betteroffice/tree/main/packages/agents)\n","readmeFilename":"README.md"}