Agent2Canoe MCP Server

<p align="center"> <img src="https://raw.githubusercontent.com/suzike/Agent2Canoe/main/docs/assets/agent2canoe-hero.png" alt="Agent2Canoe：AI 驱动的 CANoe 自动化开发工具包" width="100%"> </p>

<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="https://github.com/suzike/Agent2Canoe/actions/workflows/automation-tests.yml"><img alt="自动化测试" src="https://github.com/suzike/Agent2Canoe/actions/workflows/automation-tests.yml/badge.svg"></a> <a href="https://github.com/suzike/Agent2Canoe/actions/workflows/pylint.yml"><img alt="静态检查" src="https://github.com/suzike/Agent2Canoe/actions/workflows/pylint.yml/badge.svg"></a> <img alt="Python 3.10-3.14" src="https://img.shields.io/badge/Python-3.10--3.14-3776AB?logo=python&logoColor=white"> <img alt="版本 0.2.0" src="https://img.shields.io/badge/version-0.2.0-7C3AED"> <img alt="Windows" src="https://img.shields.io/badge/platform-Windows-0078D4?logo=windows"> <img alt="许可证 MIT" src="https://img.shields.io/badge/license-MIT-22C55E"> </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>

<p align="center"> <img src="https://raw.githubusercontent.com/suzike/Agent2Canoe/main/docs/assets/agent2canoe-architecture.svg" alt="Agent2Canoe 分层架构：AI 客户端、接入层、编排安全层、CANoe 自动化层和工程资产" width="96%"> </p>

当前开发线能做什么

能力域	已集成能力	可用入口
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 设备回归；当前版本只提供只读前提审计，不打包第三方二进制。

<p align="center"> <img src="https://raw.githubusercontent.com/suzike/Agent2Canoe/main/docs/assets/agent2canoe-ai-workbench.png" alt="AI 智能体通过安全编排连接汽车网络测试台架" width="100%"> </p>

AI 执行闭环

<p align="center"> <img src="https://raw.githubusercontent.com/suzike/Agent2Canoe/main/docs/assets/agent2canoe-workflow.svg" alt="从自然语言任务到 CANoe 执行与证据回传的七步闭环" width="96%"> </p>

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

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

快速开始

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 工程审计 和 硬件通道映射独立审计。

文档导航

• 自动化平台指南
• AI 智能体与 MCP 集成
• LLM 结构化规划适配器
• 短时确认令牌
• 身份认证、角色权限与 mTLS
• 持久化审计、幂等与恢复
• 可验证网络事务
• CANoe 版本兼容与能力探针
• 硬件通道映射独立审计
• v0.2.0 工程审计与增强建议
• 版本变更记录
• 安全策略

许可证

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