MCP SAP GUI Server

MCP SAP GUI

为一个已配置的 SAP GUI for Windows 会话提供 MCP 工具。此修复使用 Python MCP SDK 2.1.1，通过 stdio 同时支持已发布的 2026-07-28 协议（server/discover）和旧版初始化方式。原有的 7 个工具名称仍可使用；COM 控制工具和可选的 GuiXT InputScripts 为图像识别提供了替代方案。

安装并选择会话

在交互式 Windows 桌面上使用 Python 3.11–3.13，并确保已安装获许可的 SAP GUI、配置好的 SAP Logon 连接，以及由管理员安装并启用的 SAP GUI 脚本功能。此实现面向公开的 SAP GUI 8.00/8.10 脚本接口。CI 会检查 Python 和 Windows 绑定；CI 尚未在实际的 SAP 8.00/8.10 系统上进行测试。请查阅 SAP 当前的平台／补丁矩阵，以确认适用于你的安装环境。此工具不支持 SAP GUI for Java 或无头 SAP 桌面。

python -m pip install .
Copy-Item .env.example .env
# Edit .env to select the intended session.
python -m sap_gui_server.server

为了便于重复开发，请使用 uv sync --frozen --python 3.13、uv run pytest 和 uv build。build.bat 从本地源代码构建；setup.bat 会创建模板，不会提示输入或回显密码。Node 为可选项，仅在运行 run.bat debug（MCP Inspector）时需要。

已通过身份验证的现有会话（包括 SSO）无需密码：

SAP_SESSION_ID=/app/con[0]/ses[0]
# Optional assertion, checked against the authenticated SAP user:
SAP_USER=YOUR_SAP_USER

请使用专供自动化使用的会话的准确 ID。SAP GUI 的脚本录制器会显示连接／会话索引。服务绝不会随意选择活动窗口或第一个现有会话。若要改为打开新连接，请省略 SAP_SESSION_ID，并将 SAP_CONNECTION 设为 SAP Logon 中对应描述的准确文本。新连接可以使用现有的 Windows／SAP SSO；可选的 SAP_CLIENT、SAP_USER、SAP_PASSWORD 和 SAP_LANGUAGE 会通过 COM 填写登录控件。密码绝不会作为进程参数或日志条目。

SSO 使用本地 Windows／SAP 会话的身份。它不会推断聊天用户的身份、交换 ChatGPT 令牌，也不会实现远程 Microsoft 代理身份验证。请在每个预期的 Windows 用户账户下运行单独的本地服务；此处没有共享的远程身份验证端点。这一区别是问题 #8 尚待解决的集成要求之一。

若使用自定义安装，请将 SAP_GUI_PATH 设为已安装的 saplogon.exe 或其所在目录，例如 C:\Program Files\SAP\FrontEnd\SAPGUI。当 SAP Logon 的 COM 对象未运行时，此路径会用于启动 SAP Logon。默认情况下要求 SAP Logon 已在运行，以避免猜测 32 位注册表路径（#3）。

脚本读取文本时使用 SAP 控件属性，而非 Win32 窗口标题，以解决 64 位文本读取问题报告（#6）。密码控件会被隐藏。只读脚本策略可能允许读取但拒绝写入；服务会报告此类失败，绝不会更改 SAP 安全设置。SAP 的脚本要求和GUI 文档介绍了安装和管理员先决条件。

工具

工具	操作
launch_transaction	在所选会话中启动事务代码
end_transaction	结束该会话的事务，同时保留其他会话和 SAP Logon
sap_click、sap_move_mouse	使用相对于 SAP 窗口的物理屏幕像素坐标
sap_type	使用现有的 WScript SendKeys 语义，包括显式特殊键
sap_scroll	在该窗口内向上或向下滚动
save_last_screenshot	将最近请求的屏幕截图保存到已配置的输出根目录中
sap_get_screen	读取最多 300 个 COM 控件的 ID、类型和文本；密码字段会被隐藏
sap_set_field	在相对于会话的 SAP 文本字段中设置原样文本
sap_press	按下 SAP COM 按钮
sap_send_vkey	发送有文档说明的 SAP 虚拟键（0 表示 Enter）
sap_run_guixt_script	向确切的会话窗口提交预安装的 InputScript

控件 ID 必须以 wnd[N] 开头，例如 wnd[0]/usr/ctxtFIELD；跨会话的绝对 ID 会被拒绝。这些是公开的 SAP ActiveX/COM 脚本操作（#2），使用类型化方法，而非任意 COM 方法求值。请参阅 SAP 的应用程序 API和会话 API。

