MCP server
Report and dashboard authoring for AI clients, over stdio.
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
IMcpToolin anMcpToolRegistry; adding a tool does not touch the transport. - Shared logic: tools call the same
ReportDefinition,ReportJsonSerializer,DefinitionValidator, engine/renderers,DashboardDefinitionDocumentand 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
McpToolExceptionand a tool error content item; the server never swallows an exception. - No new packages: JSON-RPC and stdio are implemented with
System.Text.Jsonand 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
patharguments on load/save, not by a UI dialog.