Excel MCP Server (FsOpenXmlDsl)

Kookerella.FsOpenXmlDsl

A typesafe F# DSL for building Excel workbooks, 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 .xlsx back into the same DSL.

See MAPPING.md for exactly which SpreadsheetML features map 1:1, which are approximated, and which aren't modeled yet.

This round-trips in both directions, which most Excel libraries (EPPlus, ClosedXML, NPOI, ...) don't: they give you an imperative API to build a workbook from scratch or mutate an existing one, but no way to turn an *existing* file back into readable source. Here, Reader parses a real .xlsx/.xlsm back into the same DSL, and Workbook.generateScript (F#) / CsCodeGen.Generate (C#) go one step further and render that model back out as a self-contained script that rebuilds an equivalent file - a decompiler for spreadsheets, not just a writer. Two more surfaces, Xml.ofWorkbook/Xml.toWorkbook (see "## XML" below) and Json.ofWorkbook/Json.toWorkbook (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, e.g. an XSLT pipeline producing a report. Kookerella.FsOpenXmlDsl.Mcp exposes all four directions as MCP tools (generate_fsharp_script/generate_csharp_script/generate_xml/create_workbook_from_xml/ generate_json/create_workbook_from_json) for an AI agent, and as fsopenxmldsl-mcp convert/build CLI commands for anyone else - try it on any spreadsheet you already have, no code required:

dotnet tool install -g Kookerella.FsOpenXmlDsl.Mcp

fsopenxmldsl-mcp convert your-file.xlsx --lang csharp

Don't have .NET installed? Download a self-contained build for your platform from the Releases page - no install required.

Demos

Full worked examples of the decompile-then-extend workflow above - reverse-engineering the same invoice template into C#, F#, an XSLT transform, and a plain JSON-generation script, each wired up to real data and real tests proving the result stays schema-valid - live in a companion repo: Kookerella.Demo.DecompileToSource.

Layout

