11. MCP 集成opensovd-mcp1. 背景与原理1.1 MCP 是什么为什么 SOVD 需要它MCPModel Context Protocol是让 LLM 应用连接外部系统的开放协议。它把外部能力抽象为三类原语原语方向类比Tools模型 → 系统可调用函数有参数与输出 schemaResources系统 → 模型可被读取的数据URI 寻址Prompts用户 → 模型预置的提示词模板SOVD 与 MCP 天然契合SOVD 的实体/能力模型是自描述的capabilities HATEOAS几乎不需要额外建模就能提供给 LLM而用自然语言问车怎么了正是诊断场景的直觉交互。1.2 本项目的独特位置opensovd-mcp是连接 SOVD 与 AI Agent 的桥。它复用opensovd-client而非二次实现 HTTP因此 MCP 与客户端共享同一套语义与 bug 修复。2. 当前实现架构2.1 组件#[derive(Clone)] struct McpServer { client: Client, // 复用 opensovd-client tool_router: ToolRouterSelf, }原语实现Toolslist_components、list_areas、list_apps#[tool_router]#[tool]宏Resourcessovd://topology整车拓扑 Markdown 快照Promptsexplore-topologyTransportstdiormcpfeaturetransport-ioCapabilitiestoolsresourcesprompts2.2 启动与连接默认连接http://localhost:7690/sovd/v1cli.rs:31可通过 CLI 覆盖Client::connect(url)建立客户端全生命周期共享注意未设 timeout#[tokio::main(flavor current_thread)]3. 核心流程与算法3.1 Tool 调用流程LLM 调用 list_components │ ├─ client.list_components().schema(true).send().await │ └─ GET /sovd/v1/components?include-schematrue ├─ serde_json::to_value(response)? └─ CallToolResult::structured(value)#[tool_router] impl McpServer { #[tool(description List all SOVD components)] async fn list_components(self) - ResultCallToolResult, McpError { let response self.client.list_components() .send().await .map_err(|e| McpError::internal_error(e.to_string(), None))?; let value serde_json::to_value(response) .map_err(|e| McpError::internal_error(e.to_string(), None))?; Ok(CallToolResult::structured(value)) } // list_areas / list_apps 同构 }3.2 拓扑快照生成算法let (components, areas, apps) tokio::try_join!( async { self.client.list_components().send().await.map_err(..) }, async { self.client.list_areas().send().await.map_err(..) }, async { self.client.list_apps().send().await.map_err(..) }, )?; let mut text String::new(); let _ writeln!(text, # Vehicle Topology\n); let _ writeln!(text, ## Components ({})\n, components.data.items.len()); for component in components.data.items { let _ writeln!(text, - {} (id: {}), component.name, component.id); } // Areas / Apps 同构 ResourceContents::text(text, TOPOLOGY_URI)算法要点try_join!并发拉取三个集合而非串行——减少 2/3 延迟输出 MarkdownLLM 友好的结构化文本let _ writeln!(...)忽略格式化错误String写入不会失败但掩盖了潜在问题3.3 Server 信息与系统提示let capabilities ServerCapabilities::builder() .enable_tools().enable_resources().enable_prompts().build(); // ... .with_instructions( OpenSOVD MCP server for vehicle diagnostics. \ Base URI: /sovd/v1. \ Entity hierarchy: Areas Components Apps Functions. \ Each entity may expose: data, faults, operations, configurations, \ bulk-data, locks, and modes. \ Use the topology resource to explore the vehicle.)注意instructions 声称实体可暴露 data、faults、operations、configurations、bulk-data、locks、modes——但实际只实现了 data。这会让 LLM 产生错误预期尝试调用不存在的能力。4. 待完善与风险4.1 功能性严重只暴露 3 个只读 tool高无数据读写dataGET/PUT、无关系查询hosts/contains、无能力查询capabilities。作为诊断入口当前只能回答车上有什么不能回答这个数据是多少或执行某个操作。系统提示与实际能力不符高instructions 声称支持 faults/operations/configurations/bulk-data/locks/modes实际全无。LLM 会据此生成注定失败的操作序列。应让 instructions 与已实现能力动态一致例如从EntityCapabilities生成。无 output schema中tool 只返回structured内容未声明outputSchema社区已有 issuefeat(mcp): advertise output schema on list tools。客户端无法校验/生成类型。4.2 健壮性严重所有 client 错误降级为internal_error高401/404/超时一律变成-32603调用方LLM 与上层应用无法区分未授权与服务崩溃也无法触发重新认证。应映射401 → 需要凭据404 → 资源不存在超时 → 可重试。Client::connect无超时高见 09 章 §4.2 缺陷 4。MCP 是长驻进程一次挂起会卡死整个会话。read_resource无缓存/无分页中每次读取都并发打 3 个请求大规模车辆数百 Component会生成无上限文本可能超出上下文窗口。应支持分页与增量。read_resource忽略分页参数低对 URI 做精确串比较忽略_request中的分页参数。4.3 集成细节中工具名无前缀中list_components等通用名在多 MCP server 共存时易冲突建议sovd_list_components。只回structured不回content文本中部分 MCP 客户端只渲染content可能出现空结果。建议同时提供文本摘要。let _ writeln!(...)静默吞错低应显式处理或改用write!?。4.4 能力演进建议按价值排序优先级新增能力价值P1sovd_get_data(entity, id, data_id)/sovd_write_data(...)让 LLM 真正能读数据当前最大缺口P1sovd_get_capabilities(entity, id)让 LLM 动态发现能力而非依赖静态 instructionsP2sovd_list_faults需服务端先实现 faults故障诊断的核心场景P2拓扑 resource 增加关系hosts/contains与分页大车辆可承载P2错误语义映射401/404/timeout可恢复性P3elicitation写操作前请求用户确认安全MCP 2025-06 起支持4.5 安全中写能力一旦加入就必须配确认机制中当前全只读风险可控未来加入write_data/operation时必须通过 MCPelicitation让人类确认否则 LLM 会直接改动车辆配置。无认证透传中MCP server 使用固定 URL 连接 SOVD server若服务端启用 JWTMCP 侧没有获取/刷新令牌的机制。5. 关键代码位置内容路径McpServer定义opensovd-cli/mcp/src/main.rs:29-34Tools 实现opensovd-cli/mcp/src/main.rs:36-78Promptopensovd-cli/mcp/src/main.rs:91-108Server capabilities 与 instructionsopensovd-cli/mcp/src/main.rs:110-131Resource 声明opensovd-cli/mcp/src/main.rs:133-142拓扑快照生成opensovd-cli/mcp/src/main.rs:156-212main 与客户端构造opensovd-cli/mcp/src/main.rs:216-258CLI 默认地址opensovd-cli/mcp/src/cli.rs:31依赖rmcpopensovd-cli/mcp/Cargo.toml