MCP 服务器

Agent2Canoe MCP Server

MCP server that enables AI agents to interact with Vector CANoe for automotive bus testing and diagnostics using natural language commands.

README

<h1 align="center">Agent2Canoe</h1>

<p align="center"> <strong>让 Claude Code、Codex 与其他 AI 智能体安全、可验证地驱动 Vector CANoe</strong> </p>

<p align="center"> 从自然语言意图到能力发现、执行计划、人工确认、CANoe 操作与结构化证据，<br> 为汽车电子自动化开发提供统一的 Python、REST 与 MCP 接口。 </p>

<p align="center"> <a href="#快速开始">快速开始</a> · <a href="#ai--mcp-接入">AI / MCP</a> · <a href="docs/automation.md">自动化指南</a> · <a href="docs/ai-agent-integration.md">集成文档</a> · <a href="docs/engineering-audit-v0.2.0.md">工程审计</a> · <a href="CHANGELOG.md">变更记录</a> · <a href="README_EN.md">English</a> </p>

为什么是 Agent2Canoe

传统 CANoe 自动化解决了“脚本如何调用工具”，Agent2Canoe 进一步解决“AI 如何理解工程、约束操作并证明结果”。

<table> <tr> <td width="33%" valign="top"> <h3>🔎 先发现，再执行</h3> 读取当前工程中的网络、数据库、信号、系统变量、诊断、测试与 CAPL 能力，避免 AI 凭空假设。 </td> <td width="33%" valign="top"> <h3>🛡️ 副作用可控</h3> 写信号、改网络、运行诊断和测试前生成计划；危险步骤需要明确确认，并支持 dry-run。 </td> <td width="33%" valign="top"> <h3>📊 结果可审计</h3> 返回结构化状态、测试统计、报告路径和执行证据，让智能体能够继续判断，而不是只得到一行日志。 </td> </tr> </table>

当前开发线能做什么

能力域	已集成能力	可用入口
CANoe 会话	打开/附着配置、启动/停止测量、恢复与退出	Python · REST · MCP
工程能力发现	版本 provider、分区探针、网络、信号、变量、诊断、测试与降级证据	REST · MCP
网络管理	事务预览、快照冲突检测、批量增删、回读验证与失败回滚	Python · REST · MCP
测试结果统计	用例快照、通过/失败/其他数量、通过率、报告路径	Python
AI 安全编排	计划预览、短时单次令牌、幂等重试、持久化审计与恢复检查点	REST · MCP
身份与权限	API Key 摘要、mTLS、五级角色权限、签发者/执行者审计	REST · MCP
硬件映射审计	检查 Windows、位宽、XL Driver DLL 和开放阻塞项	Python · REST · MCP

硬件安全边界

v0.2.0 的物理硬件通道写映射仍保持关闭。该能力依赖可审计的 Vector XL Driver SDK 来源、ABI/位宽验证以及真实 VN 设备回归；当前版本只提供只读前提审计，不打包第三方二进制。

AI 执行闭环

AI 不应直接把一句自然语言变成不可见的 COM 调用。Agent2Canoe 将工作拆成可检查的步骤：

读取 canoe_status，确认会话与测量状态。
调用 describe_agent_capabilities，了解接口、约束和确认策略。
调用 discover_capabilities，发现当前工程真正存在的对象。
受约束命令使用 plan_task；自由工程语言读取 get_planning_contract 后通过 plan_model_output 提交受 Schema 约束的候选。
用户确认带副作用的步骤；调用 confirm_plan_steps 获取参数绑定令牌。
将步骤 ID 与短时单次令牌传给 execute_plan。
根据结构化返回值复核实际状态、统计与证据。

快速开始

1. 准备环境

Agent2Canoe 运行于 Windows。真实自动化需要本机已安装并获得许可的 Vector CANoe；没有 CANoe 时仍可使用 Mock 后端开发和验证 AI 工作流。

git clone https://github.com/suzike/Agent2Canoe.git
cd Agent2Canoe
uv sync --all-extras

2. 用 Python 控制 CANoe

from agent2canoe import Agent2Canoe

canoe = Agent2Canoe()
canoe.open(r"C:\work\demo.cfg")
canoe.start_measurement()

for network in canoe.list_networks():
    print(network)

canoe.stop_measurement()

3. 不连接 CANoe 先验证

# 查看命令行入口
uv run agent2canoe --version

# 启动 Mock REST 服务
uv run agent2canoe-api --mock --port 8765

# 启动 Mock MCP 服务
uv run agent2canoe-mcp --mock --principal codex-local --roles viewer,operator,approver

AI / MCP 接入

Claude Code、Codex 或其他支持 MCP 的客户端可通过 stdio 启动 Agent2Canoe：

{
  "mcpServers": {
    "Agent2Canoe": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\Agent2Canoe",
        "run",
        "agent2canoe-mcp",
        "--principal",
        "codex-workbench",
        "--roles",
        "viewer,operator,approver"
      ]
    }
  }
}

MCP 工具一览

