M↔ MCP Development Map
Protocol → Product → Production

把模型接上
真实世界

MCP 开发不是“写几个工具函数”。它是一套从能力建模、协议通信、权限边界，到测试、部署与运维的完整接口工程。

进入开发地图 ↓ 看 OpenFOAM 映射
内容基于 MCP 2026-07-28 版官方文档校准
live topologyJSON-RPC 2.0
MCP HostAI 应用 / Agent
Client1 : 1 connection
Server AFiles
Server BDatabase
Server COpenFOAM
data layertransport layer
3Host / Client / Server
2Data / Transport layers
3Tools / Resources / Prompts
2stdio / Streamable HTTP
01 · Architecture

先分清谁负责什么

Host 管理用户体验和模型；Client 维护一条面向某个 Server 的协议连接；Server 把外部系统包装成可发现、可验证、可调用的上下文与动作。点击节点查看职责。

MCP HOST — AI 应用内部
02 · Capability surface

Server 暴露的三种核心能力

最重要的设计决定不是选 Python 还是 TypeScript，而是把业务能力正确分成“动作、数据、工作流模板”。边界越清晰，模型越容易选对能力。

01MODEL-CONTROLLED
{ }

Tools

有副作用或需要计算的可执行函数。用 JSON Schema 明确输入，并返回结构化结果、文本或资源引用。

tools/listtools/call
02APPLICATION-CONTROLLED
◇

Resources

可读取的上下文数据，如文件、数据库记录、日志或网格摘要。用 URI 标识，用 MIME 类型描述。

resources/listresources/read
03USER-CONTROLLED
⌁

Prompts

可复用的交互模板，把领域流程、参数和示例包装为入口，帮助用户稳定地发起复杂任务。

prompts/listprompts/get
C→U

Elicitation

Server 通过 Client 请求用户补充信息或确认关键动作。适合缺参、审批与敏感操作前确认。

DEPRECATED

Sampling / 协议日志

在 2026-07-28 版中已被标记为弃用；新实现应直接连接模型 API，并使用 stderr 或 OpenTelemetry 记录日志。

EXT

可选扩展

Tasks 可为长任务提供持久句柄；MCP Apps 可在兼容 Host 内呈现交互界面。它们属于按需增加的扩展层。

03 · Runtime flow

一次工具调用，协议里发生了什么

MCP 的数据层建立在 JSON-RPC 2.0 之上。当前规范强调无状态请求、每次请求携带版本与能力元数据；发现、列举、调用和通知各有明确消息。

Protocol trace

STEP 01 · DISCOVERY

发现协议版本与能力

Client 可先请求 server/discover，了解 Server 支持的协议版本、能力、身份与缓存策略。

CLIENT → SERVER
request.jsonJSON-RPC 2.0

            

          

        

      

    


    

      

        

          
04 · Engineering stack
真正要开发的七层东西

          
SDK 会替你处理消息封装，但不会替你做领域建模、权限边界、幂等性、资源治理或故障恢复。展开每层查看具体产物和常见陷阱。

        


        

          

            L7
Host 集成与用户体验model loop · consent · result rendering
模型看见什么，用户确认什么

            
交付物
Server 配置、工具呈现、权限确认、错误与进度 UI。
易错点
把所有工具一次性塞进上下文；对高风险动作没有显式确认。

          

          

            L6
测试、可观测性与兼容性inspector · contract test · tracing
不仅“能连上”，还要可回归

            
交付物
Inspector 用例、Schema 合约测试、超时/取消测试、审计与指标。
易错点
只在一个 Host 中手工试；升级 SDK 后不做版本兼容验证。

          

          

            L5
安全与治理authn · authz · sandbox · audit
谁能读什么、做什么、做到哪里

            
交付物
最小权限、OAuth/令牌校验、文件根目录、命令白名单、配额与审计。
易错点
透传令牌；把句柄当身份；让工具参数直接进入 shell。

          

          

            L4
Transport 与部署stdio · streamable HTTP · packaging
本地子进程，还是远程多用户服务

            
交付物
启动命令、环境变量、容器/服务、TLS、反向代理、健康检查。
易错点
stdio 模式向 stdout 打日志；远程服务无认证或无租户隔离。

          

          

            L3
协议与 SDKJSON-RPC · discovery · notifications
方法、版本、能力和错误语义

            
交付物
Server/Client 实例、能力注册、分页、进度、取消与通知。
易错点
混用不同规范版本的消息格式；自行重造协议而遗漏边界行为。

          

          

            L2
能力契约tool schema · URI · error contract
让模型和程序都能理解的接口

            
交付物
工具名与描述、输入/输出 Schema、资源 URI、提示模板、错误分类。
易错点
工具粒度过大；描述只写实现不写使用条件；返回只有自然语言。

          

          

            L1
领域适配与后端系统API · database · filesystem · solver
把真实业务安全地包装起来

            
交付物
领域服务、输入校验、事务/幂等、缓存、后端适配器与故障映射。
易错点
MCP handler 直接堆业务逻辑；缺少超时、重试边界和可恢复错误。

          

        

      

    


    

      

        

          
05 · Transport choice
本地与远程，是两种安全模型

          
两种传输承载相同的数据层消息，但启动方式、身份认证、并发、隔离和运维责任完全不同。

        

        

          

            LOCAL / PROCESS
stdio
Host 启动 Server 子进程，通过标准输入输出交换消息。适合个人工具、本机文件和开发调试。

            

              
连接通常一个 Server 服务一个 Client

              
认证依赖本机进程、配置与操作系统边界

              
注意stdout 只能放协议消息；日志写 stderr

              
适合CLI、IDE 扩展、本机 OpenFOAM 适配器

            

          

          

            REMOTE / SERVICE
