matlab-agentic-toolkit-setup

MATLAB Agentic Toolkit 设置

为 MATLAB Agentic Toolkit 自动完成入门设置。检测 MATLAB，下载并安装 MCP 服务二进制文件，配置 AI 编码 Agent，并验证一切是否正常。

已测试的平台： Claude Code。
已自动化的平台： GitHub Copilot、Gemini CLI（提供手动备用方案）。 实验性平台： Codex、Amp 按现状提供；设置流程会引导你完成每个步骤，如果遇到问题，也会提供手动备用说明。

此技能不需要 MATLAB MCP 服务——直到最后的验证步骤之前，所有操作都通过 shell 命令完成。

欢迎消息

开始任何操作前，先向用户打印一条欢迎消息。这有助于说明接下来会发生什么，以及为什么可能需要用户批准某些操作。语气应友好、亲切，并使用“I”表述。消息应涵盖以下内容：

Welcome! My goal is to get you set up with the MATLAB Agentic Toolkit so you
can use MATLAB tools and skills with your agent for your projects.

Here's what I'll do:

1. Look around your computer to find your MATLAB installation(s) and check
   whether the MCP server is already installed. Depending on your permissions
   settings, you may be asked to approve some of these steps — I'm just
   reading system info, not changing anything yet.

2. Come back to you with a plan showing what I found and what I'd like to
   configure. You'll have a chance to adjust any choices before I make changes.

3. Once you approve, I'll install the MCP server (if needed), configure your
   agent to use it for your other projects, and verify the connection to MATLAB.

This setup configures everything globally — once it's done, MATLAB tools and
skills will be available in every session, regardless of which project you're
working in. This is the easiest way to get started. If you later want to scope
the configuration to specific projects, the Configuration and Troubleshooting guide covers that.

If you'd rather set things up manually, the Configuration and Troubleshooting guide has
step-by-step instructions: Configuration_and_Troubleshooting.md

自然地调整措辞，不要逐字照读，但要涵盖以上三点。打印欢迎消息后，直接进入阶段 1，无需等待用户回复。

适用场景

• 用户运行 /matlab-setup，或要求设置 MATLAB Agentic Toolkit
• 克隆后首次使用该工具包
• 将该工具包移至新位置后
• 安装新版本 MATLAB 后
• 将 MCP 服务升级到最新版本
• MCP 连接问题可能意味着安装已损坏
• 用户想为任何受支持的 Agent 平台配置 MATLAB MCP

不适用场景

• MATLAB 环境已设置完成且运行正常——请直接使用环境验证功能
• 用户询问特定的 MATLAB 任务（请使用相应的领域技能）

工作流概览

1. 发现（静默）— 检测平台、查找 MATLAB 安装、检查现有 MCP 服务、检测 Agent 平台
2. 计划（交互）— 汇总所有发现的信息和拟执行的操作；在进行任何更改前，让用户确认或调整
3. 执行（不中断）— 执行已批准的计划：安装二进制文件、配置 Agent
4. 验证 — 确认 MCP 服务能够连接 MATLAB
5. 报告 — 汇报所有已完成的设置及其所在位置

目标是只向用户询问一次所有需要决定的事项，然后不中断地执行。

---

阶段 1：发现

开始前打印一条简短的状态消息："正在扫描系统中的 MATLAB 安装并检查当前设置。你可能需要批准某些只读命令——我只是在收集信息，尚未进行任何更改。"

静默运行以下所有检查——此阶段不要提示用户。收集所有结果，供阶段 2 汇报。

1a. 检测平台

uname -s   # Darwin, Linux, or MINGW*/MSYS* for Windows
uname -m   # arm64, x86_64, aarch64

将检测结果映射为下载资源名称（用于 GitHub 发布版本 URL）：