支持屏幕截图的工具接受 return_screenshot：none（默认）、as_file、as_base64、as_imagecontent 或 as_imageurl。最后一种拼写仍保持兼容，但现在返回有效的嵌入式 PNG blob 资源，而非虚假的可远程检索 URL。屏幕截图使用物理像素，不会进行双重 DPI 缩放，且限制为 3000 万像素 / 7 MB。文件写入前，SAP_OUTPUT_ROOT 必须是已存在的目录；as_file_target_folder 必须解析到该目录内。保存操作绝不会覆盖已有文件。默认情况下不会截取屏幕截图，因此调用 save_last_screenshot 前必须先显式请求屏幕截图。

GuiXT（#1）

请根据已获许可的配置安装 GuiXT/InputAssistant。将 GUIXT_PATH 设置为 guixt.exe 的绝对路径，并将 GUIXT_SCRIPT_ROOT 设置为包含已审核 InputScript 的现有目录；脚本应使用 read_order.txt 之类的简单名称。在 GuiXT 的配置文件中显式启用 AllowExternalInput Yes；服务不会修改此设置。工具接受脚本名称、验证根目录边界，并使用 findsession=hwnd:'…' 调用 GuiXT，指定所选 SAP 窗口。不会使用 shell 或调用方提供的命令片段。

GuiXT 提交是异步的。成功结果表示外部调用已被接受，并不代表业务流程已完成。发出更多输入前，请检查同一会话以及任何特定于脚本的输出。对于已被 GuiXT 接受的脚本，不会自动重试，也没有通用的取消机制。请参阅供应商的外部 InputScript 规范，其中包括在 2026 Q1 1 引入的选择启用要求。

生命周期与迁移

所有 COM 工作都在一个串行的 STA 工作进程中运行。SAP_OPERATION_TIMEOUT 默认值为 30 秒（1–120）。取消操作或达到截止时间时，只会终止此服务自身的工作进程，并拒绝后续工作，直到重启 MCP 服务。已发出的 SAP 操作无法回滚；恢复操作前请检查会话。不再使用 taskkill、进程名称匹配、全局终止 SAP 或自动处理多重登录弹窗。关闭 MCP 会释放句柄，但保持 SAP 会话打开。显式调用 end_transaction 可能会丢弃所选事务中的未保存工作。

执行失败时会返回 isError=true；无效输入和未知工具遵循 SDK 错误语义；标准输出仅包含 MCP JSON-RPC。不会记录工具参数、表单文本、凭据或 COM 异常详情。本地 stdio 进程拥有其 Windows 用户的桌面权限。请使用专用自动化会话，并确保输出目录和脚本目录由该用户控制。

0.2 版替换了有问题的 SDK1 构造函数、装饰器和进程级控制行为。SAP_SYSTEM 已由 SAP_CONNECTION（Logon 描述）或 SAP_SESSION_ID 取代；密码为可选项。现在文件输出必须指定根目录。使用内部控制器方法的旧代码应迁移到具名 MCP 工具。集成助手使用调用它的 Python 解释器；请从包含该软件包的环境中运行它。

验证与 Docker

uv run ruff check .、uv run ruff format --check .、uv run pytest 和 uv build 用于验证源代码、受控 COM 模拟、超时/取消、真实子进程的现代/旧版协议会话、已安装软件包的发现能力以及错误行为。Windows CI 会导入原生绑定并捕获一个可丢弃的测试窗口。它不会登录 SAP、在真实系统上运行事务，也无法证明你的环境中的 SSO/GuiXT 可用。

Dockerfile 现在基于此代码库构建，并运行非 root 的协议/发现镜像。Linux 容器无法访问需要许可的交互式 Windows SAP GUI。该镜像中的 SAP 工具调用会返回明确的平台错误；自动化请使用原生 Windows 软件包。此更改修正了 #4 中无效的 Dockerfile，但并不代表 SAP 已实现容器化，也不表示 Glama 部署已验证。更新或声称已上架第三方目录属于独立的外部工作。

投入生产前，请在一次性 SAP 客户端上：验证选定的 SSO 身份和可选的不匹配断言；在你的 GUI 补丁版本上读取文本；启动一个无害事务，并验证另一个已打开的会话不受影响；测试一个控件、截图和 GuiXT 脚本；取消一个长时间运行的请求，并确认没有关闭无关进程。记录 GUI 版本、补丁、Windows 版本、脚本策略和结果。在完成测试之前，这些原生 SAP 验收关卡仍需明确列出。