<!--
╔══════════════════════════════════════════════════════════════════════╗
║  DreamSeed 种梦计划 — AI创造者大赛  官方 README 模板                ║
║                                                                      ║
║  使用说明：                                                          ║
║  1. 将本模板放在参赛仓库根目录 README.md 的顶部                       ║
║  2. 头图使用 DreamField 官方公开活动图片地址                         ║
║  3. 请保留 DREAMFIELD_README_HEADER_START / END 标识                 ║
║  4. 分割线以下供创作者自由编写项目内容                               ║
╚══════════════════════════════════════════════════════════════════════╝
-->

<!-- DREAMFIELD_README_HEADER_START -->

<p align="center">
  <a href="https://www.dreamfield.top">
    <img src="https://www.dreamfield.top/dream-field/contest-readme/assets/dreamseed-readme-banner.png" alt="DreamSeed 种梦计划参赛作品" width="100%" />
  </a>
</p>

<!-- DREAMFIELD_README_HEADER_END -->


# xs-studio-mcp

`xs-studio-mcp` is a Model Context Protocol server for `XS Studio.exe`. It keeps the public MCP interface of `@codesys/mcp-toolkit`, and adds an XS-specific `create_dut` tool for `ST / FB / DUT` generation workflows.

## What it exposes

- Resources
  - `codesys://project/status`
  - `codesys://project/{+project_path}/structure`
  - `codesys://project/{+project_path}/pou/{+pou_path}/code`
- Toolkit-compatible tools
  - `open_project`
  - `create_project`
  - `save_project`
  - `create_pou`
  - `set_pou_code`
  - `create_property`
  - `create_method`
  - `compile_project`
- XS extension
  - `create_dut`

## Prerequisites

- XS Studio with scripting support
  - Default executable path on this machine:
    `D:\Program Files\XS Studio\CODESYS\Common\XS Studio.exe`
  - Default detected profile:
    `XS Studio V2.3.2`
- Python 3.11

## Setup

```powershell
uv python install 3.11
uv venv --python 3.11 .venv
uv pip install --python .\.venv\Scripts\python.exe -e .
```

## Run

```powershell
.\.venv\Scripts\xs-studio-mcp-tool.exe
```

By default each script call starts XS Studio and closes the launched process after the script reports completion. On this XS Studio build, project scripting works more reliably with the visible UI than with `--noUI`:

```powershell
$env:XS_STUDIO_RUN_WITH_UI = "1"
```

To avoid opening one XS Studio window per MCP tool call, enable the reusable scripting agent. The first call opens one MCP-managed XS Studio window; later calls reuse that window through a temp-file request queue:

```powershell
$env:XS_STUDIO_RUN_WITH_UI = "1"
$env:XS_STUDIO_REUSE_WINDOW = "1"
```

The agent files are stored under `%TEMP%\xs_studio_mcp_agent\...` by default. Override that with `XS_STUDIO_AGENT_DIR` if needed. To stop the reusable agent, close the XS Studio window, create a file named `stop` inside the agent directory, or run `examples\packml\stop_xs_agent.cmd`.

Optional flags:

```powershell
.\.venv\Scripts\xs-studio-mcp-tool.exe `
  --codesys-path "D:\Program Files\XS Studio\CODESYS\Common\XS Studio.exe" `
  --codesys-profile "XS Studio V2.3.2" `
  --workspace "D:\Projects\XS-MCP" `
  --template-path "C:\Users\zhouweihai\Desktop\未命名2\未命名2.project"
```

## Cursor / Claude MCP config

See [docs/mcpServers.sample.json](/d:/Projects/XS-MCP/docs/mcpServers.sample.json).

The local-repo form is:

```json
{
  "mcpServers": {
    "xs_studio_local": {
      "command": "D:\\Projects\\XS-MCP\\.venv\\Scripts\\xs-studio-mcp-tool.exe",
      "args": [
        "--codesys-path",
        "D:\\Program Files\\XS Studio\\CODESYS\\Common\\XS Studio.exe",
        "--codesys-profile",
        "XS Studio V2.3.2",
        "--workspace",
        "D:\\Projects\\XS-MCP",
        "--template-path",
        "C:\\Users\\zhouweihai\\Desktop\\未命名2\\未命名2.project"
      ]
    }
  }
}
```

## Demo project

The demo project lives at [examples/hello_xs/HelloXs.project](/d:/Projects/XS-MCP/examples/hello_xs/HelloXs.project). `create_project` defaults to `C:\Users\zhouweihai\Desktop\未命名2\未命名2.project` on this machine, and falls back to XS Studio `Standard.project` if no configured template is available. The demo is then extended with:

- `Application/MAIN`
- `Application/FB_Demo`
- `Application/FB_Demo/Execute`
- `Application/FB_Demo/State`
- `Application/DUT_RunMode`

PackML demo:

```powershell
examples\packml\run_packml_demo_admin.cmd
```

This demo runs elevated, enables `XS_STUDIO_REUSE_WINDOW=1`, creates a timestamped project under `examples\packml`, and should leave only one MCP-managed XS Studio window open.

## Troubleshooting

- Path with spaces
  - This implementation quotes executable, profile, and script paths explicitly. Keep `--codesys-path`, `--codesys-profile`, and `--workspace` as separate MCP args in client config.
- Wrong profile
  - Verify `--codesys-profile` matches the installed profile name exactly.
- Script engine failure
  - Check tool output for `SCRIPT_ERROR` details and verify XS Studio scripting is installed.
- Compile failure
  - `compile_project` inspects XS Studio message objects after the build and returns MCP error output when compiler errors are present.