操作系统	架构	资源名称
macOS	arm64	matlab-mcp-server-macos-arm64
macOS	x86_64	matlab-mcp-server-macos-x64
Linux	x86_64	matlab-mcp-server-linux-x64
Windows	x86_64	matlab-mcp-server-windows-x64.exe

本地二进制文件名称始终为 matlab-mcp-server（Windows 上为 matlab-mcp-server.exe），与下载资源名称无关。

1b. 检查现有配置

先检查当前位置的配置文件，然后再回退到旧位置：

cat ~/.matlab/agentic-toolkits/config.json 2>/dev/null

如果未找到，请检查旧位置：

cat ~/.matlab-agentic-toolkit/config.json 2>/dev/null

如果任一位置存在配置且路径有效，请记录其中保存的值，作为阶段 2 的默认值。如果只有旧配置存在，请标记该配置，以便在阶段 3 迁移。

1c. 查找 MATLAB 安装

搜索以下所有位置：PATH（which matlab）、常见目录和 macOS Spotlight。收集所有结果。

平台	搜索位置
macOS	/Applications/*/MATLAB_*.app、/Applications/MATLAB_*.app、Spotlight
Linux	/usr/local/MATLAB/R20*、/opt/MATLAB/R20*
Windows	/c/Program Files/MATLAB/R20*

验证每个结果：test -x "$MATLAB_ROOT/bin/matlab"，并从 VersionInfo.xml 读取版本。

1d. 检查是否已有 MCP 服务

先检查当前位置的二进制文件（先检查新名称，再检查旧名称），然后检查旧目录：

~/.matlab/agentic-toolkits/bin/matlab-mcp-server --version 2>/dev/null
~/.matlab/agentic-toolkits/bin/matlab-mcp-core-server --version 2>/dev/null
~/.local/bin/matlab-mcp-core-server --version 2>/dev/null

如果在任何位置找到，请记录路径和版本。如果在任一位置以旧名称（matlab-mcp-core-server）找到，请标记为在阶段 3 中重命名。如果只在旧目录（~/.local/bin/）中找到，也请标记为需要迁移目录。还要查询 GitHub 上的最新版本：

curl -sL https://api.github.com/repos/matlab/matlab-mcp-core-server/releases/latest | grep '"tag_name"' | head -1 | sed 's/.*"\(v[^"]*\)".*/\1/'

1e. 检查现有 Agent 配置

对于 Claude Code：

claude plugin list 2>&1

对于其他平台，检查其全局配置文件中是否已有 matlab MCP 服务条目（路径请参阅各平台的专用参考文件）。

1f. 检测 Agent 平台

检查环境和 CLI 工具：claude --version（Claude Code）、codex --version（Codex）、amp --version（Amp）、gemini --version（Gemini CLI）、$VSCODE_*（Copilot）。如果无法确定，请询问用户。

1g. 检查旧版遗留项

阅读平台专用参考文件，并检查其中 Legacy Artifacts 部分（如有）列出的项目。记录发现的内容——这些内容会显示在计划中，并在阶段 3 中清理。

参考文件解析： 在重新运行时（存在 ~/.matlab/agentic-toolkits/config.json 或 ~/.matlab-agentic-toolkit/config.json 时），从该配置中的工具包源路径解析参考文件。在新架构中，此路径为 toolkits.matlab.source（值为本地路径而非 "release" 时）。在旧版架构中，此路径为 toolkitRoot。示例：<source>/skills-catalog/toolkit/matlab-agentic-toolkit-setup/reference/<filename>。这样可以避免技能从插件缓存加载时读取过时的缓存版本。

1h. 检测旧版配置位置

如果在 ~/.matlab-agentic-toolkit/config.json 找到配置，但在 ~/.matlab/agentic-toolkits/config.json 中未找到，请记录需要迁移。旧配置使用扁平架构，必须在阶段 3 中转换为多工具包架构。

---

阶段 2：制定计划

