内容
# Simulink MCP 服务器
一种模型上下文协议（MCP）服务器，通过共享的MATLAB引擎连接，为VS Code代理提供全面的MATLAB和Simulink功能。
## 🚀 快速入门（5分钟）
```powershell
# 1. 运行自动安装程序
.\install.ps1
# 2. 启动带有共享引擎的MATLAB
.\start_matlab.ps1
# 或手动在MATLAB中：matlab.engine.shareEngine('SimulinkMCP')
# 3. 重新加载VS Code（Ctrl+Shift+P → "Reload Window"）
# 4. 在MATLAB中打开Simulink模型
# 5. 向GitHub Copilot提问：
# "我当前正在编辑哪个模型？"
# "在MATLAB中创建一个10x10的魔方矩阵"
# "计算我的矩阵A的特征值"
```
**📖 完整教程：** [GETTING_STARTED.md](GETTING_STARTED.md)
**🔧 详细安装：** [INSTALL.md](INSTALL.md)
## 功能
### 便携式代理技能
- 适用于MATLAB、Simulink和基于模型的 workflows的`.agents/skills/`目录：调试、测试、代码审查、应用程序构建、现代化、Live Scripts、数据库访问、模型构建、仿真、需求草稿、算法规格和工厂模型规格。
- 技能仅为纯文本指导和参考模板；该仓库在其本地源可见的服务器工具中保留MCP执行。
### 🆕 MATLAB代码执行（新增！）
- **执行代码**：运行任意MATLAB代码片段
- **工作区变量**：获取/设置/列出/清除工作区变量
- **表达式求值**：求值MATLAB表达式并获取结果
- **脚本执行**：运行MATLAB .m脚本文件
- **函数调用**：调用内置或自定义MATLAB函数
- **单一上下文**：Simulink和MATLAB操作的统一工作区
### 交互式上下文感知 ⭐
- **查询当前状态**：获取活动模型、选定块、当前子系统
- **智能搜索**：按类型、名称或属性查找块
- **模型状态**：检查是否有未保存的更改、加载的模型
- **视觉反馈**：用颜色编码突出显示块
### 核心Simulink操作
- **模型管理**：创建、加载、保存Simulink模型
- **块操作**：添加块、连接块、创建子系统
- **参数控制**：获取/设置块参数
- **总线操作**：创建总线元素、总线选择器
- **仿真**：运行具有可配置参数的仿真
- **布局和清理**：自动排列块、路由信号线
### 引擎管理
- **共享引擎**：使用`matlab.engine.shareEngine('SimulinkMCP')`进行多进程访问
- **回退模式**：优雅地处理断开连接
- **连接管理**：自动重新连接和错误处理
## 新增功能
### 版本 0.2.0 - 发布强化
- MIT许可证、安全策略、第三方通知和MathWorks商标归属
- `SIMULINK_MCP_MODE`，具有`readonly`、`open`和`full`工具暴露模式
- 非UV和离线轮安装指南，用于企业审查
- `.github` Copilot指令和技能已清理，用于公共仓库使用
- 函数间隙markdown，替换本地保存的MathWorks HTML导出
- 用于测试、类型检查、审计、SBOM、轮、源分发、校验和和GitHub发布工件的CI和发布工作流
- 总共43个MCP工具
## 安装
### 自动安装（推荐）
安装程序现在**自动检测MATLAB**并使用**便携式路径**：
```powershell
.\install.ps1
```
该脚本将：
- ✅ 自动检测MATLAB安装（R2025a → R2023a）
- ✅ 使用UV创建虚拟环境
- ✅ 安装Python的MATLAB引擎
- ✅ 使用相对路径配置VS Code
- ✅ 测试安装
### 便携式安装
要在**另一台计算机**上安装，请参阅 **[PORTABLE_INSTALL.md](PORTABLE_INSTALL.md)** 以获取：
- ✅ 自动检测MATLAB版本
- ✅ 通过`config.local.ps1`进行自定义配置
- ✅ 团队部署策略
- ✅ 非标准MATLAB位置
**快速便携式安装**：
```powershell
# 将项目文件夹复制到新计算机
# 删除.venv文件夹
# 运行安装程序 - 它会自动检测所有内容！
.\install.ps1
```
### 手动安装
参见 [INSTALL.md](INSTALL.md) 以获取逐步手动安装说明。
### 先决条件
- **MATLAB** （R2023a或更新版本），带有Simulink
- **Python 3.10+** （由UV自动安装）
- **UV包管理器** （[安装](https://docs.astral.sh/uv/))，用于自动安装程序，或用于非UV环境的标准`venv`/`pip`
- **VS Code** ，带有GitHub Copilot扩展
- **管理员访问权限** （仅限MATLAB引擎安装）
## VS Code集成
### 先决条件
1. 启动MATLAB并创建一个共享引擎：
```matlab
matlab.engine.shareEngine('SimulinkMCP')
```
2. 运行安装程序（`.\install.ps1`）以设置`.venv/`并安装MATLAB引擎。
### 推荐：VS Code `.vscode/mcp.json`
将 [config/mcp.json.example](config/mcp.json.example) 复制到您的*项目*中作为 `.vscode/mcp.json`，然后替换占位符。
此仓库的MCP入口点是：
- `python -m simulink_mcp_server.mcp_server`
对于仅限审查的使用，请从
[config/mcp.readonly.json.example](config/mcp.readonly.json.example) 开始。对于受信任的本地编辑，请使用 [config/mcp.full.json.example](config/mcp.full.json.example)。
### 可选：Copilot特定设置
如果您需要Copilot特定配置，请复制
[config/copilot.settings.json.example](config/copilot.settings.json.example) 到 `.vscode/settings.json`。
## 可用工具
### 交互式上下文函数（新增！）
获取有关您在Simulink编辑器中的当前位置和选择的以下信息：
- `simulink_get_current_model()` - 获取活动模型名称（bdroot）
- `simulink_get_current_block()` - 获取选定块路径（gcb）
- `simulink_get_current_block_handle()` - 获取选定块句柄（gcbh）
- `simulink_get_current_system()` - 获取活动系统/子系统（gcs）
- `simulink_get_selected_blocks()` - 获取所有选定块
- `simulink_find_blocks(model_name, criteria)` - 查找符合条件的块
### 引擎管理
- `connect_simulink_engine()` - 连接到共享的MATLAB引擎
### 模型操作
- `simulink_new_model(model_name)` - 创建新的Simulink模型
- `simulink_load_model(file_path)` - 从文件加载模型
- `simulink_save_model(model_name, file_path?)` - 保存模型到文件
- `simulink_run_simulation(model_name, stop_time?)` - 运行仿真
- `simulink_model_is_loaded(model_name)` - 检查模型是否在内存中（新增！）
- `simulink_model_is_dirty(model_name)` - 检查是否有未保存的更改（新增！）
### 块操作
- `simulink_add_block(model_name, block_type, block_name, position?)` - 向模型添加块
- `simulink_delete_block(block_path)` - 从模型中删除块（新增！）
- `simulink_replace_block(model_name, old_type, new_type)` - 替换块（新增！）
- `simulink_list_blocks(model_name, block_type?)` - 列出模型中的块
- `simulink_highlight_block(block_path, color?)` - 突出显示块（新增！）
### 连接操作
- `simulink_connect_blocks(model_name, source_block, source_port, dest_block, dest_port)` - 连接块
- `simulink_delete_line(model_name, source_block, source_port, dest_block, dest_port)` - 删除线（新增！）
### 参数管理
- `simulink_get_param(model_name, block_name, parameter)` - 获取块参数
- `simulink_set_param(model_name, block_name, parameter, value)` - 设置块参数
### 层次结构和布局
- `simulink_create_subsystem(model_name, blocks, subsystem_name)` - 从块创建子系统
- `simulink_expand_subsystem(subsystem_path)` - 用内容替换子系统（新增！）
- `simulink_arrange_system(system_path)` - 自动布局块（新增！）
- `simulink_route_line(line_handle)` - 自动路由信号线（新增！）
### 高级功能
- `simulink_add_bus_element(model_name, bus_object_name, element_name, data_type, dimensions)` - 添加总线元素
- `simulink_create_bus_selector(model_name, bus_signal_block, selected_signals, selector_name)` - 创建总线选择器
**子总计：28个Simulink和引擎工具**
### MATLAB代码执行（新增！）
- `matlab_execute_code(code, capture_output?)` - 执行任意MATLAB代码
- `matlab_eval_expression(expression)` - 求值表达式并获取结果
- `matlab_get_workspace_variable(variable_name)` - 从工作区获取变量
- `matlab_set_workspace_variable(variable_name, value)` - 设置工作区变量
- `matlab_list_workspace_variables()` - 列出工作区中的所有变量
- `matlab_clear_workspace(variables?)` - 清除变量（如果为空则全部清除）
- `matlab_run_script(script_path)` - 运行MATLAB .m脚本文件
- `matlab_call_function(function_name, *args, nargout?)` - 调用MATLAB函数
**总计：8个MATLAB函数**
### MATLAB代码质量
- `matlab_check_code(script_path)` - 运行MATLAB静态代码分析
- `matlab_run_tests(script_path)` - 运行MATLAB测试
- `matlab_detect_toolboxes()` - 列出已安装的MATLAB产品和版本
**总计：3个代码质量工具**
### 异步执行和性能
- `matlab_execute_async(code)` - 异步启动长时间运行的MATLAB代码
- `matlab_check_task(task_id)` - 检查异步任务状态
- `matlab_cancel_task(task_id)` - 取消异步任务
- `matlab_perf_summary()` - 总结最近的MATLAB执行时间
**总计：4个异步/性能工具**
**总计：43个MCP工具**
## 用例
参见 [GETTING_STARTED.md](GETTING_STARTED.md) 以获取完整的演练。
### MATLAB代码执行（新增！）
```python
# 执行代码并捕获输出
matlab_execute_code("disp('Hello from MATLAB!')")
# 返回：{'status': 'success', 'output': 'Hello from MATLAB!\n'}
# 求值数学表达式
matlab_eval_expression("2^10 + sqrt(144)")
# 返回：{'status': 'success', 'value': 1036.0, 'type': 'float'}
# 创建和操作变量
matlab_set_workspace_variable("my_matrix", [[1, 2], [3, 4]])
matlab_get_workspace_variable("my_matrix")
# 返回：{'status': 'success', 'value': [[1, 2], [3, 4]], 'type': 'array'}
# 调用MATLAB函数
matlab_call_function("magic", 5, nargout=1)
# 返回：{'status': 'success', 'result': [[17,24,1,8,15],...]}
# 运行分析代码
code = """
x = 1:100;
y = sin(x/10);
mean_y = mean(y);
std_y = std(y);
fprintf('Mean: %.4f, Std: %.4f\\n', mean_y, std_y);
"""
matlab_execute_code(code)
# 列出工作区变量
matlab_list_workspace_variables()
# 返回：{'status': 'success', 'variables': ['x', 'y', 'mean_y', ...]}
```
### 统一的Simulink + MATLAB工作流
```python
# 1. 创建Simulink模型
simulink_new_model("AnalysisModel")
# 2. 仿真并获取结果
simulink_run_simulation("AnalysisModel", 10.0)
# 3. 在MATLAB中分析仿真结果
matlab_execute_code("""
% 加载仿真输出
out = evalin('base', 'out');
time = out.tout;
signals = out.yout;
% 执行分析
peak_value = max(signals);
settling_time = time(find(abs(signals - peak_value) < 0.02, 1));
fprintf('Peak: %.4f, Settling time: %.4f\\n', peak_value, settling_time);
""")
# 4. 使用分析结果修改模型
peak = matlab_get_workspace_variable("peak_value")
simulink_set_param("AnalysisModel", "Gain1", "Gain", str(peak['value']))
```
### 创建简单模型
```python
# 创建新模型
simulink_new_model("MyModel")
# 添加源块
simulink_add_block("MyModel", "simulink/Sources/Constant", "Constant1", [30, 30, 60, 60])
# 添加范围块
simulink_add_block("MyModel", "simulink/Sinks/Scope", "Scope1", [120, 30, 150, 60])
# 连接块
simulink_connect_blocks("MyModel", "Constant1", 1, "Scope1", 1)
# 设置常量值
simulink_set_param("MyModel", "Constant1", "Value", "5")
# 运行仿真
simulink_run_simulation("MyModel", 10.0)
# 保存模型
simulink_save_model("MyModel")
```
### 交互式查询
```python
# 获取当前模型名称
simulink_get_current_model()
# 获取选定块
simulink_get_current_block()
# 按类型查找块
simulink_find_blocks("MyModel", {"BlockType": "Gain"})
# 突出显示块
simulink_highlight_block("MyModel/Gain1", "green")
# 自动排列布局
simulink_arrange_system("MyModel")
```
### 使用总线信号
```python
# 创建总线元素
simulink_add_bus_element("MyModel", "MyBus", "signal1", "double", "1")
simulink_add_bus_element("MyModel", "MyBus", "signal2", "int32", "[1 3]")
# 创建总线选择器
simulink_create_bus_selector("MyModel", "BusCreator1", ["signal1", "signal2"], "BusSelector1")
```
## 脚本
### 安装
- `install.ps1` - 自动安装（推荐）
- `install_matlab_engine.ps1` - 单独安装MATLAB引擎（作为管理员）
### 启动
- `start_matlab.ps1` - 启动带有共享引擎的MATLAB 'SimulinkMCP'
- `start_mcp_server.ps1` - 启动MCP服务器（MATLAB运行后）
### 测试
- `test_connection.py` - 测试MATLAB引擎连接
- `test_interactive_functions.py` - 测试交互式Simulink函数
## 文档
- **[GETTING_STARTED.md](GETTING_STARTED.md)** - 快速入门指南（5分钟）
- **[INSTALL.md](INSTALL.md)** - 详细安装说明
- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - 常用命令和工作流
- **[FUNCTION_ADDITIONS.md](FUNCTION_ADDITIONS.md)** - 完整的功能文档
- **[VSCODE_SETUP.md](VSCODE_SETUP.md)** - VS Code配置详情
## 环境变量
- `MATLAB_PATH` - MATLAB安装路径（默认：`C:/Program Files/MATLAB/R2025a`)
- `SIMULINK_MCP_LOG_LEVEL` - 日志级别（默认为`WARNING`;设置为`INFO`/`DEBUG`进行故障排除）
- `SIMULINK_MCP_MODE` - 工具暴露模式：`readonly`、`open`或`full`（默认为`full`以兼容旧版本）
### 工具暴露模式
| 模式 | 意图使用 | 工具表面 |
|------|--------------|--------------|
| `readonly` | 询问/审查代理 | 检查当前上下文、查找/列表块、读取参数/状态、读取工作区变量、代码检查、工具箱检测 |
| `open` | 审查代理可以打开模型 | `readonly` 加上模型加载和编辑器高亮 |
| `full` | 受信任的本地开发 | 全部43个工具，包括MATLAB执行、|模型编辑、保存、仿真、异步任务 |
参见 [docs/ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md) 获取企业注册和离线安装指南。
## 故障排除
参见 [GETTING_STARTED.md](GETTING_STARTED.md#troubleshooting) 常见问题。
### 快速诊断
```powershell
# 测试MATLAB引擎连接
.\.venv\Scripts\python.exe test_connection.py
# 测试交互式函数（需要打开模型）
.\.venv\Scripts\python.exe test_interactive_functions.py
# 检查共享引擎状态（在MATLAB中）
matlab.engine.find_matlab()
```
### 常见问题
**"共享引擎未找到"**
- 启动MATLAB并运行：`matlab.engine.shareEngine('SimulinkMCP')`
**"当前没有打开模型"**
- 在MATLAB中打开Simulink模型后再查询
**VS Code无法看到MCP服务器**
- 重载VS Code窗口：`Ctrl+Shift+P` → "Reload Window"
- 检查`.vscode/mcp.json`是否有正确的路径
## 开发
### 运行测试
```bash
# 安装开发依赖项
uv sync --extra dev --no-prune
# 运行测试
uv run --extra dev pytest tests/
```
无UV：
```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -m "not integration"
```
### 开发模式
```bash
uv run python -m simulink_mcp_server.mcp_server
```
### 构建软件包
```bash
uv build
```
## 项目结构
```
simulink-mcp-server/
├── src/
│ └── simulink_mcp_server/
│ ├── __init__.py
│ ├── server.py # MATLAB/Simulink功能 + 引擎管理
│ └── mcp_server.py # MCP标准IO服务器公开工具
├── tests/
│ └── test_basic.py
├── examples/
│ └── demo.py
├── config/
│ ├── mcp.json.example # VS Code `.vscode/mcp.json`模板
│ └── copilot.settings.json.example # 可选的Copilot设置模板
├── install.ps1 # 自动安装程序
├── install_matlab_engine.ps1 # MATLAB引擎安装程序
├── start_matlab.ps1 # 启动带有共享引擎的MATLAB
├── start_mcp_server.ps1 # 启动MCP服务器
├── test_connection.py # 连接诊断
├── test_interactive_functions.py # 功能测试
├── GETTING_STARTED.md # 快速入门指南
├── INSTALL.md # 详细安装说明
├── QUICK_REFERENCE.md # 命令参考
├── FUNCTION_ADDITIONS.md # 功能文档
├── README.md # 本文件
└── pyproject.toml # Python依赖项
```
## 版本兼容性
| 组件 | 测试版本 | 最低版本 |
|-----------|----------------|-----------------|
| MATLAB | R2025a | R2020b+ |
| Simulink | 25.1 | 10.2+ |
| Python | 3.12.12 | 3.10 |
| UV | 0.9.2 | 0.4.0 |
| MCP SDK | 1.17.0 | 1.17.0 |
## 贡献
本项目使用：
- **UV** 或标准`venv`/`pip`进行Python包管理
- **MCP SDK** 进行协议实现
- **MATLAB引擎API** 进行MATLAB/Simulink交互
## 许可证
该项目在MIT许可证下发布。参见 [LICENSE](LICENSE).
MATLAB和Simulink是MathWorks的注册商标。本项目不隶属于、不赞助或由MathWorks, Inc. 认可。
---
**准备开始？** 运行 `.\install.ps1` 并参阅 [GETTING_STARTED.md](GETTING_STARTED.md)！
连接信息
猜你喜欢
暂无推荐服务器