src/Beep.Reports.Mcp is a dependency-free MCP server over stdio (JSON-RPC 2.0, newline-delimited). It exposes the shared report and dashboard designer surface as tools, so an MCP client (Claude Desktop, an IDE agent, a script) can create, edit, validate, preview and export reports and author dashboards without host UI. No third-party MCP package is used, so there is no new dependency to review.

Run

dotnet run --project src/Beep.Reports.Mcp -c Release

The server reads one JSON-RPC message per line from stdin and writes one response per line to stdout. Diagnostics go to the client as tool errors (isError: true), never as unhandled exceptions. BEEP_REPORTS_SAMPLES may point at the repository's samples folder; otherwise it is found by walking up from the executable.

Client configuration

{
  "mcpServers": {
    "beep-reports": {
      "command": "dotnet",
      "args": ["run", "--project", "C:/path/to/Beep.Reports/src/Beep.Reports.Mcp", "-c", "Release"]
    }
  }
}

Or point at the built executable (src/Beep.Reports.Mcp/bin/Release/net10.0/Beep.Reports.Mcp.exe) with no arguments.

Tools

Reports and authoring

Tool What it does
report.new New A4 report with a detail band
report.load Open by sample name, file path or inline JSON
report.list Sample report names and open reports
report.save / report.json / report.setJson Persist, read and replace the canonical definition
report.validate / report.describe Diagnostics, and page/bands/items/parameters/styles/groups/data sources
report.patch Patch top-level properties (settings, metadata, theme, localization, interactivity, scripts)
report.undo / report.redo / report.close Snapshot undo/redo (one step per mutation) and session close
band.add / band.update / band.remove / band.move Band authoring (kind, height, group, data source, patch)
item.add / item.update / item.remove / item.clone / item.move Item authoring for every registered type; the patch sets any model property (text, value, style, font, format, action, altText, bookmark, ...)
page.update Page size, margins, columns, paper source, duplex, culture, direction
style.add / style.update / style.remove Named styles
parameter.add / parameter.update / parameter.remove Report parameters
group.add / group.update / group.remove Groups
documentMap.set Item bookmark and document-map label

Preview and output

Tool What it does
report.preview Runs the report and returns up to maxPages pages as base64 PNG
report.export Runs and exports pdf, html, png, jpeg, svg, docx, xlsx, xlsx-layout, pptx, rtf, csv, json, xml, txt; writes a file when path is given

Runs use the in-memory sample data (samples/data/sales.json) for data sources that match it; a report without data sources runs without it.

Dashboards

Tool What it does
dashboard.load / dashboard.save / dashboard.json Open, persist and read a dashboard document
dashboard.describe / dashboard.validate Pages, widgets, parameters; diagnostics
dashboard.addWidget / dashboard.moveWidget / dashboard.removeWidget Headless design commands (12-column grid)
dashboard.undo / dashboard.redo / dashboard.close Design history and session close

Headless equivalents of UI-only interactions

Tool Replaces
theme.list / theme.get / theme.css live theme painting: tokens, and CSS custom properties for a client preview
color.parse / color.contrast the colour dialog: normalize #RGB/#RRGGBB/#AARRGGBB and check WCAG contrast
expression.functions / expression.validate the expression dialog: function signatures and compile diagnostics
parameter.list the parameter dialog: the parameter definitions
designer.shortcuts / designer.analyze the shortcuts view and the Design Analyzer
item.resize / item.arrange / item.snap drag/resize, align/distribute/same-size/z-order/lock and snapping
dashboard.resizeWidget dashboard drag-resize on the 12-column grid

Catalogues

Tool What it does
designer.commands The designer shell commands with ids and localized text
catalog.keys Keys the designer or viewer asks for, with the English text
localization.coverage Per-culture translation coverage and the release-note statement

Design

  • Contract-based: every tool is an IMcpTool in an McpToolRegistry; adding a tool does not touch the transport.
  • Shared logic: tools call the same ReportDefinition, ReportJsonSerializer, DefinitionValidator, engine/renderers, DashboardDefinitionDocument and designer commands as the hosts; the MCP project contains no report or dashboard logic.
  • Unattended safety: expected failures (bad arguments, unknown ids, invalid patches) become McpToolException and a tool error content item; the server never swallows an exception.
  • No new packages: JSON-RPC and stdio are implemented with System.Text.Json and the base class library.

Limits

  • Dashboard rendering (PNG/PDF of a dashboard) is not exposed yet; authoring, validation and grid resize are.
  • Sessions are in-process and lost when the server exits; save the definition to keep it.
  • Native file pickers are replaced by path arguments on load/save, not by a UI dialog.