在一条消息中展示所有发现和拟采取的操作。如果 Agent 有可用的交互式信息收集工具，可以使用。否则，输出计划并等待用户正常回复。计划格式如下：

MATLAB Agentic Toolkit — Setup Plan
====================================

Platform:  macOS arm64

MATLAB installations found:
  [1] R2025b  /Applications/MATLAB_R2025b.app
  [2] R2024b  /Applications/MATLAB_R2024b.app

MCP server:
  Installed:  not found
  Latest:     v0.7.0

Agent platform:  Claude Code (detected)
  Status:        Tested

Proposed actions:
  MATLAB:        Use R2025b (/Applications/MATLAB_R2025b.app)
  MCP server:    Download v0.7.0 to ~/.matlab/agentic-toolkits/bin/matlab-mcp-server
  Display mode:  desktop (full MATLAB desktop visible)
  Agent config:  Configure MCP server globally (available in all sessions)
  Migration:     (none)

Proceed with this plan? You can adjust any choice:
  - Pick a different MATLAB: "use 2" or provide a path
  - Keep existing server: "use server at /path/to/binary"
  - Change display: "use nodesktop" (MATLAB runs headless; windows still open for plots)
  - Configure a different agent: "use Codex" or "use Amp"

如果未找到 MATLAB 安装，计划应改为显示：

MATLAB installations found:
  (none detected)

Options:
  [1] Provide the path to an existing MATLAB installation
  [2] Install MATLAB using the matlab-install-products skill

等待用户选择后再完成计划的其余部分。

Migration 行显示阶段 1g、1h 和 1d 中发现的旧版遗留项。如果未发现任何内容，则显示 (none)。例如：

• Remove ~/.claude/.mcp.json (migrated to claude mcp add)
• Migrate config from ~/.matlab-agentic-toolkit/ to ~/.matlab/agentic-toolkits/
• Move binary from ~/.local/bin/ to ~/.matlab/agentic-toolkits/bin/

对于非 Claude 平台，请明确注明“实验性——未经测试，按原样提供”，并说明如果自动设置失败，将提供手动备用方案。

对于 OpenAI Codex，计划必须同时涵盖：

• ~/.codex/config.toml 中的全局 MCP 配置
• ~/.agents/skills/ 中的全局技能引用，以便设置后可从任何仓库使用该工具包

决策点

决策	默认值	如何更改
使用哪个 MATLAB	找到的最新版本	用户按编号选择或提供路径
MCP 服务	下载最新版本到 ~/.matlab/agentic-toolkits/bin/	用户说“使用现有版本”或提供路径
显示模式	desktop	用户说“使用 nodesktop”
Agent 平台	自动检测	用户说“使用 [platform]”

未找到 MATLAB

报告未找到 MATLAB，并向用户提供两个选项：

1. 提供路径，指向现有 MATLAB 安装。在继续之前进行验证。
2. 使用 matlab-install-products 技能安装 MATLAB（并可选择安装其他工具箱或支持包）。安装的版本必须为 R2021a 或更高版本——较早版本不支持 MCP 服务。

如果用户选择选项 2，则交由 matlab-install-products 处理（确保版本为 R2021a 或更高版本）。该技能报告已验证的 MATLAB 路径后，使用新安装的根目录从阶段 3 继续。

用户确认

用户确认后，进入阶段 3。如果用户调整了选项，则更新计划；只有在更改较大时才重新确认。

---

阶段 3：执行

开始前打印一条简短状态消息：“很好——现在开始执行计划。我将下载文件、编写配置文件并注册技能。根据你的权限设置，你可能需要批准其中某些操作。”

执行已批准的计划。此阶段不要向用户提问——所有决定都已在阶段 2 做出。如果计划包含通过 matlab-install-products 安装 MATLAB，则先执行安装，然后继续执行步骤 3a。

3a. 安装 MCP 服务（如有需要）

