Skip to main content
Glama

SAP Smart Forms MCP Server

sap-smartforms-mcp is an offline-first Model Context Protocol (MCP) server for SAP Smart Forms. Use it to inspect and edit native Smart Forms XML, generate grouped reports from JSON, review Word template structure, and check PDF output on your own machine. No SAP login, AI API key, or hosted service is required for the offline tools.

Install · MCP client setup · Grouped table example · FAQ · AI documentation index

**中文简介:**适用于 SAP Smart Forms(智能表单)的本地 MCP 服务。支持原生 XML 检查、修改预审、差异对比和导出;可从 JSON 生成动态分组表,支持续页分组名、页尾边框及数据行页保护。默认不连接 SAP。可选 RFC 适配器仅用于按授权操作开发或测试环境。

What it can do

  • open, inspect, search, edit (exact-locator, reviewed), clone, diff and validate native Smart Forms XML;

  • export reviewed bundles with a full change review and a READY marker;

  • analyze Word templates and build a native form draft from a strict specification;

  • generate grouped dynamic tables from JSON, with position-coded names and human-readable captions;

  • check printed PDFs against expected text and regions (bbox JSON, or PDF via PDFKit on macOS / optional pdfplumber).

By default the server never connects to SAP and never loads credentials. An optional, config-driven SAP adapter (below) must be enabled explicitly. All document content is treated as untrusted data.

Related MCP server: dsh-document-editor

Install

Use Python 3.10+ on macOS or Linux. Windows is not verified. Clone the repository, then run the installation commands from its root:

git clone https://github.com/miaomiao-wzs/sap-smartforms-mcp.git
cd sap-smartforms-mcp
python3 -m venv .venv
.venv/bin/python -m pip install .

The offline core has no third-party runtime dependencies. For PDF text and coordinate checks without PDFKit, install .[pdf] instead of .. The macOS PDFKit backend also needs the Apple developer tools.

Register in an MCP client

The server uses local stdio. In an MCP client that supports local subprocesses (for example, Claude Desktop or Cursor), use a configuration like the one below. Replace each path with an absolute path on your machine; create the input directory before starting the server. Client-specific menus and config file locations can differ.

{
  "mcpServers": {
    "sap-smartforms": {
      "command": "/absolute/path/to/.venv/bin/sap-smartforms-mcp",
      "args": [
        "--read-root", "/path/to/input-xml",
        "--output-root", "/path/to/exports",
        "--state-dir", "/path/to/state"
      ]
    }
  }
}

--read-root may be repeated. Files outside the read roots are refused.

Quick start: work on a local form

  1. Export the native Smart Forms XML from SAP GUI to the directory configured as --read-root.

  2. In the MCP client, ask the server to open the XML, inspect the draft, and plan_edit the exact changes.

  3. Review the diff before apply_plan. Then run validate, review_export, and export to a new bundle.

  4. The bundle is local review evidence, not an SAP import or runtime acceptance result.

Quick start: build a grouped table from JSON

The example examples/grouped-table.json contains only synthetic layout data. From the repository root, run:

.venv/bin/sap-smartforms-build examples/grouped-table.json grouped-form.xml

The command refuses to overwrite an existing file. You can also call smartforms_validate_spec first in an MCP client. Open the generated XML with smartforms_open (the XML must be under a configured read root).

  • tables declares the Smart Forms TABLES parameter and the row structure it references. Before using the example in SAP, replace ZS_DEMO_ITEM with an existing DDIC structure, and ZDEMO_STYLE/P1 with an existing style/paragraph. The example expects four character-like fields: GROUP_NAME, ITEM_NAME, DESCRIPTION, RESULT.

  • dynamic_table belongs in the main window. Column widths in mm must add up to the window width; the first column is group_field. Pass rows for the same group contiguously. The form groups runs of adjacent equal names; it does not sort the input. A blank group name is treated as an individual row.

  • The first column simulates vertical merging with border rules. It suppresses internal lines, prints the group label on a middle row, and attempts to repeat the label on a continuation page. A footer row closes the group border on a page break; it may consume vertical space. The four data-row types request SAP page protection (PROTECT=X). The fixed column titles are not a repeating table header.

  • Use label on fixed cells and caption on windows or dynamic tables for descriptions. Labelled fixed cells get position-coded technical names; use short window names to avoid exceeding SAP name lengths.

  • To test in SAP, separately import and check the XML in a development/test system, then preview synthetic data: an empty table, a single row, multiple groups, and a long group spanning pages. Verify continuation labels, page-end borders, and rows with long wrapped text. Do not assume a row taller than an entire page can be kept together. This staging package was not tested against your SAP system.

Tools (19)

open, inspect, find_field, edit, clone, diff, validate, export, preflight_replace, plan_edit, apply_plan, review_export, check_print, pdf_inspect, pdf_compare, analyze_word, validate_spec, plan_create, apply_create_plan (each exposed as smartforms_<name>).

