# UDS-Test-MCP

**Repository Path**: tom-embedded/uds-test-mcp

## Basic Information

- **Project Name**: UDS-Test-MCP
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UDS 测试 MCP（uds-test-mcp）

基于 python-can 的 UDS 诊断测试 MCP 工具服务器。零依赖 MCP stdio 协议层
（标准库实现，Python >= 3.8），支持 ZCode / Claude Desktop / Cursor 等
stdio MCP 客户端。

## 能力

- **CAN 链路**：PCAN（PCAN_USBBUSn）与 Vector（VN 系列，serial 精确定位）；
  经典 CAN 与 CAN FD（fd=true + data_bitrate）
- **ISO-TP**：完整 SF/FF/CF/FC 收发状态机（FD 12bit+32bit 转义、块控制
  BS/STmin、SN 循环校验），外加**协议注入原语**（错误 SN、超长 FF、
  FC.WT 洪水、FF 后无 FC）——传输层中止/NRC 回送用例必备
- **UDS 客户端**：raw hex / DID / 会话便捷请求，0x78 pending 跟随，
  NRC 名称解析，功能寻址
- **时间参数测量**：P2/P2* 分布统计（rounds 采样）、S3 会话保持时长
  （探测回落）、STmin 遵守度（声明 STmin 收长响应测 CF 间隔）、
  会话参数声明值读取（10 xx 响应 byte2..5）
- **安全算法独立层**：与项目解耦，四种来源
  - `xor` 常量族（按等级映射，如 ACM 的 SAL1/2/3）
  - `expr` 表达式沙箱（`seed ^ 0xABCDEFAB`，seed 为大端整数）
  - `python` 自定义代码（定义 `compute(seed: bytes, level: int) -> bytes`）
  - `dll` SeedKey DLL（ctypes，stdcall/cdecl 自动嗅探，四参/五参签名自适应；
    注意 DLL 位数须与本进程 Python 一致）
- **数据源驱动测试**：
  - Excel 调查表：**标准用例模板**（见下）自动识别；**电气诊断表**
    （信号×短路/开路矩阵）与 **DTC 故障表**（故障名称/标志位/阈值）
    解析并可生成 19 服务用例
  - ODX/PDX：内置轻量 XML 解析——服务清单（请求字节模板）、DTC 清单、
    读类服务自动生成用例（写类 2E/31/27/11/14/85/28 一律不自动生成）

## 安装

```bash
pip install python-can openpyxl   # 仅两个依赖
python tests/test_all.py          # 离线自检(29 项, 虚拟总线全链路)
```

## MCP 注册（ZCode / Claude Desktop）

```json
{
  "mcpServers": {
    "uds-test": {
      "command": "python",
      "args": ["D:/workspace/uds-mcp/server.py"]
    }
  }
}
```

## 工具一览

| 工具 | 用途 |
|---|---|
| `uds_info` | 依赖/连接状态 |
| `uds_scan_channels` | 扫描 PCAN/Vector 通道（只开不发） |
| `uds_connect` | 建链（通道/ID/FD/时序/安全算法一次性配置） |
| `uds_send` | UDS 请求（hex / did / session 便捷形式） |
| `uds_send_raw_frame` | 帧级原始发送（注入原语） |
| `uds_sniff` | 总线监听（ID 过滤） |
| `uds_isotp_inject` | 协议故障注入（wrong_sn / ovflw_ff / wft_ovrn / no_fc，可选期望 NRC 比对+探活） |
| `uds_timing_measure` | p2 / s3 / stmin / session_params 四类时序测量 |
| `uds_security_unlock` | 27 解锁（连接配置算法或临时 spec） |
| `uds_security_selftest` | 算法自验（不碰总线） |
| `uds_load_source` | 加载 Excel/ODX 调查数据源 |
| `uds_run_suite` | 批量执行用例（数据源生成用例或内联 cases） |
| `uds_last_report` | 最近报告 |

示例：`uds_connect` 参数见 `config/acm_tc367.json`（ACM 后桥 0x7A1，
VN1610 serial 定位，SAL1/2/3 XOR 族）。

## 标准用例模板（Excel）

建一张表头包含 **用例ID / 服务 / 期望** 的 sheet（大小写不敏感，列顺序
任意），每行一个用例：

| 列 | 说明 | 示例 |
|---|---|---|
| 用例ID | 唯一标识 | T01 |
| 描述 | 用途说明 | 读 VIN |
| 前置会话 | 空=默认 / 03=扩展 | 03 |
| 安全等级 | 空=不解锁 / 0x61 | 0x61 |
| 服务 | 请求字节 | 22 F1 90 |
| 功能寻址 | 是/空 | |
| 期望 | 断言（见下） | 62 F1 90 |
| 备注 | 自由文本 | |

**断言语法**：`62 F1 90`（正响应前缀匹配）/ `NRC:31` 或 `NRC:31\|33`
（多值）/ `POS`（仅要求正响应）/ `TIMEOUT`（期望超时）/ 空（只发不判）。

## 典型工作流

1. `uds_scan_channels` → `uds_connect`（+security spec）
2. 冒烟：`uds_send {"hex":"10 03"}` → `uds_send {"hex":"22 F1 90"}`
3. 时序：`uds_timing_measure {"kind":"p2","hex":"22 F1 90","rounds":20}`、
   `{"kind":"s3"}`、`{"kind":"stmin","hex":"22 FE 02","stmin":"0x0A"}`
4. 注入：`uds_isotp_inject {"scenario":"wft_ovrn","request_hex":"22 FE 02",
   "expect_nrc":"0x72"}`
5. 调查表：`uds_load_source {"path":"D:/xxx/诊断调查表.xlsx"}` →
   `uds_run_suite {"source":"<path>"}` → 报告

## 安全提示

`0x2E/0x31/0x27/0x14/0x11/0x85/0x28` 等服务会改写/复位真实 ECU。
注入工具只影响诊断 ID 通道；ODX 自动生成只覆盖读类服务。写类用例
请人工确认参数后通过 `uds_send` 或模板明确写出。

## 目录

```
server.py            MCP 入口(stdio JSON-RPC 2.0)
uds_mcp/can_link.py  PCAN/Vector/FD 链路层(驱动时间戳归一)
uds_mcp/isotp.py     ISO-TP 组帧/收发/注入原语
uds_mcp/uds_client.py UDS 请求/响应/安全访问流程
uds_mcp/timing.py    P2/P2*/S3/STmin 测量
uds_mcp/security.py  安全算法独立层(xor/expr/python/dll)
uds_mcp/diag_excel.py 调查表解析(标准模板/电气诊断/DTC表)
uds_mcp/diag_odx.py  ODX/PDX 轻量解析
uds_mcp/runner.py    用例执行器+断言引擎+报告
tests/mock_ecu.py    虚拟总线 Mock ECU
tests/test_all.py    离线全量测试(29 项)
config/acm_tc367.json 连接示例
```