如果阶段 1d 在旧位置（~/.local/bin/matlab-mcp-core-server）找到了二进制文件，且它已是最新版本，则应移动并重命名它，而不是重新下载：

mkdir -p ~/.matlab/agentic-toolkits/bin
mv ~/.local/bin/matlab-mcp-core-server ~/.matlab/agentic-toolkits/bin/matlab-mcp-server

如果阶段 1d 在当前位置（~/.matlab/agentic-toolkits/bin/matlab-mcp-core-server）以旧名称找到了二进制文件，且它已是最新版本，则应重命名：

mv ~/.matlab/agentic-toolkits/bin/matlab-mcp-core-server ~/.matlab/agentic-toolkits/bin/matlab-mcp-server

否则，使用 curl（首选）或 wget 下载，并直接以新名称保存：

mkdir -p ~/.matlab/agentic-toolkits/bin
curl -sL -o ~/.matlab/agentic-toolkits/bin/matlab-mcp-server \
  "https://github.com/matlab/matlab-mcp-core-server/releases/download/${LATEST_TAG}/${ASSET_NAME}"

下载（或移动）后：执行 chmod +x（macOS/Linux）、xattr -d com.apple.quarantine（macOS）、Unblock-File（Windows）。如果 macOS Gatekeeper 阻止运行：前往“系统设置”>“隐私与安全性”>“仍要允许”。

验证：~/.matlab/agentic-toolkits/bin/matlab-mcp-server --version

如果下载失败，请提供直接下载 URL，供用户手动下载。

**清理旧名称的二进制文件：**成功安装或重命名后，删除所有旧名称的二进制文件：

rm -f ~/.matlab/agentic-toolkits/bin/matlab-mcp-core-server
rm -f ~/.local/bin/matlab-mcp-core-server

3b-migrate. 清理旧版文件

如果阶段 1g 发现了任何旧版文件，请根据平台参考文件中 Legacy Artifacts 一节的说明进行清理。只有在成功写入新配置后，才能删除这些文件（即在 3b-platform 之后执行此操作，而不是之前）。

3b-shared. 注册全局技能（Copilot、Codex、Gemini）

对于从 ~/.agents/skills/ 发现技能的平台——GitHub Copilot、OpenAI Codex 和 Gemini CLI——创建指向工具包仓库的符号链接。即使配置了多个平台，也只需执行一次。

工具包包含跨平台辅助脚本：

macOS / Linux：

bash "<TOOLKIT_ROOT>/skills-catalog/toolkit/matlab-agentic-toolkit-setup/scripts/install-global-skills.sh" "<TOOLKIT_ROOT>"

Windows PowerShell：

powershell -ExecutionPolicy Bypass -File "<TOOLKIT_ROOT>\skills-catalog\toolkit\matlab-agentic-toolkit-setup\scripts\install-global-skills.ps1" -ToolkitRoot "<TOOLKIT_ROOT>"

这些脚本会自动发现所有已发布的技能（skills-catalog/ 下任何包含 manifest.yaml 的目录），并在 ~/.agents/skills/ 中创建符号链接。回显已创建或更新的技能链接列表。

3b-platform. 配置 Agent 平台

阅读特定平台的参考文件（位于此技能文件旁的 reference/ 目录中），并严格按照其中的说明操作。使用工具包根目录解析路径：<TOOLKIT_ROOT>/skills-catalog/toolkit/matlab-agentic-toolkit-setup/reference/<filename>。

平台	参考文件
Claude Code	reference/claude-code-setup-guidance.md
GitHub Copilot	reference/copilot-setup-guidance.md
OpenAI Codex	reference/codex-setup-guidance.md
Sourcegraph Amp	reference/amp-setup-guidance.md
Gemini CLI	reference/gemini-cli-setup-guidance.md

每个参考文件都包含准确的配置格式、全局配置路径、合并说明和手动备用步骤。MCP 服务应配置为全局（而非按项目配置），这样无论用户打开哪个工作区，都能在每个会话中使用。

