rpt-mcp (SAP Crystal Reports)

rpt-mcp

English | 中文

用于 SAP Crystal Reports .rpt 文件的 MCP 服务。

一个 MCP 服务，可让 AI 助手（Claude Code、Claude Desktop、Cursor，……）读取和编辑 SAP Crystal Reports .rpt 文件。

.rpt 是一种二进制格式，因此 AI 无法将其作为文本编辑。此服务封装了官方的 Crystal Reports .NET 运行时（引擎 + 进程内 Report Application Server），并将安全、结构化的编辑操作作为 MCP 工具公开。

工具

工具	功能
list_reports	列出文件夹中的 .rpt 文件
inspect_report	页面设置、表格 / SQL 命令 / 连接、链接、参数、公式、选择公式、分组、排序、节以及每个对象（位置、文本、绑定字段、字体），包括格式设置中隐藏的条件公式（抑制、颜色、数字格式……）
batch_edit	加载一次、备份一次、保存一次，运行多项编辑操作；要么全部成功，要么全部不生效
diff_reports	对两份报表进行结构差异比较（例如备份与编辑后的报表）
set_formula / delete_formula	编辑、创建或删除公式字段
set_selection_formula	记录或分组选择公式
add_parameter / set_parameter / delete_parameter	报表参数；set_parameter 可原地更改提示词、类型、多值或默认值，同时保留所有使用该参数的公式
add_group / delete_group	按字段分组（按班次、按天、按月……）；返回新建的组页眉 / 页脚节。小计使用组页脚中的公式，例如 Sum({T.Qty}, {T.Shift})
add_sort / delete_sort	记录排序（升序 / 降序）；按分组字段排序时，add_sort 会切换该组的排序方向
add_running_total / delete_running_total	运行总计（求和、计数、不同值计数、平均值、最小值、最大值）；可按记录、字段 / 分组值变化或公式计算，并可选择永不重置、按字段 / 分组重置或按公式重置
set_command_sql	替换现有 SQL Command 表的 SQL（实验性功能）
add_table	添加数据库表（OLE DB / ADO，例如 SQL Server 或 LocalDB），以便将其列放入报表；返回列清单
set_datasource	将表重新指向其他服务器 / 数据库，也可选择切换 OLE DB 提供程序（会持久保存）
remove_table	移除表 / 命令（受保护：只要仍有字段被使用，就会拒绝移除，除非指定 force）
set_text	更改文本对象的文本
set_text_with_fields	在新建或现有文本对象中插入含嵌入字段的文本，例如 Shift : {T.Shift} 或 Page {PageNumber} of {TotalPageCount}
set_object_props	位置 / 大小、字体、颜色、对齐方式、抑制、可增长；对于线条 / 方框，还可设置端点、线条样式 / 粗细 / 颜色和方框填充
add_line / add_box	添加水平 / 垂直线条和方框（填充、圆角），也可跨越到后续节
add_picture / replace_picture	插入图片，或替换图片（例如徽标），同时保留其名称、位置和大小
set_field_format	设置字段的数字 / 日期 / 时间 / 布尔值格式：小数位、千位和小数分隔符、负数、货币、零值文本、日期顺序 / 分隔符、12 / 24 小时制……或自定义格式（#,##0.00、yyyy-MM-dd HH:mm）
set_condition_formula	设置 / 清除条件公式（抑制、字体颜色、显示字符串、边框、数字格式……）
set_section_props	节高度、抑制、分页符、保持整体、背景
add_section / delete_section	添加节（例如第二个 Detail），或删除节（只要其中包含对象就会拒绝删除）
move_object	将对象移动到另一节，同时保留其名称、字体、格式和条件公式
add_subreport / set_subreport_links	插入另一份 .rpt 作为子报表并建立链接：主报表参数 → 子报表参数，或主报表字段 → 子报表字段（用于筛选子报表，例如按组筛选）
set_page_setup	纸张大小（A4、Letter、Legal……或自定义）、方向和页边距；返回可打印宽度
add_text_object / add_field_object / delete_object	添加或移除报表对象；字段对象也可显示特殊字段（RecordNumber、PageNumber、TotalPageCount、PageNofM、PrintDate、GroupNumber、FileName……）
verify_database	根据数据库检查报表：已不存在的列（以及使用这些列的对象）、类型变更、登录 / 提供程序问题。不会保存
export_report	运行报表并导出为 PDF / Excel / Word / CSV /……或 PNG / JPG 图片（每页一张，可选择 dpi 和 pages），以便 Agent 直接查看版面。图片导出通过 Windows 10 / Server 2016+ 内置的 PDF 渲染器生成；PNG 比 JPG 保留的文本更清晰，文件也更小。对于基于 DataSet / XML 的报表，或无需数据库的快速预览，可内联传入行数据（data）
位置和尺寸的单位为 twips（1440 = 1 英寸，567 ≈ 1 厘米），这是 Crystal 的原生单位。