Streamable HTTP
Client 通过 HTTP POST 发消息，可选 SSE 流式返回。适合远程服务、多用户和企业集成。

            

              
连接一个服务通常承载多个 Client

              
认证推荐 OAuth；也可结合 Bearer、API Key 与自定义头

              
注意TLS、租户隔离、SSRF、限流和审计

              
适合SaaS、共享数据库、集群作业网关

            

          

        

      

    


    

      

        

          
06 · Build roadmap
一条可交付的开发路线

          
先证明“能力边界正确”，再追求“协议功能完整”。最小 Server 应该有一个真实场景、可验证契约和安全失败路径。

        

        

          
定义任务边界
明确用户、后端系统、读写范围、风险和成功标准。
任务清单

          
设计能力面
把需求分到 Tools、Resources、Prompts 与 Elicitation。
接口草图

          
建立领域层
先写可独立测试的业务服务，再套 MCP handler。
领域 API

          
接入 SDK
注册 Schema、传输、错误、分页、进度与通知。
可运行 Server

          
测试与接 Host
用 Inspector 和契约测试，再连接目标 AI 应用。
回归用例

          
生产化
认证、限流、审计、监控、版本、发布与回滚。
运行手册

        

      

    


    

      

        

          
07 · Domain example
映射到 OpenFOAM / CFD

          
对你的场景，最实用的做法是让 MCP 成为“受控的工程接口层”，而不是让模型直接拼 shell 命令。求解器和 C++ 库保持原样，外围用成熟 SDK 适配。

        


        

          

            
CFD Project Server
把案例读取、检查、提交、监控和后处理分成窄而可审计的能力；让 AI 负责选择与解释，让领域层负责规则与执行。

            推荐：Python façade + C++ solver
          

          

            

              

                
RESOURCES
case://demo/summarycase://demo/logcase://demo/residualscase://demo/boundary

                
TOOLS
validate_casecheck_meshsubmit_jobjob_statussample_results

                
PROMPTS
diagnose_divergenceprepare_case_reportcompare_schemes

                
ELICIT
confirm_core_hoursselect_time_rangeapprove_overwrite

              

              
为什么不优先直接写 C++ MCP？
当前官方 SDK 列表没有 C++。用 Python/TypeScript 做协议与 Schema 层，通过稳定 CLI、REST、文件或 IPC 调用现有 C++/OpenFOAM 组件，更容易跟进规范与测试。

            

            

              

                
只允许访问配置好的案例根目录，拒绝路径穿越和任意绝对路径

                
命令采用枚举/白名单，不把模型输出直接拼接到 shell

                
作业提交返回 job handle；每次查询重新验证用户与案例归属

                
为核数、队列、walltime、磁盘和并发建立配额

                
删除、覆盖、提交高成本作业前，通过 Elicitation 要求确认

                
工具返回结构化状态码、关键指标和日志资源 URI，不只返回长文本

                
OpenFOAM 进程输出进入日志文件；stdio 协议通道不写普通 stdout

              

            

          

        

      

    


    

      

        

          
08 · SDK & skeleton
选语言，然后保持业务层独立

          
Tier 越高，通常意味着协议覆盖和维护承诺越强。以下代码只表达架构骨架：Handler 做校验和映射，真正的 CFD 逻辑放在独立 service 中。

        

        

          

            
官方 SDK 层级

            

              
TypeScript · Python · C# · Go · RustTier 1

              
Java · RubyTier 2

              
Swift · PHP · KotlinTier 3

            

            
SDK 层级会随协议支持与维护状态变化；实际选型前应再次检查官方 SDK 页面。

          

          

            

              
              
              
            

            

          

        

      

    


    

      

        

          
09 · Security
把“模型会调用”当作不可信输入

          
MCP 扩大了 AI 应用的行动能力，也扩大了攻击面。Server 端、Client 端和底层资源都必须独立验证，不能把模型判断当成安全边界。

        

        

          
RISK 01
Token passthrough
接受并向下游转发并非为本 Server 签发的 token，会破坏 audience 边界和审计链。
→ 验证 issuer / audience / scope；禁止令牌透传

          
RISK 02
SSRF 与恶意 URL
OAuth discovery、重定向或 Server 提供的 URL 可能访问内网、元数据端点或危险 scheme。
→ HTTPS、私网阻断、逐跳校验、受控 egress

          
RISK 03
本地 Server 失控
stdio Server 本质上是以用户权限执行的本机程序，恶意启动命令可导致执行、泄漏或删除。
→ 来源验证、沙箱、最小文件/网络权限

          
RISK 04
State handle hijacking
工作流 ID、作业 ID 或购物车 ID 不是身份凭证；可猜句柄会造成跨用户访问。
→ 随机句柄、过期、服务端绑定已验证用户

          
RISK 05
工具参数注入
路径、SQL、shell 参数和模板都可能承载注入；Schema 合法不等于业务安全。
→ 参数化、allowlist、规范化与二次授权

          
RISK 06
高成本 / 高影响动作
模型可能误选核数、覆盖目录、批量发信或执行不可逆操作。
→ 配额、dry-run、幂等键、确认与审计

        

      

    


    

      

        

          
10 · Release gate
上线前，逐项过一遍

          
点击勾选，得到一个本地完成度。这里不保存也不上传任何数据。

        

        

          

            
0%

            
先完成接口与权限边界设计

          

          

            
            
            
            
            
            
            
            
            
            
          

        

      

    


    

      

        
Official references
规范与工具入口

        

          Architecture overview↗
          Specification 2026-07-28↗
          Official SDKs↗
          Build an MCP server↗
          MCP Inspector↗
          Security best practices↗