写入任何配置文件后，始终向用户回显：

1. 写入的文件路径
2. 写入的准确内容
3. 文件是新建的，还是更新了现有条目

3c. 迁移旧版配置（如有需要）

如果 Phase 1h 检测到 ~/.matlab-agentic-toolkit/config.json 中存在旧版配置，请立即迁移：

1. 读取旧配置
2. 将扁平架构转换为多工具包架构：
   • matlabRoot → matlab.root
   • mcpServerVersion → mcpServerVersion
   • mcpServerPath → mcpServerPath
   • displayMode → 保持不变（新架构仍支持此字段）
   • configuredPlatforms: ["claude-code"] → configurations.global.claude_code.toolkits: ["matlab"]
   • toolkitRoot → toolkits.matlab.source（如果指向 git 克隆目录，则使用 "local"；否则使用 "release"），并将 toolkits.matlab.version 设为 setupSkillVersion 或 "unknown"
3. 将转换后的配置写入新位置（见下文 3d）
4. 删除旧目录：rm -rf ~/.matlab-agentic-toolkit

3d. 保存状态

将配置写入 ~/.matlab/agentic-toolkits/config.json：

mkdir -p ~/.matlab/agentic-toolkits

{
  "toolkits": {
    "matlab": {
      "version": "<TOOLKIT_VERSION_OR_CALVER_TAG>",
      "source": "<SOURCE_PATH_OR_release>"
    }
  },
  "mcpServerVersion": "<VERSION>",
  "mcpServerPath": "<FULL_PATH_TO_BINARY>",
  "matlab": {
    "root": "<MATLAB_ROOT>",
    "version": "<MATLAB_RELEASE>"
  },
  "displayMode": "<DISPLAY_MODE>",
  "configurations": {
    "global": {
      "<AGENT_KEY>": {
        "toolkits": ["matlab"]
      }
    },
    "projects": {}
  },
  "setupSkillVersion": "<SKILL_VERSION>",
  "lastUpdated": "<ISO_8601_TIMESTAMP>"
}

说明：toolkits 支持多个条目（例如，除 "matlab" 外还可包含 "simulink"）。对于 GitHub 安装，source 为 "release"；对于开发克隆，则为本地路径。configurations 中的 Agent 键使用下划线（例如，claude_code、gemini_cli）。setupSkillVersion 记录此文件 front matter 中的版本，用于检测升级。

3e. 验证已保存的配置

写入 config.json 后，重新读取并验证路径是否有效：

cat ~/.matlab/agentic-toolkits/config.json
test -d "<matlab.root>" && echo "OK: matlab root exists" || echo "FAIL: matlab root not found"
test -x "<mcpServerPath>" && echo "OK: mcp server executable" || echo "FAIL: mcp server not found"
test -d "<toolkits.*.source>" && echo "OK: toolkit source exists" || echo "FAIL: toolkit source not found"

检查输出：确认 JSON 格式正确（花括号匹配、没有尾随逗号或内容截断），并且三项路径检查都通过。如果有任何检查失败，请修复配置并重新验证，然后再继续。

---

第 4 阶段：验证

打印一条简短的状态消息："设置已完成 — 正在验证与 MATLAB 的连接。" 验证步骤取决于 Agent 平台。

Claude Code

使用 MATLAB MCP 工具（现已通过插件提供）运行：

v = ver('MATLAB');
fprintf('MATLAB %s (%s) — ready.\n', v.Version, v.Release);

如果当前会话中没有 MCP 工具（首次设置后很常见），请告知用户：

刚刚安装了插件。请启动一个新的 Claude Code 会话以启用 MATLAB MCP 工具，然后通过提问来验证："What version of MATLAB is running?"

其他平台

对于非 Claude 平台，请尽可能进行以下验证：

1. 二进制文件可运行：

   ~/.matlab/agentic-toolkits/bin/matlab-mcp-server --version
   

