document-mcp 1.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/README.md +65 -8
- package/dist/bin.js +815 -2
- package/dist/index.cjs +815 -2
- package/dist/index.js +815 -2
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
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
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,
|
|
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
8
|
|
|
9
9
|
```mermaid
|
|
10
10
|
graph TD
|
|
@@ -15,6 +15,7 @@ graph TD
|
|
|
15
15
|
mdcodec("markdown-codec")
|
|
16
16
|
documents("documents.js")
|
|
17
17
|
mcp("document-mcp")
|
|
18
|
+
cli("document-cli")
|
|
18
19
|
|
|
19
20
|
schema --> ooxml
|
|
20
21
|
schema --> odf
|
|
@@ -28,6 +29,7 @@ graph TD
|
|
|
28
29
|
documents --> mcp
|
|
29
30
|
odf --> mcp
|
|
30
31
|
pdfcodec --> mcp
|
|
32
|
+
documents --> cli
|
|
31
33
|
|
|
32
34
|
click schema "https://github.com/ExaDev/document-schema.js" "document-schema.js"
|
|
33
35
|
click ooxml "https://github.com/ExaDev/ooxml.js" "ooxml.js"
|
|
@@ -36,28 +38,83 @@ graph TD
|
|
|
36
38
|
click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec"
|
|
37
39
|
click documents "https://github.com/ExaDev/documents.js" "documents.js"
|
|
38
40
|
click mcp "https://github.com/ExaDev/document-mcp" "document-mcp"
|
|
41
|
+
click cli "https://github.com/ExaDev/document-cli" "document-cli"
|
|
39
42
|
|
|
40
43
|
style mcp fill:#f9a825,stroke:#333,stroke-width:3px
|
|
41
44
|
```
|
|
42
45
|
|
|
43
|
-
## Status
|
|
44
|
-
|
|
45
|
-
Under construction. This repository currently holds the project scaffold only (package/build/lint/release tooling and the shared hybrid document input/output I/O helpers) — no MCP tools are registered yet. A later phase wires `documents.js`'s conversions, `.odb` reading, metadata, and font tooling up as real MCP tools. This README will be rewritten once that lands.
|
|
46
|
-
|
|
47
46
|
## Getting started
|
|
48
47
|
|
|
49
48
|
Requires Node.js `>=20` and pnpm `11.6.0` (pinned via `packageManager` in `package.json`).
|
|
50
49
|
|
|
51
50
|
```sh
|
|
52
51
|
pnpm install
|
|
53
|
-
pnpm build
|
|
52
|
+
pnpm build # tsdown -> dist/ (ESM + CJS + .d.ts)
|
|
54
53
|
pnpm typecheck # tsc --noEmit
|
|
55
54
|
pnpm lint # eslint . --max-warnings 0
|
|
56
55
|
pnpm test # vitest run --project unit
|
|
57
|
-
pnpm test:smoke # rebuilds dist/, then a
|
|
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
|
+
}
|
|
58
87
|
```
|
|
59
88
|
|
|
60
|
-
|
|
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. |
|
|
61
118
|
|
|
62
119
|
## References
|
|
63
120
|
|