MCP C# SDK 2.0 与上位机工具调用

内容类型：方法说明难度：进阶适合：想用 MCP 让 AI 调用上位机诊断、构建、测试或设备工具的开发者阅读时间：约 15 分钟前置：已了解 MCP 与 AI Agent 基本概念

MCP 解决的是“模型怎样发现并调用工具”，不是“模型怎样自动接管设备”。

对 C# 上位机来说，真正值得 MCP 化的是：把日志、解析、构建、测试和受控诊断做成输入输出清楚、权限明确、可以留下证据的工具。

1. MCP 在这里扮演什么角色

text

工程师提出任务
    ↓
Agent 判断缺什么证据
    ↓
MCP Client 请求获准能力
    ↓
C# MCP Server 做权限和参数检查
    ↓
调用项目内稳定能力
    ↓
返回结构化结果 + 证据状态

关键不在“能注册多少 Tool”，而在 C# MCP Server 只暴露允许 Agent 使用的能力边界。

2. 先按副作用给工具分级

建议先分能力，再决定是否开放：

级别	例子	默认策略
LocalRead	查项目结构、读脱敏配置、读指定日志	可开放，限制路径/大小
PureCompute	协议解析、CRC/换算、日志聚合	优先开放
BuildTest	affected build、固定测试/filter、Replay	可开放，参数白名单
HardwareRead	查询设备状态、error queue、版本	只有安全+授权+不扰动现场时
HardwareWrite	输出、高压、运动、阀门、配置写入	默认不开放；需要 HITL

不要只按“GET/SET”“QUERY/WRITE”名字判断副作用。某些所谓查询可能会清空 error queue、改变游标、抢占会话或扰动当前试验。

3. 第一版优先只做软件侧工具

一个很实用的 MVP 可以只有：

parse_frame：输入受限 HEX / 文本，返回解析字段和错误位置；
search_log：只读允许目录中的脱敏日志；
run_focused_test：运行固定项目和受限 filter；
replay_scenario：对 Captured Replay 运行当前 parser/workflow；
query_project_fact：读取 solution、项目和稳定配置摘要。

这些已经能明显提高 Bug、协议和 Review 效率，不需要第一天就让 Agent 控制真机。

4. MCP v2 stateless ≠ 设备连接每次重建

官方 MCP C# SDK v2.0 的 HTTP transport 默认 stateless。这解决的是 MCP 协议层的请求状态，不是物理设备生命周期。

不要写成：

text

每次 MCP tools/call
→ new SerialPort / new VISA / new SCPI client
→ query
→ dispose

真实上位机更常需要：

text

MCP Tool
→ Application/Diagnostic Service
→ existing Device Session Owner
→ SerialPort / TCP / SCPI / VISA

设备 Session 的建立、占用、取消、Stop、重连和 Dispose 仍由应用自己的稳定 owner 管理。

因此：

MCP transport 是否 stateless，与设备通信是否 single-session / long-lived 是两个完全不同的问题。

5. 不要为了 MCP 诊断偷偷打开第二设备会话

如果设备只能单连接，或者现有试验流程已经拥有该 Session：

诊断 Tool 默认复用现有 owner；
没有安全读取 seam 时宁可返回 HardwarePending；
不为了“查询方便”临时建立第二 SCPI/VISA/SerialPort 会话；
不让 MCP 工具绕过现有 workflow/safety gate 直达底层 Send。

否则 Agent 为了取证本身就会改变故障现场。

6. HardwareRead 也需要三项前提

真实设备只读 Tool 只有同时满足以下条件才执行：

text

SafeToQuery = true
Authorized = true
SessionOwnershipSafe = true

还要确认：

查询不会改变输出/模式；
不会清空后续需要的错误信息；
不会打断正在运行的测试窗口；
当前设备手册/项目经验支持该查询安全。

不满足时返回结构化结果，例如：

text

VerificationState: HardwarePending
Reason: 当前试验占用设备 Session，未执行只读查询

而不是擅自连接设备。

7. HardwareWrite 默认不要作为普通 Tool

高压、运动、继电器、阀门、加热、气路、联锁、关键配置写入等动作不应变成模型可自由调用的普通 Tool。

确实需要时至少经过：

text

业务权限
→ 明确参数范围
→ 当前状态/联锁检查
→ 人工确认当前动作
→ 后端再次校验
→ 执行动作
→ 审计日志

对于高风险动作，即使“用户已经允许真机测试”，也保持 HITL，而不是给 Agent 一个长期开放的万能 send_command。

8. 工具接口要窄，不要暴露任意 Shell / 任意路径

不推荐：

text

run_command(string shell)
read_file(string anyPath)
send_scpi(string anyCommand)

更安全也更容易验证的是：

text

run_affected_build(ProjectId, Configuration)
search_diagnostic_log(TimeRange, DeviceId, Keyword)
replay_scenario(ScenarioId)
query_device_status(DeviceId)

参数应该：

有明确类型；
有长度/范围；
路径白名单；
设备/项目使用稳定 ID；
拒绝任意命令拼接；
失败返回结构化原因。