所有工具都接受 subreport 参数，以便在子报表中操作。

安全

• 每次编辑都会先将原文件复制到同一目录下的 _rptmcp_backup/<name>_<timestamp>.rpt，然后才在原位置覆盖文件。传入 output_path 可改为写入新文件。
• 如果 delete_formula、delete_parameter、delete_running_total 和 remove_table 要删除的字段仍在使用中（字段对象、嵌入文本对象中的字段、公式、选择公式/条件公式、分组、排序、SQL 命令），这些工具会拒绝操作并列出使用位置。force: true 会同时删除绑定的对象。若没有这项保护，Crystal 会悄悄删除所有绑定到已删除公式的对象。

要求

• Windows
• .NET Framework 4.8
• SAP Crystal Reports runtime for .NET Framework（v13，64 位），或 SAP Crystal Reports for Visual Studio（建议使用 SP 20+）。可从 SAP 免费下载。该运行时是 SAP 的专有软件，不包含在本仓库中。
• 从源代码构建：.NET SDK 6+（构建目标为 net48）。

安装

1. 安装 SAP Crystal Reports 运行时（见「要求」）。
2. 通过以下任一方式获取 rpt-mcp：
   • Zip： 从 Releases 下载 rpt-mcp-<version>-win-x64.zip，解压到任意位置（例如 C:\Tools\rpt-mcp），然后在 MCP 客户端中注册 rpt-mcp.exe（见下文）。
   • MCP Bundle： 在支持 MCP Bundles 的客户端中打开 Releases 中的 rpt-mcp-<version>.mcpb，例如 Claude Desktop。
   • MCP Registry： rpt-mcp 已作为 io.github.ashafizullah/rpt-mcp 列入官方 MCP Registry。

从源代码构建

cd src
dotnet build -c Release
# -> src\bin\Release\rpt-mcp.exe

项目从 GAC（C:\Windows\assembly\GAC_MSIL）引用 Crystal 程序集。如果程序集位于其他位置，请使用 dotnet build -p:CrGacMsil=<folder> 覆盖路径。

对于 32 位 Crystal 运行时，请使用 -p:PlatformTarget=x86 构建。

使用 dotnet test RptMcp.sln -c Release 运行测试。报表测试请参阅 CONTRIBUTING.md。

在 MCP 客户端中注册

Claude Code：

claude mcp add rpt-mcp -- "C:\path\to\rpt-mcp.exe"

Claude Desktop / 其他客户端（mcpServers 配置）：

{
  "mcpServers": {
    "rpt-mcp": { "command": "C:\\path\\to\\rpt-mcp.exe" }
  }
}

数据库连接（可选）

编辑报表不需要数据库。export_report、set_command_sql 和 set_datasource 通常需要数据库，add_table 则始终需要（Crystal 会从服务器读取列列表）。 直接传入 server / database / user / password / integrated，或在 exe 旁创建 connections.json（也可以将 RPTMCP_CONNECTIONS 指向该文件），并传入 connection: "<name>"：

{
  "dev": { "server": "localhost\\SQLEXPRESS", "database": "Northwind", "integrated": true }
}

