内容
# Lauterbach TRACE32 MCP 支持（预览版）
请注意，这是一个早期开发预览版。实现仍在不断演变，未来版本可能会发生变化。
**问题和反馈**：
我们非常希望听到您对我们的MCP实现的反馈和改进建议。对于问题、反馈和帮助，请使用GitLab问题功能。
## 目录
1. [文件概述](#文件概述)
2. [MCP服务器](#MCP服务器)
3. [代理技能](#代理技能)
4. [AI代理配置](#AI代理配置)
5. [预期代理行为](#预期代理行为)
6. [概念和AI路线图](#概念和AI路线图)
## 文件概述
```
t32mcp/ # 该仓库
├── README.md # 此文件
├── t32mcp-rs/ # MCP服务器源代码
├── CLAUDE.md # 调试说明示例
└── .claude/
└── skills/
└── skill-trace32/ # 配套代理技能
├── SKILL.md # MCP使用和脚本文档
└── scripts/
├── <脚本名称>.cmm # 作为PRACTICE脚本实现的“实际工具”
└── ...
```
## MCP服务器
您可以下载并使用预先编译的可执行文件（如果兼容）或从源代码自行构建。
**注意：** 可执行文件的路径需要对MCP客户端（您的AI代理，例如Claude Code）可访问，并且可执行文件需要能够通过远程API（默认为TCP）与TRACE32通信。
为了简单起见，本README的其余部分假设可执行文件位于 `/<您的路径>/t32mcp/t32mcp` / `C:\<您的路径>\t32mcp\t32mcp.exe`。
### 下载预编译版本（推荐）
x86-64 Linux和Windows的预编译可执行文件附在每个版本中。
从[发布页面](https://gitlab.com/lauterbach/t32mcp/-/releases)获取它们：
- `t32mcp-linux-x86_64`
- `t32mcp-windows-x86_64.exe`
- `skill-trace32.zip` 用于配套的TRACE32代理技能（`skill-trace32/`包含`SKILL.md`和PRACTICE脚本）
下载适用于您平台的可执行文件和技能压缩包，然后将`skill-trace32.zip`解压到您存储技能的任意位置（参见[技能](#技能)）。在Linux上，使用`chmod +x t32mcp-linux-x86_64`使可执行文件可运行。您可以重命名并移动可执行文件到您首选的位置。
### 自行构建
MCP服务器的Rust源代码位于`t32mcp-rs`目录中。在该目录中使用`cargo build --release`获取可移植的可执行文件`t32mcp`（Linux）/ `t32mcp.exe`（Windows）（在`t32mcp/t32mcp-rs/target/release/`中）。您可以将其移动到您首选的位置。
### 用法
MCP服务器通过`stdio`协议与MCP客户端通信。
可执行文件应使用命令行参数`--skills <技能路径>`调用。这将MCP服务器指向加载PRACTICE脚本`<技能路径>/skill-trace32/scripts/*.cmm`的根目录。
还有一个可选参数：`--port`。它默认为20000（TRACE32远程API的默认端口）。如果您使用不同的端口，请在此处提供。
### 工具
MCP服务器暴露了三个工具：
1. `execute_practice_skill`：执行脚本
2. `abort_practice_skill`：取消当前脚本
3. `collect_practice_skill_response`：获取/轮询正在运行的脚本的结果
## 代理技能
我们的MCP服务器仅提供与TRACE32的基本接口。
然后，我们依靠“技能”功能来解释如何使用这些MCP工具。
目前，所有说明和文档都在`SKILL.md`文件中。
### 脚本
技能的`scripts`目录包含一组PRACTICE（`*.cmm`）脚本，为AI代理提供实际的工具功能。
脚本可以接受输入参数，并可以通过打印到`AREA`窗口向AI代理返回信息。
以简单的`sw_get_stack_frame.cmm`为例：
```cmm
PRinTer.Area
WinPrint.Frame
ENDDO
```
**注意：** 每个脚本及其用法都应在`SKILL.md`文件中记录！
## AI代理配置
### MCP
要添加我们的MCP服务器，请按照您的AI代理的说明进行操作。通常，这包括指定协议，应设置为`stdio`（有时也称为`local`）。
然后设置可执行文件/路径到可执行文件 `/<您的路径>/t32mcp/t32mcp` / `C:\<您的路径>\t32mcp\t32mcp.exe`。
**重要：** 还要添加命令行参数 `--skills <您的技能路径>`。`<您的技能路径>` 的值取决于您如何配置技能（下一节）。
### 技能
大多数AI代理支持来自多个标准目录（全局和本地/项目）的技能，例如在 `.claude/skills/` 中。
将我们的 `skill-trace32` 技能放入其中一个支持的技能目录中（此处引用为 `<您的技能路径>`）。将发布的 `skill-trace32.zip` 解压到那里，或从 `<您的路径>/t32mcp/.claude/skills/skill-trace32` 复制。在添加MCP服务器时使用该目录 `<您的技能路径>` 作为 `--skills` 参数！
**重要：** 如果您自定义技能和脚本，例如添加新脚本，**您必须使用 `--skills` 参数将MCP指向正确的技能目录**。如果您指向未修改的原始git检出，AI代理将认为它可以访问新功能，但是MCP服务器将无法找到相应的PRACTICE脚本！
**注意：** 如果您已将 `skill-trace32` 复制到本地和全局技能目录（并且可能已编辑它们以使它们不同），请确保您了解您的AI代理的优先级顺序，以确定实际加载哪个技能。
#### 自定义
在您的本地项目中，您可以自由编辑 `skill-trace32/SKILL.md` 和相应的PRACTICE脚本，以自定义AI代理的TRACE32接口和说明，而不会影响其他项目或原始配置。您还可以添加新的技能，例如 `skill-trace32-arm-etm-trace`。如果您已经拥有有用的PRACTICE脚本库，您也可以通过技能使它们可供AI代理使用。
### Claude Code 示例
这在Claude Code中注册了MCP服务器。假设您已经将 `skill-trace32` 放入技能目录中（参见[技能](#技能)）。替换您自己的两个路径：
- MCP服务器可执行文件
- 包含 `skill-trace32` 的技能目录
命令在每个平台上都是相同的；只有路径语法不同。
Linux 示例：
```bash
claude mcp add-json t32mcp '{"type":"stdio","command":"/home/you/t32mcp/t32mcp","args":["--skills", "/home/you/my-project/.claude/skills"]}'
```
Windows（PowerShell）示例：
```powershell
claude mcp add-json t32mcp '{"type":"stdio","command":"C:\\Users\\you\\t32mcp\\t32mcp.exe","args":["--skills", "C:\\Users\\you\\my-project\\.claude\\skills"]}'
```
（可选）使用我们提供的“调试说明”，方法是将提供的 `CLAUDE.md` 复制到您的项目根目录中 / 复制到您自己的 `CLAUDE.md` 中。请注意，我们尚未评估这些说明的效果如何，您可以随意更改。
注意：要从Claude Code中删除MCP服务器，请使用 `claude mcp remove t32mcp`。
## 预期代理行为
如果您要求代理使用TRACE32在目标上设置寄存器值，它应该会自动读取 `skill-trace32` 技能。在 `SKILL.md` 文件中，它将找到：
````md
您可以访问一组用Lauterbach的脚本语言PRACTICE编写的 `*.cmm` 脚本，可以在TRACE32调试器中执行。
要执行它们，请使用Lauterbach的官方MCP服务器 `t32mcp`。
...
## 脚本参考
...
### 核心视角
#### `core_get_registers.cmm`
访问核心的当前寄存器。
#### `core_set_register.cmm`
将核心寄存器 `寄存器` 设置为值 `值`。
```json
{
"type": "object",
"properties": {
"register": { "type": "string" },
"value": {"type": "string"}
},
"required": ["register", "value"]
}
```
示例：
```json
{
"register": "x1",
"value": "0x10"
}
```
````
然后它应该检查MCP服务器提供的工具，并决定使用 `execute_practice_skill` 工具执行具有相应参数的 `core_set_register.cmm` 脚本。
## 概念和AI路线图
理想情况下，AI代理能够像人类（专家）一样使用TRACE32。
方便的是，LLM可以完全通过文本命令（PRACTICE / `cmm`脚本）控制TRACE32。
不幸的是，有很多PRACTICE命令，通用LLM似乎对它们了解不多。这导致TRACE32相关信息的幻觉率很高（尤其是在不使用网络搜索工具时）。
一种常见的方法是直接向AI代理提供TRACE32手册。
实际上，我们已经投入了一些精力来提供信息和额外的工具，使AI成为更有用的TRACE32助手。TRACE32 AI助手作为网站上的聊天机器人提供 [https://assistant.ai.lauterbach.com](https://assistant.ai.lauterbach.com) （有限预览，请使用公司电子邮件地址注册以增加获得访问权限的可能性）。
我们还计划使聊天机器人功能作为远程MCP服务器提供，以便您的AI代理可以受益于相同的知情TRACE32答案和资源。
一旦可用，我们也可以尝试允许AI代理通过PRACTICE直接与TRACE32接口（像人类专家一样），真正“解锁”所有TRACE32功能供AI使用。
但在此之前，我们需要某种“包装器接口”到TRACE32，AI可以理解。目前，我们选择了上述“MCP + 代理技能 + PRACTICE脚本”方法，因为它还允许用户自定义和扩展，同时允许AI访问几乎任何TRACE32功能（一旦作为脚本提供）。
在此期间，**您可以让我们的TRACE32 AI助手帮助您编写自己的技能和扩展PRACTICE脚本！**
# 许可证
该项目根据Apache License, Version 2.0许可。详见
[LICENSE](LICENSE) 文件。