9. Tool 返回值不仅要“成功/失败”

建议返回足够形成证据链的结果：

text

Operation
Target
Timestamp
Result
Evidence
VerificationState
SideEffect

例如：

text

Operation: ReplayProtocol
Scenario: raw-timeout-001
Result: Passed
VerificationState: Verified
SideEffect: None

或者：

text

Operation: QueryHardwareStatus
Result: NotExecuted
VerificationState: HardwarePending
Reason: 当前真实设备查询未获授权
SideEffect: None

这样 Agent 不会把“Tool 没执行”误写成“设备正常”。

10. MCP Tool 与 V10 Verification Level 怎么配合

Tool 类别	常见作用
PureCompute / static	V0/V1 证据
affected build	V1/V2
focused test / Replay	V2/V3
workflow simulator	V3
HardwareRead	工程/现场补充证据，不自动替代 HITL
HardwareWrite	只在明确业务和安全授权下进入现场验证

MCP 只是执行通道，不会自动提高证据等级。

11. 日志和 Replay 是最适合先 MCP 化的能力

上位机现场问题经常需要：

text

读取一小段日志
→ 按时间对齐
→ 找 first anomaly
→ 找原始 TX/RX
→ Replay
→ 同输入比较修复前后

这类工具副作用低、可重复、证据价值高，通常比“让 Agent 直接控制设备试一遍”更值得优先投入。

详见日志与时间线诊断和通信证据包。

12. 服务部署边界

不要求所有项目都把 MCP Server 塞进主上位机进程。

常见选择：

独立诊断服务

优点：权限边界清楚、Agent 异常不直接拖垮 UI/设备控制进程。

进程内受限 Tool Adapter

适合：必须复用已有 Device Session Owner，且项目已经有清楚的 application/safety seam。

决定依据是生命周期和安全边界，不是“微服务更先进”或“进程内更简单”。

13. 最小验收

第一版 MCP 工具至少验证：

参数缺失/非法时拒绝；
超长报文和非法路径被拒绝；
Tool failure 不让服务进程退出；
0 tests matched 不写成 Verified；
每次调用有时间、Tool、目标和结果；
Agent 结论可以追溯到 Tool 返回值；
HardwareRead 未满足安全条件时返回 HardwarePending；
HardwareWrite 没有被意外暴露成通用命令接口。

14. 常见反模式

MCP Server 能运行，就把整套设备控制对象全部注册成 Tool；
send_scpi(any string) 直接开放给模型；
MCP v2 HTTP stateless，就每次查询重建设备 Session；
为诊断开第二个设备会话改变故障现场；
Tool 只返回 true/false，无法形成证据；
Fake/Replay 工具成功后写“真机已验证”；
用 Prompt 要求模型“谨慎”代替后端权限和参数校验。

15. 和现有项目怎么衔接

优先复用现有稳定边界：

text

Tool
→ existing application service
→ existing parser / replay / log reader / session owner

不要为了 MCP 把一个本来稳定的项目重新设计成另一套架构。

下一步

继续学习

用 AI 分析 MSBuild Binary Log

工具调用里最有价值的一类，就是把构建和日志变成可重复查询的工程证据。

下一步 →

MCP C# SDK 2.0 与上位机工具调用 ​

1. MCP 在这里扮演什么角色 ​

2. 先按副作用给工具分级 ​

3. 第一版优先只做软件侧工具 ​

4. MCP v2 stateless ≠ 设备连接每次重建 ​

5. 不要为了 MCP 诊断偷偷打开第二设备会话 ​

6. HardwareRead 也需要三项前提 ​

7. HardwareWrite 默认不要作为普通 Tool ​

8. 工具接口要窄，不要暴露任意 Shell / 任意路径 ​

9. Tool 返回值不仅要“成功/失败” ​

10. MCP Tool 与 V10 Verification Level 怎么配合 ​

11. 日志和 Replay 是最适合先 MCP 化的能力 ​

12. 服务部署边界 ​

独立诊断服务 ​

进程内受限 Tool Adapter ​

13. 最小验收 ​

14. 常见反模式 ​

15. 和现有项目怎么衔接 ​

下一步 ​

用 AI 分析 MSBuild Binary Log

MCP C# SDK 2.0 与上位机工具调用

1. MCP 在这里扮演什么角色

2. 先按副作用给工具分级

3. 第一版优先只做软件侧工具

4. MCP v2 stateless ≠ 设备连接每次重建

5. 不要为了 MCP 诊断偷偷打开第二设备会话

6. HardwareRead 也需要三项前提

7. HardwareWrite 默认不要作为普通 Tool

8. 工具接口要窄，不要暴露任意 Shell / 任意路径

9. Tool 返回值不仅要“成功/失败”

10. MCP Tool 与 V10 Verification Level 怎么配合

11. 日志和 Replay 是最适合先 MCP 化的能力

12. 服务部署边界

独立诊断服务

进程内受限 Tool Adapter

13. 最小验收

14. 常见反模式

15. 和现有项目怎么衔接

下一步