• src/Kookerella.FsOpenXmlDsl — the library.
• Reference.fs — CellRef and "A1"-style address conversions.
• Styles.fs — cell formatting: Color, FontStyle, FillStyle, BorderStyle, AlignmentStyle, NumberFormat, CellProtection, CellStyle.
• Validation.fs — conditional formatting and data validation: ComparisonOperator (shared by both), ConditionalFormatRule, ValidationKind, ValidationAlert, and the ConditionalFormatEntry/DataValidationEntry records stored on Worksheet.
• Hyperlinks.fs — HyperlinkTarget (external URL/mailto: vs. internal same-workbook reference) and the HyperlinkEntry record stored on Worksheet.
• Comments.fs — CommentEntry (classic cell comments, i.e. current Excel's "Notes" - see MAPPING.md for the modern threaded-comments gap).
• Protection.fs — SheetProtection, the sheet-level protection flags stored on Worksheet (pairs with CellStyle.Protection for per-cell locking), and WorkbookProtection, the workbook-level structure/window protection flags stored on Workbook.
• DefinedNames.fs — DefinedNameScope/DefinedNameEntry, stored on Workbook rather than Worksheet - the one DSL concept that's genuinely workbook-level.
• PageSetup.fs — print settings: PageOrientation, PaperSize, PrintScaling, PageMargins, and the PageSetup record stored on Worksheet.
• Tables.fs — Excel Tables: TableColumn, TableStyle, and the TableEntry record stored as a list on Worksheet (a sheet can have several).
• Sparklines.fs — in-cell mini-charts: SparklineType, SparklineStyle, SparklineCell, and the SparklineGroupEntry record stored as a list on Worksheet (a sheet can have several independently-styled groups).
• Charts.fs — column/bar/line/pie charts: ChartType, ChartSeries, and the ChartEntry record stored as a list on Worksheet (a sheet can have several).
• Images.fs — raster images: ImageFormat and the ImageEntry record (raw file bytes plus a cell-range anchor) stored as a list on Worksheet.
• PivotTables.fs — PivotAggregation and the PivotTableEntry record (source range, row/column/value fields, an anchor cell) stored as a list on Worksheet.
• Model.fs — CellValue, Cell, Worksheet, Workbook (including Workbook. VbaProject, a macro-enabled workbook's raw vbaProject.bin bytes - see its own doc comment; there's no dedicated Macros.fs since it's a single opaque field, not a new type).
• Xml.fs / Xml.xsd — the XML surface: Xml.toWorkbook/Xml.ofWorkbook translate a Workbook 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 — the JSON surface: Json.toWorkbook/Json.ofWorkbook translate a Workbook to/from a System.Text.Json.Nodes.JsonObject tree, covering the same worksheet/workbook-level feature set Xml.fs does. Schema validation (Json.schema.json) is test-suite only, not a public API - see "## JSON" below.
• Builders.fs — ergonomic helpers: plain functional constructors (cellA1, ...) for the canonical model, plus the SheetItem/CellEntry types (each a single simple DU case with optional fields) and the sheet fold function - a small tree-shaped "AST for building a sheet" (rows of cells, plus sheet-level facts like column widths, merges, conditional formats, data validations, hyperlinks, comments, autofilter, and sheet protection) that mirrors how SpreadsheetML itself nests. SheetDsl is what you actually write against: cell/row/autoFilter/conditionalFormat/ dataValidation/hyperlink/comment members with real optional parameters (?col, ?style, ?index, the data validation alert fields, ?tooltip, ?author) - no builder objects, no separate "styled" function, no None-noise for the common case. (Protect is the one SheetItem case with no smart constructor - SheetProtection is a plain record you build the usual F# way, { SheetProtection.Default with ... }.)
• Interpreter/StyleRegistry.fs — interns fonts/fills/borders/number formats into a shared OOXML stylesheet (internal).
• Interpreter/ChartWriter.fs / ChartReader.fs — charts' own DSL ↔ DrawingML/ChartML translation, split out from Writer.fs/Reader.fs given how much larger that one feature's OOXML surface is than everything else combined (internal).
• Interpreter/ImageWriter.fs / ImageReader.fs — images' own DSL ↔ DrawingML translation (internal).
• Interpreter/DrawingWriter.fs / DrawingReader.fs — own the one DrawingsPart/ relationship a worksheet gets when it has charts and/or images, since both features share that one drawing canvas rather than each managing their own (internal).
• Interpreter/PivotTableWriter.fs / PivotTableReader.fs — pivot tables' own group-by
• aggregate engine plus DSL ↔ OOXML translation (pivotCacheDefinition/ pivotCacheRecords/pivotTableDefinition), split out from Writer.fs/Reader.fs the same way charts and images are (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 Workbook back out as a self-contained .fsx script that rebuilds an equivalent file when run (internal).
• Api.fs — the public Workbook.save / saveToStream / load / loadFromStream / generateScript entry points.
• tests/Kookerella.FsOpenXmlDsl.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 workbook it builds to Examples/ /output.xlsx (checked into the repo), so every feature has a real, openable .xlsx demonstrating it - a browsable gallery, not just assertions. Each scenario also gets an Examples/ /script.fsx - see "Regenerating a file as F# source" below - which a separate, slower Category=Slow test group actually executes via dotnet fsi and verifies against the committed .xlsx, and an Examples/ /workbook.xml - the same workbook through Xml.ofWorkbook, validated against Xml.xsd at generation time (see "## XML" below) - and an Examples/ /workbook.json - the same workbook through Json.ofWorkbook, validated against Json.schema.json at generation time (see "## JSON" below) - so one folder always has four views of the same example: the real file, the F# source that rebuilds it, and the XML/JSON that also rebuild it. Assets/ holds the one test fixture too large to inline as a base64 literal like every other binary fixture in Tests.fs - a real vbaProject.bin extracted from a workbook actually saved by Excel, used by the macro example.
• samples/Kookerella.FsOpenXmlDsl.Sample — a small console app that builds a workbook, saves it, and reads it back.
• src/Kookerella.CsOpenXmlDsl — an idiomatic, immutable, fluent C# wrapper over this library, for callers who'd rather not touch F# discriminated unions/option types directly. Now covers every feature this library models at the worksheet/workbook level - see its own README for scope and an example. tests/Kookerella.CsOpenXmlDsl.Tests is its own C# xUnit suite, exercising the wrapper the way a real C# caller would rather than reusing the F# test project.
• src/Kookerella.FsOpenXmlDsl.Mcp — a local MCP (Model Context Protocol) server exposing this library's read/write/code-generation/XML/JSON capabilities as tools any MCP-compatible AI agent can call directly, and the same conversion capability as plain fsopenxmldsl-mcp convert/build CLI commands for anyone not going through an MCP client - see its own README for the tool list and how to configure it.

Quick start

open Kookerella.FsOpenXmlDsl

open type Kookerella.FsOpenXmlDsl.SheetDsl

let headerStyle = { CellStyle.Default with Font = Some { FontStyle.Default with Bold = true } Fill = Some { Color = Rgb(220uy, 220uy, 220uy) } }

let data = sheet "Sheet1" [ row [ cell (Text "Name", style = headerStyle) cell (Text "Amount", style = headerStyle) ] row [ cell (Text "Widgets") cell (Number 42.5, style = { CellStyle.Default with NumberFormat = Some TwoDecimal }) ] Freeze(1, 0) ]

workbook [ data ] |> Workbook.save "out.xlsx"

// Reverse transform: let roundTripped = Workbook.load "out.xlsx"

CellEntry and SheetItem's row case are each a single simple DU case with optional fields (Col/Index) rather than separate "styled" or "explicit position" cases - None means "the next column/row after the previous entry" (starting at 0), Some n jumps there explicitly and sequential numbering resumes right after it. You don't construct the case directly, though: SheetDsl.cell/SheetDsl.row are members with real optional parameters (?col/?style on cell, ?index on row) that hide the Nones for the common case - plain let functions can't have optional parameters in F#, wh