2. 配置文件存在且包含 matlab 条目：

   cat <GLOBAL_CONFIG_PATH> 2>/dev/null | grep -l matlab
   

3. 告知用户如何在其 Agent 中验证：

   重启 [platform name]，然后提问："What version of MATLAB is running?" 如果 Agent 能调用 detect_matlab_toolboxes 或 evaluate_matlab_code，则表示设置成功。

如果验证失败：

1. 验证二进制文件存在且可执行：test -x ~/.matlab/agentic-toolkits/bin/matlab-mcp-server
2. 尝试手动运行服务进行诊断：

   ~/.matlab/agentic-toolkits/bin/matlab-mcp-server --matlab-root <path> --matlab-display-mode desktop 2>&1 | head -20
   

3. 在输出中查找 "Application startup complete"

---

阶段 5：报告

提供最终摘要，包括：MATLAB 版本和位置、MCP 服务版本和二进制文件路径、显示模式、Agent 平台和配置文件路径，以及状态文件位置。

• **对于 Claude Code：**列出已安装的插件及其作用范围。后续步骤：启动新会话，尝试询问“正在运行的 MATLAB 是什么版本？”，列出可用技能。
• **对于其他平台：**后续步骤：重启 Agent，尝试询问“正在运行的 MATLAB 是什么版本？”。提供故障排除方法：检查配置文件、测试二进制文件、链接到 Configuration_and_Troubleshooting.md 和问题跟踪器（https://github.com/matlab/matlab-agentic-toolkit/issues）。

---

重新运行时的行为

再次运行设置时：将 ~/.matlab/agentic-toolkits/config.json 中的现有配置作为默认值读取，执行完整发现，提供显示当前状态与计划状态的方案（例如，“升级 v0.6.0 → v0.7.0”），仅执行发生变化的操作，验证并报告。

---

约定

• 除验证步骤（Claude Code 的阶段 4）使用 MATLAB MCP 工具外，所有步骤均使用 bash 命令
• 绝不修改工具包目录、~/.matlab/agentic-toolkits/ 和平台全局配置路径之外的文件
• 在阶段 1 静默收集所有信息；在阶段 2 一并提供所有决策
• 发生故障时，提供可执行的说明；绝不在没有上下文的情况下显示原始错误
• 对于非 Claude 平台，始终提供手动备用说明
• **Windows 路径转义：**JSON 和 TOML 都将 \ 视为转义字符。向配置文件写入 Windows 路径或在 CLI 命令（如 claude mcp add-json）中传递路径时，必须使用正斜杠（C:/Users/Name/...）或将每个反斜杠加倍（C:\\Users\\Name\\...）。原始反斜杠会产生无效的转义序列，导致配置文件在不知情的情况下被破坏。将路径作为字符串值传递时，Python 的 json.dump() 会自动处理此问题；请优先使用程序化写入，而非字符串插值。

防护措施

始终执行

• 下载前检查是否已安装
• 继续操作前验证 MATLAB 根目录
• 做出任何更改前提供完整方案
• 准确回显写入配置文件的内容
• 明确标注实验性或未经测试的平台支持

先询问

• 在阶段 2 一并提供所有决策；执行过程中不再提示
• 如果发现多个 MATLAB 安装，请列出并推荐最新版本

绝不执行

• 通过 bash/终端运行 MATLAB；只能使用 MCP 工具（且仅在 Claude Code 的阶段 4 中使用）
• 直接安装 MATLAB；只有当用户在“未找到 MATLAB”流程中选择相应选项时，才委托给 matlab-install-products
• 覆盖其他 MCP 服务的现有配置项（仅添加/更新 matlab 条目）
• 跳过验证步骤
• 在阶段 1（发现）或阶段 3（执行）期间提示用户
• 声称未经测试的平台已获得全面支持

---

Copyright 2026 The MathWorks, Inc.

---