Skip to main content
Glama
README.md
# 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](#install) · [MCP client setup](#register-in-an-mcp-client) · [Grouped table example](#quick-start-build-a-grouped-table-from-json) · [FAQ](#faq) · [AI documentation index](llms.txt)

**中文简介:**适用于 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.

## Install

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

```bash
git clone https://github.com/miaomiao-wzs/sap-smartforms-mcp.git
```

```bash
cd sap-smartforms-mcp
```

```bash
python3 -m venv .venv
```

```bash
.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.

```json
{
  "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](examples/grouped-table.json) contains only synthetic layout data.
From the repository root, run:

```bash
.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

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

## License

[MIT](LICENSE). This is an independent community project, not an official SAP product.