document-mcp 2.0.9 → 2.1.0

package/README.md

@@ -15,9 +15,12 @@ graph TD
     mdcodec("markdown-codec")
     bytecodec("byte-codec")
     documents("documents.js")
+    outline("document-outline.js")
     mcp("document-mcp")
     cli("document-cli")
 
+    schema --> outline
+    outline --> mcp
     schema --> ooxml
     schema --> odf
     schema --> pdfcodec
@@ -42,6 +45,7 @@ graph TD
     click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec"
     click bytecodec "https://github.com/ExaDev/byte-codec" "byte-codec"
     click documents "https://github.com/ExaDev/documents.js" "documents.js"
+    click outline "https://github.com/ExaDev/document-outline.js" "document-outline.js"
     click mcp "https://github.com/ExaDev/document-mcp" "document-mcp"
     click cli "https://github.com/ExaDev/document-cli" "document-cli"
 
@@ -210,6 +214,7 @@ Every tool that takes or produces document bytes goes through the same two hybri
 | `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`. |
 | `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. |
 | `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). |
+| `outline_document` | Projects a document's own table of contents as structured JSON: groups (`{ text, level, children }`) for headings, list items, slides, sheets, and draw pages, leaves (`{ kind, text }`) for the content between them. The outline is over the source's own content — read through `documents.js`'s `DocumentConverter` port and built by `document-outline.js`'s `buildOutline`. |
 | `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). |
 | `odb_forms` | Lists every form an `.odb` database declares, with each form's own data source and field-bound controls. |
 | `odb_reports` | Lists every report an `.odb` database declares, with each report's own data-source command, band/group structure, and `rpt:` formula expressions. |
@@ -221,12 +226,13 @@ Every tool that takes or produces document bytes goes through the same two hybri
 ## References
 
 - [documents.js](https://github.com/ExaDev/documents.js) — the library this server exposes.
+- [document-outline.js](https://github.com/ExaDev/document-outline.js) — the artefact-utilities package over document-schema.js's tree-form `DocumentPackage` whose `buildOutline` powers `outline_document`.
 - [document-cli](https://github.com/ExaDev/document-cli) — the sibling CLI/TUI over the same library, whose toolchain this repository's scaffold mirrors.
 - [Model Context Protocol](https://modelcontextprotocol.io) — the protocol this server implements, via [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server).
 
 ## Gotchas
 
-- **Runtime dependencies are `documents.js` + `@modelcontextprotocol/server` + `zod` only; `pdf-codec` and `odf.js` are devDependencies (test-support only).** Every runtime reach into either — `ProvidedFont`/`FontSubstitution`/`describeFontFace`/the `WinAnsi` substitution shape — goes through `documents.js`'s own re-exports, so a published install pulls in no direct `pdf-codec`/`odf.js` dependency. `odf.js` survives in `devDependencies` solely because `src/test-support/odm-fixture.ts` and `src/test-support/embedded-font-fixture.ts` build real ODF package fixtures from its low-level XML primitives (`zipPackage`/`el`/`rootElement`), and `src/test-support/` is excluded from the `tsdown` build — only `src/index.ts` and `src/bin.ts` are entry points — so neither fixture module ever ships in `dist/`.
+- **Runtime dependencies are `documents.js` + `document-outline.js` + `@modelcontextprotocol/server` + `zod` only; `pdf-codec` and `odf.js` are devDependencies (test-support only).** `document-outline.js` is the one dependency beyond the server stack itself: `outline_document` imports `buildOutline`/`outlineLeafText` from it, and documents.js deliberately does not re-export them (the outline projection lives in the family's artefact-utilities package, which depends only on `document-schema.js` — already a transitive dependency via documents.js — so it adds no second copy of anything). Every runtime reach into `pdf-codec`/`odf.js` — `ProvidedFont`/`FontSubstitution`/`describeFontFace`/the `WinAnsi` substitution shape — goes through `documents.js`'s own re-exports, so a published install pulls in no direct `pdf-codec`/`odf.js` dependency. `odf.js` survives in `devDependencies` solely because `src/test-support/odm-fixture.ts` and `src/test-support/embedded-font-fixture.ts` build real ODF package fixtures from its low-level XML primitives (`zipPackage`/`el`/`rootElement`), and `src/test-support/` is excluded from the `tsdown` build — only `src/index.ts` and `src/bin.ts` are entry points — so neither fixture module ever ships in `dist/`.
 
 ## License
 

package/dist/bin.js

@@ -6,8 +6,9 @@ import { z } from "zod";
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { buildOutline, isOutlineNode, outlineLeafText } from "document-outline.js";
 //#region package.json
-var version = "2.0.9";
+var version = "2.1.0";
 //#endregion
 //#region src/io/document-input.ts
 const EXTENSION_TO_FORMAT = {
@@ -773,6 +774,69 @@ function registerOdmTools(server) {
 	});
 }
 //#endregion
+//#region src/tools/outline.ts
+const OUTLINE_PROBE_TARGETS = {
+	csv: "ods",
+	docx: "odt",
+	odf: "pdf",
+	odg: "pdf",
+	odt: "docx",
+	odp: "pptx",
+	ods: "xlsx",
+	markdown: "docx",
+	pdf: "docx",
+	pptx: "odp",
+	svg: "odg",
+	xlsx: "ods"
+};
+function leafKind(leaf) {
+	if ("kind" in leaf) return leaf.kind;
+	if ("mathml" in leaf) return "formula";
+	return "embeddedObject";
+}
+function toOutlineJson(children) {
+	return children.map((child) => isOutlineNode(child) ? {
+		text: child.text,
+		level: child.level,
+		children: toOutlineJson(child.children)
+	} : {
+		kind: leafKind(child),
+		text: outlineLeafText(child)
+	});
+}
+function registerOutlineTools(server) {
+	const converter = createLocalDocumentConverter();
+	server.registerTool("outline_document", {
+		title: "Outline document",
+		description: "Projects a document's table of contents as a structured outline: reads the source through documents.js's DocumentConverter port, takes the tree-form DocumentPackage the conversion reports, and runs document-outline.js's buildOutline over it. Groups carry { text, level, children } (a heading's, list item's, slide's, sheet's, or page's own label plus nested children); leaves carry { kind, text }. The outline is over the source's own content -- the internal conversion target preserves it and is pdf only for odf (the one format that only converts to pdf) and odg (whose alternative, svg, cannot represent more than one page).",
+		inputSchema: z.object({ source: DocumentInputSchema.describe("The document to outline.") })
+	}, async ({ source }, ctx) => {
+		const { signal } = ctx.mcpReq;
+		const { bytes, format } = await resolveDocumentInput(source, { signal });
+		const targetFormat = OUTLINE_PROBE_TARGETS[format];
+		const pkg = (await converter.convert({
+			source: {
+				format,
+				bytes
+			},
+			targetFormat
+		}, { signal })).package;
+		if (pkg === void 0) throw new Error(`the ${format}-to-${targetFormat} conversion reported no DocumentPackage, so there is no tree to outline`);
+		const structuredContent = {
+			sourceFormat: format,
+			kind: pkg.kind,
+			outline: toOutlineJson(buildOutline(pkg))
+		};
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(structuredContent)
+			}],
+			structuredContent
+		};
+	});
+}
+//#endregion
 //#region src/tools/pdf-inspect.ts
 function buildItemKindHistogram(items) {
 	const histogram = /* @__PURE__ */ new Map();
@@ -838,6 +902,7 @@ function createServer() {
 	registerOdbTools(server);
 	registerOdbRenderReportTools(server);
 	registerOdmTools(server);
+	registerOutlineTools(server);
 	registerPdfInspectTools(server);
 	return server;
 }

package/dist/index.cjs

@@ -5,8 +5,9 @@ let zod = require("zod");
 let node_fs_promises = require("node:fs/promises");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
+let document_outline_js = require("document-outline.js");
 //#region package.json
-var version = "2.0.9";
+var version = "2.1.0";
 //#endregion
 //#region src/io/document-input.ts
 const EXTENSION_TO_FORMAT = {
@@ -772,6 +773,69 @@ function registerOdmTools(server) {
 	});
 }
 //#endregion
+//#region src/tools/outline.ts
+const OUTLINE_PROBE_TARGETS = {
+	csv: "ods",
+	docx: "odt",
+	odf: "pdf",
+	odg: "pdf",
+	odt: "docx",
+	odp: "pptx",
+	ods: "xlsx",
+	markdown: "docx",
+	pdf: "docx",
+	pptx: "odp",
+	svg: "odg",
+	xlsx: "ods"
+};
+function leafKind(leaf) {
+	if ("kind" in leaf) return leaf.kind;
+	if ("mathml" in leaf) return "formula";
+	return "embeddedObject";
+}
+function toOutlineJson(children) {
+	return children.map((child) => (0, document_outline_js.isOutlineNode)(child) ? {
+		text: child.text,
+		level: child.level,
+		children: toOutlineJson(child.children)
+	} : {
+		kind: leafKind(child),
+		text: (0, document_outline_js.outlineLeafText)(child)
+	});
+}
+function registerOutlineTools(server) {
+	const converter = (0, documents_js.createLocalDocumentConverter)();
+	server.registerTool("outline_document", {
+		title: "Outline document",
+		description: "Projects a document's table of contents as a structured outline: reads the source through documents.js's DocumentConverter port, takes the tree-form DocumentPackage the conversion reports, and runs document-outline.js's buildOutline over it. Groups carry { text, level, children } (a heading's, list item's, slide's, sheet's, or page's own label plus nested children); leaves carry { kind, text }. The outline is over the source's own content -- the internal conversion target preserves it and is pdf only for odf (the one format that only converts to pdf) and odg (whose alternative, svg, cannot represent more than one page).",
+		inputSchema: zod.z.object({ source: DocumentInputSchema.describe("The document to outline.") })
+	}, async ({ source }, ctx) => {
+		const { signal } = ctx.mcpReq;
+		const { bytes, format } = await resolveDocumentInput(source, { signal });
+		const targetFormat = OUTLINE_PROBE_TARGETS[format];
+		const pkg = (await converter.convert({
+			source: {
+				format,
+				bytes
+			},
+			targetFormat
+		}, { signal })).package;
+		if (pkg === void 0) throw new Error(`the ${format}-to-${targetFormat} conversion reported no DocumentPackage, so there is no tree to outline`);
+		const structuredContent = {
+			sourceFormat: format,
+			kind: pkg.kind,
+			outline: toOutlineJson((0, document_outline_js.buildOutline)(pkg))
+		};
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(structuredContent)
+			}],
+			structuredContent
+		};
+	});
+}
+//#endregion
 //#region src/tools/pdf-inspect.ts
 function buildItemKindHistogram(items) {
 	const histogram = /* @__PURE__ */ new Map();
@@ -837,6 +901,7 @@ function createServer() {
 	registerOdbTools(server);
 	registerOdbRenderReportTools(server);
 	registerOdmTools(server);
+	registerOutlineTools(server);
 	registerPdfInspectTools(server);
 	return server;
 }

package/dist/index.js

@@ -4,8 +4,9 @@ import { z } from "zod";
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { buildOutline, isOutlineNode, outlineLeafText } from "document-outline.js";
 //#region package.json
-var version = "2.0.9";
+var version = "2.1.0";
 //#endregion
 //#region src/io/document-input.ts
 const EXTENSION_TO_FORMAT = {
@@ -771,6 +772,69 @@ function registerOdmTools(server) {
 	});
 }
 //#endregion
+//#region src/tools/outline.ts
+const OUTLINE_PROBE_TARGETS = {
+	csv: "ods",
+	docx: "odt",
+	odf: "pdf",
+	odg: "pdf",
+	odt: "docx",
+	odp: "pptx",
+	ods: "xlsx",
+	markdown: "docx",
+	pdf: "docx",
+	pptx: "odp",
+	svg: "odg",
+	xlsx: "ods"
+};
+function leafKind(leaf) {
+	if ("kind" in leaf) return leaf.kind;
+	if ("mathml" in leaf) return "formula";
+	return "embeddedObject";
+}
+function toOutlineJson(children) {
+	return children.map((child) => isOutlineNode(child) ? {
+		text: child.text,
+		level: child.level,
+		children: toOutlineJson(child.children)
+	} : {
+		kind: leafKind(child),
+		text: outlineLeafText(child)
+	});
+}
+function registerOutlineTools(server) {
+	const converter = createLocalDocumentConverter();
+	server.registerTool("outline_document", {
+		title: "Outline document",
+		description: "Projects a document's table of contents as a structured outline: reads the source through documents.js's DocumentConverter port, takes the tree-form DocumentPackage the conversion reports, and runs document-outline.js's buildOutline over it. Groups carry { text, level, children } (a heading's, list item's, slide's, sheet's, or page's own label plus nested children); leaves carry { kind, text }. The outline is over the source's own content -- the internal conversion target preserves it and is pdf only for odf (the one format that only converts to pdf) and odg (whose alternative, svg, cannot represent more than one page).",
+		inputSchema: z.object({ source: DocumentInputSchema.describe("The document to outline.") })
+	}, async ({ source }, ctx) => {
+		const { signal } = ctx.mcpReq;
+		const { bytes, format } = await resolveDocumentInput(source, { signal });
+		const targetFormat = OUTLINE_PROBE_TARGETS[format];
+		const pkg = (await converter.convert({
+			source: {
+				format,
+				bytes
+			},
+			targetFormat
+		}, { signal })).package;
+		if (pkg === void 0) throw new Error(`the ${format}-to-${targetFormat} conversion reported no DocumentPackage, so there is no tree to outline`);
+		const structuredContent = {
+			sourceFormat: format,
+			kind: pkg.kind,
+			outline: toOutlineJson(buildOutline(pkg))
+		};
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(structuredContent)
+			}],
+			structuredContent
+		};
+	});
+}
+//#endregion
 //#region src/tools/pdf-inspect.ts
 function buildItemKindHistogram(items) {
 	const histogram = /* @__PURE__ */ new Map();
@@ -836,6 +900,7 @@ function createServer() {
 	registerOdbTools(server);
 	registerOdbRenderReportTools(server);
 	registerOdmTools(server);
+	registerOutlineTools(server);
 	registerPdfInspectTools(server);
 	return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document-mcp",
-  "version": "2.0.9",
+  "version": "2.1.0",
   "description": "MCP (Model Context Protocol) server exposing documents.js's document-conversion, .odb, metadata, and font tooling as MCP tools.",
   "type": "module",
   "repository": {
@@ -85,7 +85,8 @@
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
-    "documents.js": "^3.1.1",
+    "document-outline.js": "^1.0.0",
+    "documents.js": "^3.1.2",
     "zod": "^4.2.0"
   },
   "devDependencies": {