Word MCP Server (FsWordDsl)

Kookerella.FsWordDsl

A typesafe F# DSL for building Word documents, interpreted into calls against the DocumentFormat.OpenXml SDK. The DSL is a plain data model (records/DUs with structural equality) - the interpreter (Writer) compiles it to OOXML, and the reverse transform (Reader) parses an existing .docx back into the same DSL.

This is the WordprocessingML sibling of Kookerella.FsOpenXmlDsl (the Excel/SpreadsheetML one) - same objectives, same round-trip philosophy, translated to Word's own document model. See MAPPING.md for exactly which WordprocessingML features map 1:1, which are approximated, and which aren't modeled yet.

This round-trips in both directions, which most Word libraries don't: they give you an imperative API to build a document from scratch, but no way to turn an *existing* file back into readable source. Here, Reader parses a real .docx/.docm back into the same DSL, and Document.generateScript goes one step further and renders that model back out as a self-contained script that rebuilds an equivalent file - a decompiler for Word documents, not just a writer. Two more surfaces, Xml.toDocument/Xml.ofDocument (see "## XML" below) and Json.toDocument/Json.ofDocument (see "## JSON" below), do the same translation to/from plain XML or JSON against a real schema - for a caller who'd rather generate or consume data than write code at all.

A fluent C# wrapper (Kookerella.CsWordDsl) sits on top of the F# core for callers who'd rather not touch F# discriminated unions/option types directly - immutable records with With* builders, plus its own CsCodeGen decompiler that renders a Document back out as runnable C# source. See "## The C# wrapper" below.

An MCP server (Kookerella.FsWordDsl.Mcp) exposes the same read/write/decompile capabilities as tools any MCP-compatible AI agent can call directly, and doubles as a plain CLI (fsworddsl-mcp convert/build) for anyone not going through an MCP client at all - see its own README for the full tool list.

Don't have .NET installed? Download a self-contained build of the MCP server for your platform (win/linux/osx, x64/arm64) from the Releases page - unzip and run, no install required.

Layout

