document-mcp 0.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +127 -0
- package/dist/bin.js +831 -0
- package/dist/index.cjs +827 -0
- package/dist/index.d.cts +5 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +826 -0
- package/package.json +95 -2
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ExaDev
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# document-mcp
|
|
2
|
+
|
|
3
|
+
[](https://github.com/ExaDev/document-mcp) [](https://www.npmjs.com/package/document-mcp) [](https://github.com/ExaDev/document-mcp/releases/latest) [](https://github.com/ExaDev/document-mcp/actions)
|
|
4
|
+
|
|
5
|
+
> An MCP (Model Context Protocol) server exposing [`documents.js`](https://github.com/ExaDev/documents.js)'s document-conversion, `.odb`, metadata, and font tooling as MCP tools, so an MCP-speaking agent can convert, inspect, and edit docx/pptx/odt/odp/ods/odg/odf/pdf/odb/xlsx/markdown documents without writing TypeScript against `documents.js` directly.
|
|
6
|
+
|
|
7
|
+
`document-mcp` adds no conversion or editing logic of its own — it is a dispatch layer over `documents.js`'s existing conversion functions, `DocumentConverter` port, and `.odb`/PDF readers, wired up as MCP tools served over stdio. [`document-cli`](https://github.com/ExaDev/document-cli) is the sibling frontend over the identical `documents.js` library — a terminal CLI/TUI rather than an MCP server — so the two are independent consumers of one shared implementation and can expose different subsets of it.
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
graph TD
|
|
11
|
+
schema("document-schema.js")
|
|
12
|
+
ooxml("ooxml.js")
|
|
13
|
+
odf("odf.js")
|
|
14
|
+
pdfcodec("pdf-codec")
|
|
15
|
+
mdcodec("markdown-codec")
|
|
16
|
+
documents("documents.js")
|
|
17
|
+
mcp("document-mcp")
|
|
18
|
+
cli("document-cli")
|
|
19
|
+
|
|
20
|
+
schema --> ooxml
|
|
21
|
+
schema --> odf
|
|
22
|
+
schema --> pdfcodec
|
|
23
|
+
schema --> mdcodec
|
|
24
|
+
schema --> documents
|
|
25
|
+
ooxml --> documents
|
|
26
|
+
odf --> documents
|
|
27
|
+
pdfcodec --> documents
|
|
28
|
+
mdcodec --> documents
|
|
29
|
+
documents --> mcp
|
|
30
|
+
odf --> mcp
|
|
31
|
+
pdfcodec --> mcp
|
|
32
|
+
documents --> cli
|
|
33
|
+
|
|
34
|
+
click schema "https://github.com/ExaDev/document-schema.js" "document-schema.js"
|
|
35
|
+
click ooxml "https://github.com/ExaDev/ooxml.js" "ooxml.js"
|
|
36
|
+
click odf "https://github.com/ExaDev/odf.js" "odf.js"
|
|
37
|
+
click pdfcodec "https://github.com/ExaDev/pdf-codec" "pdf-codec"
|
|
38
|
+
click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec"
|
|
39
|
+
click documents "https://github.com/ExaDev/documents.js" "documents.js"
|
|
40
|
+
click mcp "https://github.com/ExaDev/document-mcp" "document-mcp"
|
|
41
|
+
click cli "https://github.com/ExaDev/document-cli" "document-cli"
|
|
42
|
+
|
|
43
|
+
style mcp fill:#f9a825,stroke:#333,stroke-width:3px
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Getting started
|
|
47
|
+
|
|
48
|
+
Requires Node.js `>=20` and pnpm `11.6.0` (pinned via `packageManager` in `package.json`).
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
pnpm install
|
|
52
|
+
pnpm build # tsdown -> dist/ (ESM + CJS + .d.ts)
|
|
53
|
+
pnpm typecheck # tsc --noEmit
|
|
54
|
+
pnpm lint # eslint . --max-warnings 0
|
|
55
|
+
pnpm test # vitest run --project unit
|
|
56
|
+
pnpm test:smoke # rebuilds dist/, then spawns dist/bin.js as a real subprocess and drives it over genuine MCP stdio
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Once published, run the server directly via `npx document-mcp` (stdio transport, no install step needed).
|
|
60
|
+
|
|
61
|
+
### Connecting from Claude Code / Claude Desktop
|
|
62
|
+
|
|
63
|
+
Add an entry to the client's MCP server configuration (`claude mcp add` for Claude Code, or the `mcpServers` block in Claude Desktop's config file):
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"mcpServers": {
|
|
68
|
+
"document-mcp": {
|
|
69
|
+
"command": "npx",
|
|
70
|
+
"args": ["-y", "document-mcp"]
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Or, for local development against a checkout of this repository rather than the published package, point `command` at the built binary directly:
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"mcpServers": {
|
|
81
|
+
"document-mcp": {
|
|
82
|
+
"command": "node",
|
|
83
|
+
"args": ["/absolute/path/to/document-mcp/dist/bin.js"]
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Document I/O
|
|
90
|
+
|
|
91
|
+
Every tool that takes or produces document bytes goes through the same two hybrid shapes, documented once here rather than repeated per tool below.
|
|
92
|
+
|
|
93
|
+
**Input** (`DocumentInput`) is a union: either a filesystem `path` (the format is inferred from the file extension — `docx`, `pptx`, `xlsx`, `odt`, `odp`, `ods`, `odg`, `odf`, `md`/`markdown`, `pdf`), or inline `bytesBase64` plus an explicit `format` (required, since inline bytes carry no filename to infer one from). `.odb` tools are the one exception: a `.odb` has no single `DocumentFormat` of its own (it is a database front end, not a document — tables, saved queries, and reports are three unrelated output shapes), so their `source.path`/`source.bytesBase64` bytes are read directly with no format inference at all.
|
|
94
|
+
|
|
95
|
+
**Output** (`DocumentOutput`), on every tool that produces a document, is a single optional `outputPath`: supply it to have the tool write the result to that filesystem path (the response then reports `{ path, byteLength }`); omit it to receive the bytes inline instead (`{ bytesBase64, byteLength }`, flagged `large: true` above 5 MB — advisory only, the bytes are never truncated or refused).
|
|
96
|
+
|
|
97
|
+
## Tools
|
|
98
|
+
|
|
99
|
+
| Tool | Description |
|
|
100
|
+
| --- | --- |
|
|
101
|
+
| `convert_document` | Converts a document from one supported format to another via `documents.js`'s `DocumentConverter` port — docx, pptx, xlsx, odt, odp, ods, odg, odf, markdown, and pdf. Not every `(source, targetFormat)` pair is direct; call `list_document_conversions` first. |
|
|
102
|
+
| `list_document_conversions` | Lists every `(source, target)` format pair `convert_document` actually supports. |
|
|
103
|
+
| `metadata_read` | Reads a document's title/author/subject/keywords/creator/producer/created-and-modified timestamps. Works across every supported format, including xlsx and odf. |
|
|
104
|
+
| `metadata_write` | Patches a document's title/author/subject/keywords in place. Does not convert format — source and target format must match (or both be `pdf`); xlsx and odf are rejected as either. |
|
|
105
|
+
| `fonts` | Lists every source-embedded font face a docx/pptx/odt/odp/ods/odg document carries (family, weight/style, byte length). |
|
|
106
|
+
| `describe_font_file` | Reads a standalone `.ttf`/`.otf` font file and reports the family/bold/italic triple it declares about itself. |
|
|
107
|
+
| `docx_extras` | Reads a docx's own comments, footnotes, headers, footers, and numbering definitions — data the `ContentDocument` pivot cannot carry, so no other tool sees it. |
|
|
108
|
+
| `pdf_inspect` | Parses a PDF and reports a summary (page count, per-page size and item-kind histogram, metadata, embedded image formats), or the entire parsed `LayoutDocument` with `full: true`. |
|
|
109
|
+
| `odm_to_pdf` | Converts a `.odm` (ODF master document) to PDF. A `.odm` never carries its chapters' content inline, so each chapter resolves via a caller-supplied `chapters` href-to-document map and/or a `chaptersDir` searched by basename. |
|
|
110
|
+
| `from_package` | Rebuilds real document bytes in a target format from a `DocumentPackage` previously serialised to JSON (e.g. by a conversion tool's own `onDocument`/package-dump step). |
|
|
111
|
+
| `odb_tables` | Lists every table an embedded `.odb` database declares — column names, types, and row data — across every storage tier `documents.js` supports (HSQLDB TEXT/CACHED/BINARY, Firebird gbak backups). |
|
|
112
|
+
| `odb_forms` | Lists every form an `.odb` database declares, with each form's own data source and field-bound controls. |
|
|
113
|
+
| `odb_reports` | Lists every report an `.odb` database declares, with each report's own data-source command, band/group structure, and `rpt:` formula expressions. |
|
|
114
|
+
| `odb_query` | Runs a bounded single-table `SELECT` over an embedded `.odb` database's extracted tables — given directly as SQL or by naming a saved query. No database engine involved; an unsupported construct is reported as a tool error naming it, never silently ignored. |
|
|
115
|
+
| `odb_to_csv` | Extracts exactly one named table from an embedded `.odb` database as CSV bytes. The table name is required whenever the database declares more than one table. |
|
|
116
|
+
| `odb_to_xlsx` | Extracts every table an embedded `.odb` database declares into one xlsx workbook, one sheet per table. |
|
|
117
|
+
| `odb_render_report` | Resolves one of an `.odb` database's own reports — its data-bound command run through the bounded SQL engine, its `rpt:` formulas evaluated, its bands laid out — and renders the result to docx, odt, or pdf. |
|
|
118
|
+
|
|
119
|
+
## References
|
|
120
|
+
|
|
121
|
+
- [documents.js](https://github.com/ExaDev/documents.js) — the library this server exposes.
|
|
122
|
+
- [document-cli](https://github.com/ExaDev/document-cli) — the sibling CLI/TUI over the same library, whose toolchain this repository's scaffold mirrors.
|
|
123
|
+
- [Model Context Protocol](https://modelcontextprotocol.io) — the protocol this server implements, via [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server).
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
MIT
|