内容
# dSPACE VEOS MCP 服务器
dSPACE VEOS MCP 服务器允许您使用自然语言控制 [dSPACE VEOS](https://www.dspace.com.cn/home/products/sw/simulation_software/veos.cfm) 模拟器。通过启用大型语言模型（LLM）与 VEOS 模拟器及其日志文件交互。
## 先决条件
MCP 服务器必须与以下软件安装在同一台机器上：
- dSPACE VEOS
可选的开发者关注的设置：
- Python 3.12 或更高版本。
- `uv`，Python 包和项目管理器，用于创建环境、安装依赖项和从源代码运行服务器。从官方 Astral 文档安装 `uv`：https://docs.astral.sh/uv/getting-started/installation/
## 入门指南
有两种方法可以安装 VEOS MCP 服务器：
- 直接从最新的 GitHub 版本。参考 [安装最新的 GitHub 版本](#安装最新的-github-版本)。
- 使用 `uv` 进行开发者关注的设置，直接从源代码运行服务器。参考 [开发者关注的设置](#开发者关注的设置)。
您可以通过快速提示轻松验证安装，例如：`给我 VEOS 模拟器的状态`。
### 安装最新的 GitHub 版本
1. 从最新的 GitHub 版本中下载 `veos-mcp-windows.zip`。存档中包含服务器可执行文件 `veos-mcp.exe`。
2. 按照 MCP 客户端的 MCP 服务器安装说明进行操作（参见 [Claude](https://code.claude.com/docs/en/mcp-quickstart)、[Codex](https://developers.openai.com/codex/mcp)、[GitHub Copilot](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp) 等等文档）。
这里提供一个 GitHub Copilot 的示例安装，作为 `.vscode/mcp.json` 条目，指向提取的可执行文件：
```json
{
"servers": {
"VeosMCP": {
"type": "stdio",
"command": "<PATH_TO_EXTRACTED_RELEASE>\\veos-mcp.exe",
"args": [
"--veos-version",
"<VEOS_VERSION>"
]
}
}
}
```
### 开发者关注的设置
1. 克隆此仓库。
2. 创建项目环境并从 `pyproject.toml` 安装依赖项。
```shell
uv sync # for minimal setup
````
```shell
uv sync --extra dev # for full developer setup
```
3. 按照 MCP 客户端的 MCP 服务器安装说明进行操作（参见 [Claude](https://code.claude.com/docs/en/mcp-quickstart)、[Codex](https://developers.openai.com/codex/mcp)、[GitHub Copilot](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp) 等等文档）。
使用 `uv run` 直接从此仓库运行服务器（参见 [VeosMCP.cmd](VeosMCP.cmd) 作为参考）。
您也可以直接从 MCP 客户端安装调用 `VeosMCP.cmd` 脚本，如下所示的示例 `.vscode/mcp.json` 条目：
```json
{
"servers": {
"VeosMCP": {
"type": "stdio",
"command": "<PATH_TO_REPOSITORY>\\VeosMCP.cmd",
"args": [
"--veos-version",
"<VEOS_VERSION>"
]
}
}
}
```
有用的开发命令：
```shell
uv run pytest # 运行测试
uv run ruff format src tests # 运行格式化程序
uv run ruff check src tests # 运行 linter
uv build # 构建 wheel
```
## 配置
VEOS MCP 服务器支持以下参数。它们可以作为 JSON 配置中 `args` 列表的一部分提供：
| 参数 | 描述 |
|--------|-------------|
| `--veos-version <VEOS_VERSION>` | 允许您针对特定版本的 VEOS 安装。支持以下版本格式：`26.1`、`26-A`、`26.2`、`26-B`、`2026-A` 和 `2026-B`。 |
| `--veos-bin-path <PATH>` | 允许您通过提供 `/bin` 文件夹来针对特定 VEOS 安装。 |
如果未提供这些参数，VEOS MCP 服务器将使用最新的已安装 VEOS 版本。
## 工具
> 工具、标题和参数的完整列表。工具描述可能在此处缩写；有关完整的工具描述，请使用 [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) 或直接查看源代码下的 [src/veos_mcp/tools](src/veos_mcp/tools)。
<details>
<summary><b>日志文件访问</b></summary>
- **veos_list_all_available_log_files**
- 标题：列出所有可用的 VEOS 日志文件
- 描述：列出所有可用的 VEOS 日志文件，包括 bus 日志文件（pcapng）和模拟日志文件。
- 参数：无
- 只读：**true**
- **veos_get_log_file**
- 标题：获取 VEOS 日志文件资源链接
- 描述：获取指定 VEOS 日志文件的资源链接，可以是 bus 日志文件（pcapng）或模拟日志文件。首先调用 `veos_list_all_available_log_files` 获取可用日志文件列表。
- 参数：
- `log_file_name`（字符串）：要返回为资源链接的 VEOS 日志文件名。文件名以 `.pcapng` 结尾的返回为 bus 日志资源；其他文件名返回为模拟日志资源。
- 只读：**true**
</details>
<details>
<summary><b>模拟器控制</b></summary>
- **veos_status_info**
- 标题：获取 VEOS 模拟器状态信息
- 描述：获取 VEOS 模拟器的当前状态信息，包括模拟器状态。状态可以是以下之一：未加载、停止、运行、暂停、停止、终止。
- 参数：无
- 只读：**true**
- **veos_load**
- 标题：将 `.osa` 仿真模型加载到 VEOS 中
- 描述：将由 `.osa` 文件指定的仿真模型加载到 VEOS 模拟器中。如果成功，此操作将模拟器转换为停止状态。
- 参数：
- `osa_path`（字符串）：要加载到 VEOS 中的 `.osa` 仿真模型文件路径。
- 只读：**false**
- **veos_start**
- 标题：启动 VEOS 仿真
- 描述：启动 VEOS 仿真。此操作将模拟器从停止或暂停状态转换为运行状态。
- 参数：无
- 只读：**false**
- **veos_stop**
- 标题：停止 VEOS 仿真
- 描述：停止 VEOS 仿真。此操作将模拟器从运行或暂停状态转换为停止状态。
- 参数：无
- 只读：**false**
- **veos_apply_config**
- 标题：配置 VEOS 模拟器
- 描述：在不启动仿真的情况下设置和配置 VEOS 仿真。工具调用中省略的任何参数都将在 VEOS 配置中保持不变。
- 参数：
- `stop_time`（字符串，可选）：仿真在秒单位的 SimulationTime 中的期望停止时间。如果省略，现有停止时间配置将保持不变。
- `acceleration_factor`（字符串，可选）：仿真加速因子。`Infinity` 或 `0` 表示尽可能快；`1` 表示实时速度。如果省略，现有加速因子配置将保持不变。
- `ip_address`（字符串，可选）：VEOS 模拟器的 IP 地址。如果未由 VEOS 配置指定，则默认为本地主机 `127.0.0.1`。如果省略，现有 IP 地址配置将保持不变。
- `bus_log`（布尔值，可选）：启用 bus 日志记录时为 true，禁用 bus 日志记录时为 false。更改在执行 `veos_load` 后生效。
- `sim_log`（布尔值，可选）：启用仿真日志记录时为 true，禁用仿真日志记录时为 false。更改在执行 `veos_load` 后生效。
- 只读：**false**
</details>
<details>
<summary><b>系统提取</b></summary>
- **veos_get_all_signals_and_ports**
- 标题：从 VEOS `.osa` 仿真系统中获取信号/端口列表
- 描述：从给定的 `.osa` 文件和信号之间的现有连接中获取可用信号/端口列表。在 VEOS 仿真系统的上下文中，信号和端口经常互换使用。
- 参数：
- `osa_path`（字符串）：从中读取信号、端口和现有连接的 `.osa` 仿真模型文件路径。
- 只读：**true**
</details>
<details>
<summary><b>系统修改</b></summary>
- **veos_add_signal_connections**
- 标题：连接 JSON 文件中给出的信号
- 描述：添加 JSON 文件中列表中指定的信号连接，添加到给定的 VEOS `.osa` 文件中。信号引用是信号路径。
- 参数：
- `osa_path`（字符串）：要修改的 `.osa` 仿真模型文件路径。
- `json_path`（字符串）：包含要添加的信号连接的 JSON 文件路径。
- 只读：**false**
- **veos_remove_signal_connections**
- 标题：断开 JSON 文件中给出的信号连接
- 描述：从给定的 VEOS `.osa` 文件中删除 JSON 文件中列表中指定的信号连接。信号引用是信号路径。
- 参数：
- `osa_path`（字符串）：要修改的 `.osa` 仿真模型文件路径。
- `json_path`（字符串）：包含要删除的信号连接的 JSON 文件路径。
- 只读：**false**
</details>
## 资源模板
<details>
<summary><b>日志文件</b></summary>
- **veos://logs/sim/{log_file_name}**
- 标题：VEOS 日志文件
- 描述：用于访问 VEOS 仿真日志文件的内容的资源。如果指定的日志文件不存在，则返回错误。
- 参数：
- `log_file_name`（字符串）：要读取的 VEOS 仿真日志文件名。
- MIME 类型：`text/plain`
- **veos://logs/bus/{log_file_name}**
- 标题：VEOS Bus 日志文件
- 描述：用于访问 VEOS bus 日志文件的内容的资源。如果指定的日志文件不存在，则返回错误。
- 参数：
- `log_file_name`（字符串）：要读取的 VEOS bus 日志文件名。
- MIME 类型：`application/vnd.tcpdump.pcap`
</details>
## 示例提示
以下示例提示展示了如何与 VEOS MCP 服务器交互以执行典型的 VEOS 任务：
- `加载 `my.osa` 并运行仿真 5 秒。`
- ` `my.osa` 中有哪些信号未连接？进行最佳匹配并相应地创建连接。`
- `断开 `my.osa` 中所有来自 EngineModel FMU 的信号。`
- `启用 bus 日志记录并启动仿真，然后检查 bus 日志中是否有任何 TCP 传输。`
## 添加 MCP 工具
MCP 工具保存在 `src/veos_mcp/tools/` 中，并使用从 `veos_mcp.runtime` 模块导入的共享 FastMCP 实例注册。
要添加 MCP 工具，请执行以下步骤：
1. 将工具实现添加到 `src/veos_mcp/tools/` 中现有的模块或创建新模块。
2. 使用 `@mcp.tool(...)` 将工具注册到共享的 FastMCP 实例中。提供清晰的工具名称、标题和描述，并使用 `ToolAnnotations` 描述工具是否为只读、破坏性、幂等或开放世界。
3. 使用 `get_cli().run_sim(...)` 或 `get_cli().run_model(...)` 定义 VEOS CLI 操作。
4. 如果创建新工具模块，请从 `src/veos_mcp/tools/__init__.py` 导入它：
```python
from veos_mcp.tools import new_module as new_module
```
还要将新模块添加到 `__all__`，否则在服务器启动时不会导入该模块。
5. 在 `tests/tools/` 下添加或更新测试以验证直接 Python 函数行为。
6. 将新工具名称添加到 `tests/test_mcp_surface_smoketest.py` 中的 `expected_tools`。这确保了 MCP stdio 表面测试验证工具已注册。
7. 运行 `pytest` 和 `ruff` 以验证实现、格式化代码并检查 linting 问题。
这里是一个最小的工具示例：
```python
from veos_mcp.runtime import mcp
@mcp.tool(
name="veos_new_tool",
title="新工具",
description="扩展 VEOS MCP 服务器的新工具。"
)
def veos_new_tool() -> str:
return "来自新 VEOS MCP 服务器工具的问候！"
```