• src/Kookerella.FsWordDsl - the library.
• Units.fs - conversions between points/inches/pixels and the physical units WordprocessingML uses on the wire (twips for page geometry/spacing, EMU for image sizing).
• Styles.fs - character and paragraph formatting: Color (Rgb, Auto, or a theme-relative Theme color - see ThemeColorKind), HighlightColor (Word's own fixed highlight palette), UnderlineStyle, RunStyle (including small caps/all caps/hidden text), ParagraphAlignment, Indentation, LineSpacingRule, TabStopAlignment/TabLeader/TabStop, ParagraphFormat (including paragraph borders, shading, and custom tab stops), BorderLineStyle, BorderSide, BorderStyle (reused for both paragraph and table borders).
• NamedStyles.fs - StyleDefinition (paragraph or character, with BasedOn inheritance) and a small BuiltInStyles catalog (normal, heading1/2/3, title, listParagraph, hyperlinkCharStyle).
• Numbering.fs - NumberFormatKind, ListLevel, NumberingDefinition for numbered/bulleted lists, including multi-level ones (ListLevel isn't limited to one per definition - see Builders.multiLevelNumberedListDef).
• Hyperlinks.fs - HyperlinkTarget (external URL vs. internal bookmark reference).
• Protection.fs - EditRestriction and DocumentProtection, document-level (Word has no per-section equivalent of Excel's per-sheet protection).
• Revisions.fs - RevisionKind/Revision for track changes (Inline.TrackedChange, Paragraph.MarkRevision) - narrowly scoped to inserted/deleted content and paragraph marks, see MAPPING.md for what isn't covered.
• ContentControls.fs - ContentControlType/ContentControlProps for content controls (structured document tags, w:sdt): plain text, rich text, dropdown/combo box, date picker, checkbox - see MAPPING.md for what isn't covered.
• PageSetup.fs - PageOrientation, PageSize, PageMargins, SectionBreakType, NoteNumberRestart/NoteNumberingSettings (a section's own footnote/endnote numbering).
• Tables.fs - TableBorders, VerticalMergeKind, TableCellProps (including a per-cell Margins override), TableStyleRef, TableStyleRegion/ TableStyleDefinition (custom table style definitions - all thirteen of OOXML's conditional-formatting regions), and CellMargins (shared shape for a table's default margins and a single cell's own override).
• Images.fs - ImageFormat, ImageEntry (raw file bytes plus an on-page size), anchored inline within a run.
• DocumentProperties.fs - DocumentProperties (Title, Author, Subject, Keywords, Comments, Category, Company) - core document metadata, Document.Properties.
• Model.fs - the recursive content model: Inline (runs, breaks, images, hyperlinks, bookmarks and comments - both the single-paragraph Bookmark/Comment cases and the cross-paragraph BookmarkRangeStart/End/CommentRangeStart/End markers, simple fields, footnotes/endnotes, TrackedChange for track changes, and InlineContentControl for content controls), Paragraph (including MarkRevision), Block (paragraph, table, or ContentControlBlock - the block-level counterpart to InlineContentControl), TableCell/ TableRow (including RepeatAsHeader)/TableEntry (including CellMargins), HeaderFooterSet, SectionProperties (including BreakType and FootnoteNumbering/ EndnoteNumbering), Section, Document (including Document.VbaProject, a macro-enabled document's raw vbaProject.bin bytes, Document.Properties, and Document.TableStyles).
• Xml.fs / Xml.xsd - the XML surface: Xml.toDocument/Xml.ofDocument translate a Document to/from an XElement tree, and Xml.schemaSet() loads the paired schema (embedded in the assembly as a resource) for validating either direction. See "## XML" below.
• Json.fs / Json.schema.json - the JSON surface: Json.toDocument/Json.ofDocument translate a Document to/from a System.Text.Json.Nodes.JsonObject tree. Schema validation is test-suite only, not a public API. See "## JSON" below.
• Builders.fs - plain functional constructors (section, document, withStyles, withNumbering, withProtection, withVbaProject, withDocumentProperties, withTableStyles, bulletListDef, numberedListDef, multiLevelNumberedListDef) plus DocumentDsl - smart constructors (run, para (with markRevision), hyperlink, bookmark, comment, inserted/deleted (track changes), contentControl/contentControlBlock (content controls), image, footnote, endnote, tableCell, tableRow (with height/repeatAsHeader), table (with style/borders/cellMargins)) with real optional parameters, the Word analog of the Excel repo's SheetDsl.
• Interpreter/StyleRegistry.fs - shared run/paragraph/border/color conversions plus Document.Styles <-> styles.xml (internal).
• Interpreter/ImageWriter.fs / ImageReader.fs - an inline image's own DSL <-> DrawingML translation (internal).
• Interpreter/Writer.fs - DSL -> OOXML (internal).
• Interpreter/Reader.fs - OOXML -> DSL, the reverse transform (internal).
• Interpreter/CodeGen.fs - DSL -> F# *source text*: renders a Document back out as a self-contained .fsx script that rebuilds an equivalent file when run (internal).
• Api.fs - the public Document.save/saveToStream/load/loadFromStream/ generateScript entry points.
• src/Kookerella.CsWordDsl - the fluent C# wrapper (see "## The C# wrapper" below): immutable records/sealed record closed hierarchies mirroring the F# core's own types one-for-one, DocumentConverter.cs (internal, the two-way F#<->C# translation), DocumentIO.cs (Save/Load, the one place this project does I/O), CsCodeGen.cs (DSL -> C# *source text*, the C# analog of Interpreter/CodeGen.fs).
• src/Kookerella.FsWordDsl.Mcp - the MCP server (see its own README): DocumentTools.fs (the tool surface, one [ ]-tagged member per tool), Program.fs (dispatches to the MCP stdio server, or to a plain convert/build CLI, depending on argv). Distributed as a dotnet tool (fsworddsl-mcp), same as the Excel sibling's own Kookerella.FsOpenXmlDsl.Mcp.
• tests/Kookerella.FsWordDsl.Tests - one test per feature, each validating the produced file against the OOXML schema (DocumentFormat.OpenXml.Validation.OpenXmlValidator) and asserting an exact round trip back through the DSL. Each test also writes the document it builds to Examples/ /output.docx (checked into the repo), plus script.fsx (regenerates the file - a separate, slower Category=Slow test group actually executes each one via dotnet fsi), document.xml, and document.json - one folder always has four views of the same example.
• tests/Kookerella.CsWordDsl.Tests - DriftGuardTests.cs (a reflection-based tripwire checking the C# wrapper's DU mirrors haven't fallen behind the F# core's own case counts), DocumentTests.cs (targeted round-trip assertions per feature), ExampleTests.cs (reloads the F# suite's own checked-in Examples/*/output.docx fixtures rather than re-authoring every scenario a second time), CsCodeGenTests.cs (actually executes a generated file via dotnet run --file, the C# analog of the F# suite's Category=Slow dotnet fsi group).
• samples/Kookerella.FsWordDsl.Sample - a small console app that builds a document, saves it, and reads it back.

Quick start

open Kookerella.FsWordDsl

open type Kookerella.FsWordDsl.DocumentDsl

let doc = document [ section [ para ([ run "Quarterly Report" ], styleId = "Title") para [ run "This report covers " run ("Q1 2026", style = { RunStyle.Default with Bold = true }) run ", see the " hyperlink ("full dataset", ExternalUrl "https://example.com/data") run " for details." ] ] ]

doc |> Document.save "report.docx"

// Reverse transform: let roundTripped = Document.load "report.docx"

document defaults Styles to BuiltInStyles.all, so styleId = "Heading1" (or any other built-in id) just works without registering it first - pipe withStyles afterward to replace or extend that set. run/para/hyperlink/bookmark/comment/image/ tableCell/tableRow/table are DocumentDsl members with real optional parameters (open type Kookerella.FsWordDsl.DocumentDsl brings them into scope unqualified, same as open type SheetDsl does in the Excel repo) - plain F# let bindings can't have optional parameters, which is why this part of the DSL is a type.

A Paragraph's Inlines are naturally several independently-styled runs - rich text (mixed formatting within one paragraph) is first-class, not a documented gap the way Excel's single-uniform-run Text cell is:

para

[ run "Plain text, " run ("bold", style = { RunStyle.Default with Bold = true }) run ", and " run ("colored", style = { RunStyle.Default with Color = Some Color.red }) ]

RunStyle also covers sma