## 接口定义
### 全局配置（服务器启动时传入）
MCP 服务器启动时通过命令行参数或环境变量指定，一次配置，永久生效。
| 参数 | 类型 | 默认值 | 说明 |
| ------------------- | ------- | --------------------- | ------------------------------------------------------------ |
| `--openocd-path` | string | `"openocd"` | OpenOCD 可执行文件路径（若在 PATH 中可不填） |
| `--gdb-path` | string | `"arm-none-eabi-gdb"` | GDB 可执行文件路径 |
| `--openocd-scripts` | string | `""` | OpenOCD 脚本搜索路径（可选，用于查找 interface/target 脚本） |
示例启动命令：
```bash
python openocd-mcp.py --openocd-path /usr/bin/openocd --gdb-path /usr/bin/arm-none-eabi-gdb
```
---
### 工具接口定义
所有工具返回 **字符串**。成功时返回可读的执行结果（如日志、状态 JSON）；失败时返回以 `"Error: "` 开头的错误信息。
---
#### 1. `set_project`
- **描述**：设置当前工作项目目录，并加载该目录下的 `.vscode/launch.json`，解析所有调试配置。如果之前已有项目设置，会清除当前调试会话（如有）并替换为新的配置列表。
- **输入**（JSON Schema）：
```json
{
"type": "object",
"properties": {
"project_dir": {
"type": "string",
"description": "项目根目录的绝对路径"
}
},
"required": ["project_dir"]
}
```
- **成功返回示例**：
```
Project set to /home/user/myproject
Loaded 3 debug configurations:
- Debug i2c_master_demo
- Debug i2c_slave_demo
- Debug mbootloader
```
- **失败返回示例**：
```
Error: Project directory /home/user/myproject does not exist.
```
```
Error: Could not find .vscode/launch.json in the project directory.
```
```
Error: Failed to parse launch.json: invalid JSON format.
```
---
#### 2. `refresh_debug_targets`
- **描述**：重新读取当前项目目录下的 `.vscode/launch.json`，刷新调试配置列表，并返回可用的配置名称。如果尚未设置项目目录，则返回错误。
- **输入**：无参数
- **成功返回示例**：
```
Refreshed debug targets. Available configurations:
- Debug i2c_master_demo
- Debug i2c_slave_demo
- Debug mbootloader
```
- **失败返回示例**：
```
Error: No project set. Please call set_project first.
```
```
Error: launch.json not found or unreadable.
```
---
#### 3. `flash_download`
- **描述**：根据指定的配置名称（来自 `launch.json`）执行一次性烧录。可选择覆盖固件路径。烧录完成后不启动调试会话。
- **输入**：
```json
{
"type": "object",
"properties": {
"config_name": {
"type": "string",
"description": "launch.json 中的配置名称，如 'Debug mbootloader'"
},
"firmware_path": {
"type": "string",
"description": "可选，覆盖配置中的 executable 路径"
}
},
"required": ["config_name"]
}
```
- **成功返回示例**：
```
Flashing firmware /home/user/myproject/build/artifacts/mbootloader.elf using config 'Debug mbootloader'...
OpenOCD output:
** Programming Started **
** Programming Finished **
** Verify Started **
** Verified OK **
** Resetting Target **
Flash done.
```
- **失败返回示例**：
```
Error: Config 'Debug mbootloader' not found in current project.
```
```
Error: Firmware file /home/user/myproject/build/artifacts/mbootloader.elf does not exist.
```
```
Error: OpenOCD execution failed: timeout / no device found.
```
---
#### 4. `debug_start`
- **描述**：根据配置名称启动调试会话。自动启动 OpenOCD（作为 GDB Server）和 GDB，连接目标，加载固件，并根据配置中的 `runToEntryPoint`（如 `"main"`）设置断点并运行。
- **输入**：
```json
{
"type": "object",
"properties": {
"config_name": {
"type": "string",
"description": "launch.json 中的配置名称"
},
"firmware_path": {
"type": "string",
"description": "可选，覆盖 executable 路径"
}
},
"required": ["config_name"]
}
```
- **成功返回示例**：
```
Debug session started with config 'Debug mbootloader'
OpenOCD PID: 12345
GDB PID: 12346
Loaded firmware /home/user/myproject/build/artifacts/mbootloader.elf
Running to main...
Stopped at main (breakpoint hit)
Ready for debug commands.
```
- **失败返回示例**：
```
Error: Config 'Debug mbootloader' not found.
```
```
Error: Firmware file missing.
```
```
Error: OpenOCD failed to start: address already in use.
```
```
Error: GDB connection failed: target remote :3333 timeout.
```
---
#### 5. `debug_stop`
- **描述**：终止当前调试会话（关闭 OpenOCD、GDB）。如果当前没有活跃会话，返回错误。
- **输入**：无参数
- **成功返回示例**：
```
Debug session terminated.
```
- **失败返回示例**：
```
Error: No active debug session to stop.
```
---
#### 6. `debug_command`
- **描述**：在当前调试会话中执行任意 GDB 命令，并返回命令输出。会话必须已由 `debug_start` 启动。
- **输入**：
```json
{
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "GDB 命令，如 'next', 'print x', 'break main'"
}
},
"required": ["command"]
}
```
- **成功返回示例**（执行 `print x`）：
```
$1 = 42
```
- **失败返回示例**：
```
Error: No active debug session. Call debug_start first.
```
```
Error: GDB command failed: (gdb) print x
No symbol "x" in current context.
```
---
#### 7. `debug_status`
- **描述**：查询当前调试会话的状态，以及当前项目的可用配置列表。返回 JSON 格式的文本。
- **输入**：无参数
- **成功返回示例**（会话活跃时）：
```json
{
"session_active": true,
"config_name": "Debug mbootloader",
"firmware": "/home/user/myproject/build/artifacts/mbootloader.elf",
"openocd_pid": 12345,
"gdb_pid": 12346,
"project_dir": "/home/user/myproject",
"available_configs": ["Debug i2c_master_demo", "Debug i2c_slave_demo", "Debug mbootloader"]
}
```
- **成功返回示例**（无活跃会话，但项目已设置）：
```json
{
"session_active": false,
"project_dir": "/home/user/myproject",
"available_configs": ["Debug i2c_master_demo", "Debug i2c_slave_demo", "Debug mbootloader"]
}
```
- **成功返回示例**（未设置项目）：
```json
{
"session_active": false,
"project_dir": null,
"available_configs": []
}
```
- **失败**：不会失败，总是返回当前状态。
---
#### 8. `get_runtime_config`
- **描述**：查询当前服务实际生效的运行时配置（OpenOCD/GDB 路径、脚本路径）及其来源（命令行、环境变量、`config.json` 或默认值），用于排查配置问题。返回 JSON 格式的文本。
- **输入**：无参数
- **成功返回示例**：
```json
{
"openocd_path": "D:/sdk/OpenOCD/bin/openocd.exe",
"gdb_path": "D:/sdk/Arm GNU Toolchain arm-none-eabi/11.3 rel1/bin/arm-none-eabi-gdb.exe",
"openocd_scripts": "",
"sources": {
"openocd_path": "config.json",
"gdb_path": "config.json",
"openocd_scripts": "default"
},
"cwd": "D:/WorkSpace/openocd-mcp",
"config_file": "D:/WorkSpace/openocd-mcp/config.json",
"config_file_exists": true
}
```
- **失败**：不会失败，总是返回当前配置状态（异常会被捕获并以 `Error: ` 返回）。
---
### MVP 范围说明
- 当前 MVP 阶段不包含 RTT 相关能力。
- RTT 的接口与架构设计已迁移到独立文档：`RTT特性.md`。
### 路径变量替换规则
在解析 `launch.json` 时，自动替换以下变量：
- `${workspaceRoot}`、`${workspaceFolder}` → 替换为 `project_dir`（绝对路径）。
- 如果配置中有 `cwd`，则 `executable` 的相对路径基于 `cwd` 解析，否则基于 `project_dir` 解析。
- `configFiles` 中的路径保持原样（相对路径在启动 OpenOCD 时，工作目录设为 `project_dir`，可正常查找）。
### 错误处理约定
- 所有工具返回**纯文本字符串**。
- 成功时直接返回可读结果（如日志、状态 JSON）。
- 失败时字符串必须以 `"Error: "` 开头，后跟具体错误描述。
- 工具内部应捕获所有异常，转换为友好的错误信息返回，避免服务器崩溃。
### 工具列表速览
| 工具名 | 描述 | 必需参数 |
| ----------------------- | -------------------- | ---------------- |
| `set_project` | 设置项目目录 | `project_dir` |
| `refresh_debug_targets` | 重新加载 launch.json | 无 |
| `flash_download` | 一次性烧录 | `config_name` |
| `debug_start` | 启动调试会话 | `config_name` |
| `debug_stop` | 停止当前会话 | 无 |
| `debug_command` | 执行 GDB 命令 | `command` |
| `debug_status` | 查询状态 | 无 |
| `get_runtime_config` | 查询运行时配置 | 无 |