Optional SAP adapter (development/test systems only)

Start with --sap-config /absolute/path/sap-config.json to add 7 tools: sap_capabilities, sap_read, sap_plan, sap_execute, sap_status, sap_readback, sap_render (26 tools in total). See examples/sap-config.example.json.

  • Everything about your system lives in your own config and env file: SID, client, local package ($... only), allowed target name patterns, function module names. Nothing is built in. The config holds paths, never credentials; RFC credentials are read from your env file (SAP_ASHOST, SAP_SYSNR, SAP_CLIENT, SAP_USER, SAP_PASSWD, ...) by the bundled node-rfc bridge and are never returned or logged. Requires Node.js and node-rfc (point node_rfc_dir at where it is installed).

  • Safety model: you must set confirm_non_production: true; targets must match allowed_targets; the operation is create-only (an existing target is refused); sap_execute needs the exact confirmation string printed by sap_plan; every plan is claimed permanently, so a failed or unknown run is never retried; the target is read back and compared against the reviewed payload with only exact, individually checked differences allowed.

  • A ready-made, generic ABAP helper function group (read + publish) is in abap/; see abap/README.md.

  • Your SAP side must provide function modules named in functions. Contract: read(IV_FORMNAME) -> EV_SYSID, EV_CLIENT, EV_STAGE, EV_SUCCESS, EV_EXISTS, EV_XML, EV_SHA256; publish(IV_TARGET, IV_SOURCE, IV_XML, IV_PAYLOAD_SHA256) -> EV_SYSID, EV_CLIENT, EV_STAGE, EV_SUCCESS, EV_STORED, EV_GENERATED; optional render(IV_FORMNAME, IV_<param>...) -> ..., EV_PDF, EV_PDF_SIZE, EV_PAGES, EV_OTF_ROWS, EV_SPOOL_COUNT. Each must itself refuse other systems/clients and non-allowed objects.

  • Using an ADT-based MCP server (e.g. adt-abap) instead? This server cannot call another MCP server. Use it offline: export a reviewed bundle (form.xml) and use a separately authorized import method supported by your SAP system. Do not assume that an ADT client can import Smart Forms XML.

  • The adapter is tested only against a fake bridge. Verify it on your own test system before relying on it.

Limits

Offline checks do not prove SAP import, generation, activation or print quality. Word tables, images and unsupported layouts are blocked rather than approximated by the Word creation workflow. Use the direct JSON builder for grouped tables. The bundled SAP publish helper is for reviewed copies with unchanged code and interface; it does not publish a newly generated dynamic form. Do not relax that guard to import a draft. Actual output depends on SAP release, DDIC, styles, device type and data. No automatic overwrite or physical printing is provided by the grouped-table builder.

FAQ

Can I edit SAP Smart Forms without connecting to SAP? Yes. Export native .xml from SAP GUI first, then use the local MCP review and editing tools. The server does not activate a form or validate it against SAP in offline mode.

How do I keep a dynamic table row from splitting across pages? The JSON builder requests Smart Forms page protection (PROTECT=X) on data rows. Confirm the result in SAP print preview with your actual style, device and row lengths. In particular, test rows taller than the usable page area separately.

Can I use this to convert any Word document to SAP Smart Forms? No. Word analysis identifies layout and dependencies. The reviewed creation workflow rejects unsupported Word layout, including Word tables and images. Use the JSON builder for explicitly designed grouped tables.

Does this work with GitHub Copilot or other AI tools? Repository documentation can be read independently of the server. To call the server's tools, use a client that supports local stdio MCP and configure the executable and paths. A GitHub URL is not an MCP endpoint.

Tests

pip install -e .
python -m unittest discover -s tests

License

MIT. This is an independent community project, not an official SAP product.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      B
      maintenance
      Enables local, offline document extraction and manipulation—PDF first but also HTML, DOCX, XLSX, PPTX, EML, EPUB, Markdown, and plain text—through tools for probing, locating, extracting, converting, assembling, OCR, protecting, and redacting documents, with nothing leaving the machine.
      7
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables creating, reading, editing, and verifying PDF, Word, Excel, and PowerPoint documents through MCP tools that return structured results. It preserves source files by default for edits and supports local stdio operation without network requests.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables extracting text, table grids, and images from HWPX reports and rebuilding them using a sample document's formatting, with tools for format inspection, content-preservation checks, PDF conversion, and page-fit adjustments.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables source-preserving import and analysis of EPLAN export reports (devices, connections, PLC I/O, terminals, cables, parts, network, pages) as immutable queryable snapshots, plus inspection of DXF/PDF/DWG drawings and derivation of electrical project evidence. Works offline without EPLAN, supporting querying, duplicate/endpoint checks, revision comparison, and verified JSON export.
      MIT