工具组	代表工具	用途
状态与发现	`canoe_status` · `describe_agent_capabilities` · `discover_capabilities`	建立真实工程上下文
计划契约	`get_planning_contract` · `plan_model_output`	约束 LLM 输出并绑定真实能力快照
计划与执行	`plan_task` · `execute_plan`	预览、确认并执行确定性计划
确认授权	`request_confirmation_token` · `confirm_plan_steps`	为已批准的精确参数签发短时单次令牌
审计与恢复	`list_audit_records` · `get_recovery_checkpoint` · `restore_recovery_checkpoint`	查询脱敏证据，先预览再恢复会话
网络事务	`preview_network_transaction` · `commit_network_transaction`	预览差异，确认后批量修改、回读并在失败时回滚
兼容网络操作	`list_networks` · `add_network` · `remove_network`	单项操作也经事务内核执行
工程操作	信号、系统变量、诊断、测试相关工具	驱动具体 CANoe 工作
硬件审计	`audit_hardware_mapping`	只读检查硬件映射开放前提

完整配置、确认语义和调用示例参见 AI 智能体集成指南。

REST API

uv run agent2canoe-api --mock --port 8765

方法	路径	用途
`GET`	`/agent/capabilities`	返回 AI 能力、约束与接口清单
`GET`	`/security/whoami`	返回当前主体、角色、权限与认证方式
`GET`	`/capabilities`	发现当前 CANoe 工程对象
`GET`	`/planning/contract`	返回能力指纹和严格 LLM 输出 Schema
`POST`	`/plans`	由自然语言或结构化任务生成计划
`POST`	`/plans/model`	校验 LLM 候选并生成不可绕过安全策略的计划
`POST`	`/confirmations`	为一个已批准的直接操作签发令牌
`POST`	`/plans/{id}/confirmations`	为选定计划步骤签发令牌
`POST`	`/plans/{id}/execute`	在确认策略约束下执行计划
`GET`	`/audit/records`	按游标、类型或计划查询持久化脱敏审计
`GET/POST`	`/recovery/checkpoint[/{id}]`	查询、预览或确认执行恢复检查点
`GET/POST/DELETE`	`/networks`	网络管理
`POST`	`/networks/transactions/preview`	返回写前快照、差异和确认参数
`POST`	`/networks/transactions/commit`	校验快照后提交、回读并按需回滚
`GET`	`/hardware/audit`	只读硬件映射前提审计

直接写操作缺少有效令牌时返回 HTTP 428。令牌绑定运行时会话、动作、参数哈希和有效期，且只能使用一次；详细协议见短时确认令牌。 REST 可启用 API Key 摘要认证和 mTLS，MCP stdio 可指定进程主体与最小角色；完整配置见身份认证、角色权限与 mTLS。 REST 与 MCP 命令行入口默认把审计、计划、幂等结果和检查点保存到本地 SQLite；可选 JSONL 镜像及恢复流程见持久化审计、幂等与恢复。多网络变更应使用预览与提交两阶段接口；完整协议见可验证网络事务。版本识别、兼容状态和分区探针语义见 CANoe 版本兼容与能力探针。自由自然语言的两阶段 Schema、能力指纹和 Provider 接口见 LLM 结构化规划适配器。

项目结构

Agent2Canoe/
├─ src/
│  ├─ agent2canoe/          # 新品牌公共入口
│  └─ py_canoe/             # CANoe 实现与兼容层
│     └─ automation/        # 发现、计划、安全、REST、MCP、硬件审计
├─ tests/                   # 单元、Mock 与自动化接口测试
├─ integration_test/        # 需真实 CANoe 许可的集成测试
├─ docs/                    # 指南、审计与 API 文档
└─ demo/                    # 示例工程与脚本

v0.2.0 的首选导入路径是 agent2canoe。底层 py_canoe 暂作为兼容层保留，已有脚本可渐进迁移；新的 CLI、发布包、文档和 MCP 标识统一使用 Agent2Canoe。

开发与质量门禁

uv run ruff check src/agent2canoe src/py_canoe/automation tests
uv run pytest -q
uv build
uv run mkdocs build --strict

真实 CANoe 集成测试不会默认执行，需显式设置：

$env:AGENT2CANOE_RUN_INTEGRATION = "1"
uv run pytest integration_test -m integration

当前基线	结果
默认测试套件	334 passed · 27 skipped
Python 3.10 / 3.14 自动化子集	各 85 passed
文档严格构建	通过
Wheel 隔离安装与导入	通过

以上为 0.3.0.dev0 本地开发线结果；最新状态以 GitHub Actions 为准。

真实 CANoe 12.0.75 已通过 MCP 打开 Vector Easy.cfg，发现 19 项能力（含 2 个网络、1 个数据库和 4 个信号），并完成测量启动、Running 回读、测量停止和 Stopped 回读。Codex/Claude Code 仍需分别注册 Agent2Canoe MCP 并重启客户端，注册前不会在其工具列表中出现。

版本路线

版本	主题	状态
`v0.1.0`	本地工程基线、基础自动化与中文文档	✅ 已完成
`v0.2.0`	Agent2Canoe 品牌、测试统计、网络管理、AI 发现与 MCP	✅ 已发布
`v0.3.0`	LLM 结构化规划、确认令牌、审计、认证授权与网络事务	🚧 开发中
`v0.4.x`	硬件实验台验证、版本适配与工程模板	🧭 规划中

进一步的风险、技术债与能力增强建议见 v0.2.0 工程审计和硬件通道映射独立审计。

文档导航

许可证

Agent2Canoe 采用 MIT License。Vector、CANoe 及相关产品名称归其各自权利人所有；本项目不随包分发 CANoe、Vector SDK 或驱动二进制文件。