dsh-matlab-mcp

Readme

# dsh-matlab-mcp

DeepSeek Harness (dsh) **profile bundle** that registers the MathWorks
MATLAB/Simulink MCP server into the dsh GUI, so agent sessions get native
`mcp__matlab__*` tools for controlling MATLAB and reading/building/testing
Simulink models.

| Kind | Tool name (in agent sessions) | What it does |
|---|---|---|
| MATLAB | `mcp__matlab__evaluate_matlab_code` | Run any MATLAB code in the shared session |
| MATLAB | `mcp__matlab__run_matlab_file` / `run_matlab_test_file` | Run a script / run unit tests |
| MATLAB | `mcp__matlab__check_matlab_code` | Static Code Analyzer warnings for a .m file |
| MATLAB | `mcp__matlab__detect_matlab_toolboxes` | MATLAB version + installed toolboxes |
| Simulink | `mcp__matlab__model_overview` | Hierarchical model view |
| Simulink | `mcp__matlab__model_read` | Block topology + expression notation |
| Simulink | `mcp__matlab__model_edit` | Structural edits / parameter changes |
| Simulink | `mcp__matlab__model_check` | Structural validation (unconnected ports, …) |
| Simulink | `mcp__matlab__model_query_params` | Random access to any block/config parameter |
| Simulink | `mcp__matlab__model_resolve_params` | Resolve workspace variables to values |
| Simulink | `mcp__matlab__model_test` | Gherkin-based behavioral tests (needs Simulink Test) |

## Prerequisites

1. **MATLAB R2021a or later** (R2023a+ for the Simulink `model_*` tools), with
   **Simulink** installed.
2. **MATLAB Agentic Toolkit** installed — it provides the MCP server binary
   and the Simulink extension tools. In MATLAB:
   ```matlab
   setupAgenticToolkit("install")
   ```
   (select MATLAB + Simulink toolkits). Manual download is documented in the
   [Simulink Agentic Toolkit](https://github.com/matlab/simulink-agentic-toolkit)
   getting-started guide.
3. **pnpm** (used by `dsh plugin`): `npm install -g pnpm`
4. **The dsh launcher** on PATH (`dsh`), or `npx` (the installer falls back to
   `npx -y @deepseek-ai/dsh`).

## Install

### From this repo (recommended)

```bash
git clone https://github.com/<your-account>/dsh-matlab-mcp.git
cd dsh-matlab-mcp
# Windows:
.\install.ps1
# macOS / Linux:
./install.sh
```

### Directly from the git URL (no clone)

```bash
dsh plugin --profile web add github:<your-account>/dsh-matlab-mcp
```

### Manually (no pnpm)

Append this to `~/.dsh/profiles/web/cordis.patch.yml` (create the file with
content `[]` if missing), then restart the GUI:

```yaml
- insert:
    - id: mcp-matlab
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: matlab
        transport: stdio
        command: !!js "(process.env.USERPROFILE || process.env.HOME) + '/.matlab/agentic-toolkits/bin/matlab-mcp-server' + (process.platform === 'win32' ? '.exe' : '')"
        args: !!js "['--matlab-session-mode=existing', '--extension-file=' + (process.env.USERPROFILE || process.env.HOME) + '/.matlab/agentic-toolkits/simulink/tools/tools.json']"
        env:
          WINDIR: 'C:\Windows'
        toolCallTimeoutMs: 600000
        failOnStartupError: true
```

> New rows in a patch file must be added with an `insert` list **without an
> `id`**. A bare `id` targets an existing entry and fails with
> `entry "xxx" not found`.

## After install (required every MATLAB session)

1. **Restart the dsh GUI.**
2. Make sure **MATLAB is running** — the server attaches to a running session
   (`--matlab-session-mode=existing`), it does not start MATLAB.
3. In that MATLAB session, share it with the server once per session:
   ```matlab
   addpath('~/.matlab/agentic-toolkits/simulink')   % Windows: use C:\Users\<you>\.matlab\...
   satk_initialize
   ```

## Verify

After a GUI restart, ask the agent:

> What version of MATLAB is running? List the installed toolboxes.

It should answer via `mcp__matlab__detect_matlab_toolboxes`. For Simulink:

> Show me an overview of model MyModel.

## Troubleshooting

| Symptom | Fix |
|---|---|
| No `mcp__matlab__*` tools in the session | GUI wasn't restarted after install; or `failOnStartupError` would have logged a loud error — check the GUI host console |
| Tools exist but calls fail / "not shared" | Run `addpath('~/.matlab/agentic-toolkits/simulink'); satk_initialize` in the running MATLAB session |
| `matlab-mcp-server` binary missing | Install the MATLAB Agentic Toolkit (`setupAgenticToolkit("install")`) |
| MATLAB version mismatch | The server attaches to whatever MATLAB is running; use the MATLAB you want to control |
| Tool calls time out on long simulations | Increase `toolCallTimeoutMs` (default 600000 = 10 min) in `cordis.patch.yml` |
| Simulink fails on Windows | `WINDIR` env var is injected by this bundle (required on Windows) |

## Uninstall

```bash
dsh plugin --profile web remove dsh-matlab-mcp
```

## Notes

- This repo contains **only configuration** — the MCP server itself is the
  open-source [MATLAB MCP Server](https://github.com/matlab/matlab-mcp-core-server)
  (Apache-2.0, © The MathWorks, Inc.), and the client plugin is
  `@deepseek-ai/dsh-mcp-client` shipped with DeepSeek Harness.
- The bundle's paths are resolved at config time via `!!js` expressions, so
  no per-machine editing is needed (Windows, macOS, Linux).

## License

MIT