Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@docs-mcp read the first 5 paragraphs of report.docx"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
一个 MCP Server，让 AI 代理真正读懂和改写 Word（.docx） 与 PDF—— 而不是把二进制倒成一堆字节，也不是对着扫描件干瞪眼。
AI 代理处理文档时通常走两条烂路：要么把文件当纯文本读（丢掉段落结构、样式、表格、排版）， 要么用通用库重写整个文件（改一个字，页眉、图片、批注、嵌入字体全乱）。 碰到扫描版 PDF 更糟——文本抽取拿到 0 个字符，模型却不知道自己拿到的是一片空白。
docs-mcp 走第三条路，两种格式各用各的正确解法：
做法 | 结果 | |
| 在 OOXML 包内部做最小改写：只重写真正被改到的 | 「改完用 Word / WPS 打开格式不乱」是可测的字节级性质，不是承诺 |
先探测有没有真实文本层：有就按页抽取并重建段落；没有就是扫描件，明确拒绝文本读取，改用逐页渲染成图交给视觉模型 | 不再对着 405 页扫描件空跑一遍才发现取不到字 |
Related MCP server: LibreOffice MCP Tools
任何 MCP 客户端都可以直接拉起：
// Claude Code / Cursor / 其它 MCP 客户端
{
"mcpServers": {
"docs": {
"command": "npx",
"args": ["-y", "docs-mcp", "--root", "${workspaceFolder}"]
}
}
}从源码跑：
git clone <repo> && cd docs-mcp
npm install
node bin/docs-mcp.js --root /path/to/workspace选项 | 说明 |
| 相对路径的解析根（默认进程 cwd） |
| 把写入限制在该目录内，可重复。省略则不做额外限制 |
| 用法 / 版本 |
docx_read / docx_edit / docx_createdocx_read { path, mode?: "text" | "outline" | "tables", from?, to? }
docx_edit { path, output_path?, dry_run?, operations: [...] }
docx_create { path, title?, paragraphs: [...] }读取按 1 起下标返回段落，带样式 id 与「是否在表格内」，模型可以直接寻址；大文档自动分页
编辑支持 replace_text（跨格式 run 匹配，保留匹配起点的格式）/ replace_paragraph /
insert_paragraph_after / delete_paragraph / set_metadata
所有 index 指向 docx_read 报告的那份原始文档——多个操作一次性应用，前面的操作不会让后面的下标移位
dry_run: true 只报告会改什么，一个字节都不写
原地修改首次自动留一份 <名字>.orig.docx 一次性备份
写入走「同目录临时文件 + rename」原子落盘
pdf_info / pdf_outline / pdf_read / pdf_render_pagepdf_info { path, toc_limit? }
pdf_outline { path, from?, to?, max_depth? }
pdf_read { path, from?, to?, mode?: "paragraphs" | "lines", max_chars? }
pdf_render_page { path, page, scale?, region?, out_path? }先 pdf_info——它会告诉你这份 PDF 该用哪种读法，并给出目录页码：
3 page(s) — "Quarterly Report"
Text layer: yes
Table of contents (top level):
1 Overview
2 Key findings扫描件会被明确拒绝：pdf_read 直接报错并指出改用 pdf_render_page，
而不是返回一堆空白让模型猜
pdf_render_page 把整页或指定区域（按页面比例）渲染成 PNG，
以 MCP 一等公民的图片内容块直接进模型上下文
空白页会被检测出来：渲染管线最典型的静默失败是 wasm/字体路径没配对时 pdf.js 不报错、只是画出一张白纸——非白像素低于 0.05% 就明确报错
核心与宿主分离。 src/core/ 是纯文档库（ZIP、XML、OOXML 文档模型、PDF 解析与渲染），
不认识 MCP、也不认识任何宿主框架；src/tools/ 是宿主无关的工具实现；src/server.js
才把它们接到 MCP 协议上。同一份核心逻辑因此可以同时服务 MCP 客户端和别的宿主——不重复实现。
ZIP 容器与 XML 解析全部自研，零依赖。 用 node:zlib 的 crc32 / deflateRawSync /
inflateRawSync 手写。这不是炫技：通用 ZIP 库会重新压缩所有分片，而保真要求
未被修改的分片逐字节透传。PDF 侧则老实依赖 pdfjs-dist + @napi-rs/canvas——
解析 PDF 和光栅化是两件不该手写的事。
PDF 渲染用 MCP 原生图片块，不绕附件总线。 插件形态要把图经宿主的附件服务送进上下文， 还得先校验当前模型是否声明了 image 输入模态，并准备「附件不可用时降级落盘」的兜底。 MCP 协议本身就有一等公民的图片内容块，少一整层适配。
错误走 isError 而不是抛异常。 工具级失败返回 isError: true 加一句人能读懂的话，
让模型看到「为什么失败」并自行纠正；协议连接保持完好——
test/mcp-e2e.test.mjs 专门验证了「连续报错之后连接仍可用」。
--allow-write 是可选的，不是默认强制的。 它像普通本地 CLI 工具一样默认不设限，
但保留一个开关，让「只想让它改某个目录」成为一条命令行就能表达的事。
npm test265 项，五个套件分工：
套件 | 项数 | 覆盖 |
| 45 | OOXML 核心；含 |
| 61 | 三个 docx 工具、错误路径、字节级保真、写入围栏、路径解析、 |
| 73 | 四个 pdf 工具：文本层、分页与字符预算、大纲树提取（层级/页码/max_depth/分页）、扫描件识别与拒绝、渲染成图（PNG 魔数校验）、区域裁剪、空白页检测、围栏 |
| 59 | spawn 真实 stdio 子进程，用官方 SDK 的 |
| 27 | 真实文档验收：179KB 带图带表的 Word（改一个字后除 |
夹具测试完全自包含：PDF 夹具是手写的最小 PDF 1.4（test/fixtures.mjs），不依赖任何
外部样例文件或写库。夹具证明不了的那部分交给 realworld.mjs——手造的文档段落干净、
没有嵌入字体和图片，真实文件不是这样。协议测试不使用 in-memory transport 走捷径——
它要证明的正是「任何标准 MCP 客户端都能挂上」，那就必须真的过一遍 stdio。
src/core/ 的模块来自作者另外两个项目，逐字节复用：
zip.js / xml.js / document.js —— dsh-docx-tool 的 OOXML 核心
pdf.js —— dsh-pdf-tool 的 PDF 解析与渲染核心
那两份代码在同一套夹具上已有各自的回归测试。本仓库把它们从 「某个特定宿主的插件」提升为「任何 MCP 客户端可用的独立服务」， 并补上了协议层、围栏层与端到端测试。
MIT
Create a new Microsoft Word .docx document from plain text.
Each paragraph is either a string, or an object {text, style} where style is a Word style id such as Heading1, Heading2 or Title. The produced file is a valid OOXML package that opens in Word, WPS and LibreOffice.
Fails if the target path already exists — pick another path instead of overwriting by accident.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Where to create the new .docx. | |
| title | No | Document title (stored as document properties). | |
| paragraphs | Yes | Paragraphs in order. Either a plain string, or {text, style}. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring write/not-idempotent/not-destructive, the description adds material context beyond them: the fail-on-existing behavior, the input shape for paragraphs, and output format compatibility (OOXML, opens in Word/WPS/LibreOffice). This is meaningful extra transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs, front-loaded with the core action, then input shape, then the fail-safe. Every sentence earns its place with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers creation semantics, input format, output validity, and the key failure mode. No output schema exists, but the description appropriately explains that the result is a valid file rather than describing return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description restates the paragraph structure (string vs {text,style} with example styles) which mirrors schema but adds concrete style examples like Heading1/Title, offering marginal added value over baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new Microsoft Word .docx document from plain text') and distinguishes from siblings like docx_read and docx_edit, which are read/mutate tools rather than creators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Fails if the target path already exists — pick another path instead of overwriting by accident' gives concrete guidance on a misuse condition. It doesn't name a sibling alternative, but it clearly delineates a when-not condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply edits to a Microsoft Word .docx document and write the result back.
Call docx_read first to learn paragraph indices. All index values refer to the ORIGINAL
document as docx_read reported it — operations are applied together, so earlier operations
never shift the indices of later ones.
Operations:
{op:"replace_text", find, replace, all?} — replace text inside a paragraph, matching across
formatting runs so the surrounding formatting is preserved. Works on the whole document unless
you set all:false, in which case only the first occurrence is replaced. A match spanning a
tab or line break is refused; use replace_paragraph for those.
{op:"replace_paragraph", index, text} — replace one paragraph's whole text, keeping the formatting of its first run.
{op:"insert_paragraph_after", index, text, style?} — insert a new paragraph after the given
index; use index 0 to insert at the very start. style takes a style id such as Heading1.
{op:"delete_paragraph", index} — remove a paragraph (inside a table it becomes an empty one, because a table cell must keep at least one paragraph).
{op:"set_metadata", title?, subject?, creator?, keywords?, description?, lastModifiedBy?} — update the document properties.
By default the file is modified in place, and the first in-place edit leaves a one-time backup next to it as ".orig.docx". Pass output_path to write elsewhere instead, or dry_run:true to see what would change without writing anything.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the .docx to modify. | |
| dry_run | No | Report what would change without writing anything. | |
| operations | Yes | Edits to apply, in order. | |
| output_path | No | Write the result here instead of modifying path in place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds substantial behavioral context beyond that: in-place edits, a one-time .orig.docx backup, output_path redirection, dry_run behavior, and operation ordering semantics that keep indices tied to the original document.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but appropriately structured for a multi-operation editing tool, front-loading the purpose and prerequisite before listing operations and write-behavior details. Every section earns its place by clarifying either an operation, an index rule, or a file-write effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description still covers the essential invocation and side-effect details an agent needs: required path and operations, operation ordering, backup behavior, dry-run reporting, and alternate output destination. There is no obvious missing context that would cause misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline would be 3, but the description materially enriches parameter meaning. It explains each op's find/replace/all behavior, index semantics for paragraph operations, style id usage, and edge cases like table-cell paragraph deletion and refused matches across tabs or line breaks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: apply edits to a Microsoft Word .docx document and write the result back. It explicitly tells the agent to call docx_read first, which distinguishes this tool from the read sibling and makes its editing scope clear without needing the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear operational context, including the prerequisite to call docx_read first and an explicit alternative when a text match spans a tab or line break: use replace_paragraph. It does not compare docx_edit against docx_create or state when not to use this tool, so it falls short of full when/when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a Microsoft Word .docx document and return its paragraphs with 1-based indices.
Use this before docx_edit: the returned paragraph index is the address every edit operation uses.
Each paragraph reports its text, its style id (e.g. Heading1), and whether it sits inside a table.
Runs are merged, so text that Word split across formatting runs still reads as one continuous string.
Modes:
text (default): every paragraph in document order.
outline: only styled paragraphs (headings, titles) — use it for a quick structural overview.
tables: only paragraphs inside table cells.
Large documents are paged: pass from/to to move through them, and check truncated in the result.
This tool only reads. To change the document, follow up with docx_edit.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last paragraph index to return, inclusive (default: from + number of paragraphs that fit). | |
| from | No | First paragraph index to return, 1-based (default 1). | |
| mode | No | text (default) = all paragraphs; outline = styled paragraphs only; tables = paragraphs inside tables. | |
| path | Yes | Path to the .docx file (absolute, or relative to the server root). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover read-only safety, and the description adds substantive behavior beyond them: runs are merged across formatting splits, results are paged with a `truncated` flag, and each paragraph reports style id and table membership. It also reinforces that the tool cannot mutate anything.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and the critical edit-ordering constraint, then modes, then paging. Efficient overall, though the Modes block partly restates the enum descriptions already present in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing return values and does so fully — paragraph text, style id, table flag, indices, and truncation state — leaving nothing essential unspecified for a read call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3; the description goes further by explaining that `from`/`to` are the paging mechanism and framing `outline`/`tables` by intent rather than just restating the enum. It does not, however, add syntax or edge-case detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read a Microsoft Word .docx document') plus what it returns ('paragraphs with 1-based indices'), which cleanly separates it from docx_edit and docx_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: 'Use this before docx_edit' because the returned index is the edit address, and names the follow-up tool for mutations. It also gives concrete when-to-use guidance for each mode ('use it for a quick structural overview').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a PDF and report what it is: page count, document metadata, whether it has a real text layer, and its table of contents.
Call this first, before pdf_read or pdf_render_page. It tells you which reading strategy works:
hasTextLayer true → pdf_read returns the actual text, page by page.
scanned true → the pages are images with no text at all. pdf_read cannot help; use pdf_render_page to render pages and read them visually.
The returned toc lists top-level entries with the page each one starts on, so you can jump
straight to the chapter a question is about instead of paging through the document.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the PDF (absolute, or relative to the server root). | |
| toc_limit | No | How many top-level outline entries to include (default 40). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the return shape (hasTextLayer, scanned flags, toc with page numbers) and the TOC's role in navigation. It stops short of noting failure modes such as encrypted or corrupt PDFs, so it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence followed by two short, high-signal blocks: a routing rule and a TOC usage note. Every sentence changes what the agent does; no filler or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by naming the return fields an agent must branch on. Combined with full schema coverage and existing annotations, nothing needed to call this correctly before reading a PDF is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description's mention of 'top-level entries' and the page each starts on adds marginal meaning to toc_limit, but no default, format, or interaction detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Open a PDF and report what it is') and enumerates the exact outputs (page count, metadata, text layer, TOC). It also distinguishes itself from sibling tools by name (pdf_read, pdf_render_page), so an agent can route without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this first, before pdf_read or pdf_render_page' and then gives decision rules keyed to outputs: hasTextLayer true → pdf_read; scanned true → pdf_read cannot help, use pdf_render_page. This is when-to-use plus when-not-to-use plus named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a PDF's table of contents (bookmarks) as a flat list with real page numbers.
This is the navigation index for reading: each entry has a 1-based index, a depth
(1 = top level), its title, and the 1-based page it starts on. Use it to find the section
that covers a topic, then read or render just those pages.
Not every PDF has a usable outline — a scanned book often does, a print-to-PDF rarely does.
When total is 0, fall back to pdf_read or pdf_render_page over page ranges.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last outline entry to return, inclusive. | |
| from | No | First outline entry to return, 1-based (default 1). | |
| path | Yes | Path to the PDF. | |
| max_depth | No | Only include entries at or above this depth (1 = top level only). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint and openWorldHint, but the description adds real behavioral context: entries carry index/depth/title/page, outlines are unreliable ('a scanned book often does, a print-to-PDF rarely does'), and total==0 is the signal to fall back. It discloses return-field semantics and a failure mode that the annotations cannot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs, front-loaded with purpose then usage then caveat. Every sentence earns its place; no filler or repetition of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly takes on the burden of explaining the returned entry fields and the empty-outline case. An agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so from/to/max_depth/path are already documented in the schema, and the description does not elaborate on their syntax or interaction. Baseline 3 applies; the description's discussion of entry fields is about output, not input parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Read a PDF's table of contents (bookmarks)') and even characterizes the exact shape of the result (flat list with 1-based index, depth, title, page). This is clearly distinguishable from pdf_read and pdf_render_page, which it names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the tool as 'the navigation index for reading' and tells the agent to use it to find a section then 'read or render just those pages.' It also gives the negative condition and the fallback: when total is 0, use pdf_read or pdf_render_page over page ranges.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the text of a PDF, page by page, with the page layout reconstructed into paragraphs.
Returns 1-based page numbers with their text. Headings are marked with a leading "# " so the structure of the page is visible. Pages are paged: pass from/to to move through the document.
This only works on PDFs that carry a text layer. If the PDF is a scan (pdf_info reports scanned: true), there is no text to extract and this tool refuses — render the pages with pdf_render_page and read them as images instead.
For a scanned PDF you can still use pdf_outline to learn which page a chapter starts on, then pass that page to pdf_render_page.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last page to read, inclusive. | |
| from | No | First page to read, 1-based (default 1). | |
| mode | No | paragraphs (default) merges visual lines into paragraphs; lines keeps one entry per visual line (useful for tables). | |
| path | Yes | Path to the PDF. | |
| max_chars | No | Character budget for this call (default 9000). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true and openWorldHint=false, but the description goes further: it discloses that the tool actively *refuses* on scan-only PDFs, describes the return shape (1-based page numbers, headings prefixed with '# '), and notes pages are paged via from/to. That is behavioral context the annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs, front-loaded with the core behavior, then the scan caveat, then the fallback path. Every sentence carries information an agent needs; nothing is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description itself explains the return format (pages with text, heading markers, page numbering) and the failure mode. Combined with 100% schema coverage for inputs, an agent has everything required to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so from/to/mode/max_chars are already documented in the schema — baseline 3 applies. The description only restates pagination via from/to and implies the paragraph mode; it adds no format, bounds, or budget guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('Read the text of a PDF, page by page') and immediately scopes what it returns (paragraph-reconstructed text with 1-based page numbers). It also carves out its niche against siblings by distinguishing text-layer PDFs from scans that require pdf_render_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when the tool works (PDFs with a text layer), when it does not (scanned PDFs, i.e. pdf_info reports scanned: true), and what to do instead — render with pdf_render_page or locate the chapter via pdf_outline first. This is a near-complete decision tree for the caller.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render one page of a PDF as an image and return it for you to look at.
This is how you read a scanned PDF, and how you see anything that plain text cannot carry: figures, block diagrams, circuit drawings, tables, equations, page layout, handwriting.
The rendered page is returned as an actual image, so you see exactly what is on it.
Options:
scale zooms. Omit it and the page is rendered at a width that keeps body text legible.
Use 2–3 when small text or a dense diagram matters.
region renders only part of the page, as fractions of the page from the top-left, e.g.
{x:0.5,y:0.1,w:0.5,h:0.3} for the top-right quadrant. Combine with a larger scale to zoom
into one figure or equation. Prefer this over rendering a whole page at a huge scale, which
wastes the image budget on whitespace.
out_path also writes the PNG to a file, when you need an artifact on disk.
To read a run of pages, call this once per page. Do not try to read a 400-page book end to end: use pdf_outline to find the relevant section and render only those pages.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | Page to render, 1-based. | |
| path | Yes | Path to the PDF. | |
| scale | No | Zoom factor. Omit for an automatic width that keeps body text legible. | |
| region | No | Render only part of the page, as fractions from the top-left. | |
| out_path | No | Also write the PNG here. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, non-destructive), and the description adds genuine behavioral context beyond them: the return value is an actual image the agent inspects, rendering consumes an image budget, wasteful full-page high-scale renders should be avoided, and out_path produces an on-disk side effect. It also sets the calling pattern ('once per page').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then a bulleted options list and a closing workflow rule. Every sentence carries information; no repetition of the name or restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter nested-schema tool with no output schema, the description fully covers what is returned (an image), how to control zoom and cropping, the file-writing side effect, and the multi-page strategy. Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, but the description still adds real meaning: scale omission gives an auto width tuned for legibility, a recommended 2–3 range, a concrete region example with quadrant semantics and fractional-from-top-left coordinates, and guidance to combine region with scale. It stops short of documenting coordinate edge cases, but adds clear value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Render one page of a PDF as an image') and immediately contrasts with text extraction by naming the cases plain text cannot carry: scans, figures, equations, handwriting. An agent can distinguish this from pdf_read or pdf_info without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit about when to use it (scanned PDFs, visual content), when to zoom via scale 2–3, when to prefer region over whole-page rendering, and when NOT to use it ('do not try to read a 400-page book end to end: use pdf_outline'). Names the sibling alternative directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0docx_createdocx_editdocx_readpdf_infopdf_outlinepdf_readpdf_render_pageScored across 7 tools
The four PDF tools (info, outline, read, render_page) and three DOCX tools (read, edit, create) target clearly distinct actions with clear format prefixes. The only overlap is that pdf_info also returns a table of contents while pdf_outline is dedicated to it, which the descriptions partially reconcile but could cause slight hesitation.
A strong, predictable format_action convention is used throughout (pdf_read, pdf_render_page, docx_read, docx_edit, docx_create). Minor deviation: pdf_info and pdf_outline are noun-style rather than verb-style, slightly breaking the verb_noun pattern.
Seven tools is well-scoped for a document-handling server, with each one earning its place (info, outline, read, render for PDF; read, edit, create for DOCX). No redundancy or bloat.
DOCX has full lifecycle coverage (create, read, edit/update) and PDF reading is thorough across text, scanned, and outline modes. Gaps: no PDF creation or PDF editing, though that may be out of scope for the server's apparent read-PDF/write-DOCX focus.
Generate and read PDFs for AI agents: a generate_pdf and a read_pdf tool, priced per document.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