connections.json 已加入 git 忽略列表；切勿提交凭据。

示例提示词

• “检查 C:\reports\Invoice.rpt，并将标题改为 Tax Invoice，加粗，14pt。”
• “添加公式 {@FullName} = 名字 + 姓氏，并将其放在客户代码旁边的明细节中。”
• “将 C:\reports 下所有报表中的每个表都指向服务器 SQL02、数据库 SalesProd。”
• “从 (localdb)\MSSQLLocalDB 的数据库 Sales 中，将表 dbo.Orders 添加到空白的 Orders.rpt，并将 OrderNo 和 Total 放入明细节。”
• “按班次对生产报表分组，在组头中显示 Shift : n，并在组尾中显示 Qty/Good/Reject 小计。”
• “在报表页脚中添加按产品汇总的子报表，并将其链接到报表的日期和班次参数。”
• “将报表设为 A4 横向，并使用 RecordNumber 为行编号。”
• “使用 OrderNo = 1001 将 Invoice.rpt 导出为 PDF，以便我检查版面。”
• “将 Invoice.rpt 的第 1 页导出为 PNG，查看图片并修复所有重叠的列。”

提示

• 旧报表通常使用旧版 SQLOLEDB 提供程序，无法连接到 LocalDB 或仅支持 TLS 1.2 的服务器。使用 provider: "MSOLEDBSQL"（Microsoft OLE DB Driver for SQL Server）调用 set_datasource 可解决此问题。

限制

• 不支持创建新的 SQL Command。 进程内 Crystal 运行时会拒绝此操作，并报错“Failed to load database information”，尽管在同一连接上添加普通表可以成功。set_command_sql 只能编辑已存在的命令，且尚未在包含命令的报表中验证过。
• add_table 添加的表不带关联；报表包含多个表时，Crystal 会对它们执行交叉联接。目前不支持添加表关联。
• 可以检查和移动图表、交叉表和 OLAP 网格，但不能对其进行结构性编辑。
• 线条样式：运行时会拒绝 double，并将 dashed／dotted 线条绘制为极细线。图片以位图形式存储（透明区域会被填充为白色）。
• 直接绑定到运行总计的字段对象无法由运行时保存（SaveAs 会失败并显示“No error”），因此，add_field_object 会通过公式 {@Name} 显示 {#Name}，公式文本为 {#Name}。delete_running_total 也会移除该公式。
• 运行时无法创建空报表，因此新子报表会先作为独立的 .rpt 创建（例如，复制一份报表，然后使用这些工具对其进行精简），再通过 add_subreport 插入。子报表对象无法移动到其他节；请在正确的位置插入。
• 默认参数值是提示词中提供的选项；export_report 仍需在 parameters 中传入相应值。
• set_command_sql 和 set_datasource 会调用 Crystal 的表位置 API，该 API 会连接数据库以验证架构。
• 已在 Windows 11 和 SQL Server LocalDB 上使用 Crystal Reports 运行时 13.0.2000（x64）进行测试。

协议

通过 stdio 使用 JSON-RPC 2.0（以换行符分隔）。由于 Crystal 运行时只能在 .NET Framework 上运行，此处采用手动实现。日志写入 stderr。

许可证与法律声明

• rpt-mcp 基于 MIT License 发布。
• 这是一个独立项目，与 SAP SE 无关，也未获得其认可或赞助。SAP 和 Crystal Reports 是 SAP SE 在德国及其他国家／地区的商标或注册商标。此处仅将其用于描述兼容性。
• 本项目不随附 SAP Crystal Reports 运行时。每位用户都需自行从 SAP 安装，并遵守 SAP 的许可条款。SAP 表示，该运行时可免费用于客户端（桌面）应用程序。rpt-mcp 作为本地单用户进程运行，属于此类部署。如果将其作为多个用户都能访问的共享服务运行，请查看 SAP 对服务端应用程序的许可要求（例如 Crystal Reports Developer Advantage 许可证）。
• 第三方组件列于 THIRD-PARTY-NOTICES.md。