OpenMCPSpec文档（版本0.4.1-生产标准）
📖 概述
OpenMCPSpec是模型上下文协议（MCP）服务器和代理的模式标准。\ 它定义了如何描述意图、参数、响应、元数据、枚举和服务器连接细节，使大型语言模型（LLM）代理能够以一致和安全的方式自动发现MCP服务器并与之交互。\ 本规范旨在支持 系统可靠性 （通过标准化信封和追踪）以及 法学硕士治理 （通过明确的数据敏感性标志）生产实施所需的。 OpenMCPSpec在Jalandhar举行的ICSCCC2026会议的同行评审中通过了验收。更多消息即将发布。
🧩 架构部分
1.openmcpspec
- 类型： 字符串
- 目的： OpenMCPSpec模式的版本（例如“v0.4.1”）。
- 用途： 确保代理和服务器之间的兼容性。
2.信息
- 类型： 对象
- 目的： 关于MCP服务器的元数据。
- 领域：
- title（字符串，必填）：服务器的可读名称。 - version（字符串，必填）：服务器版本。 - description（string）：服务器用途的简短描述。
3.服务器
- 类型： 对象
- 目的： 自动发现的连接和安全详细信息。
- 领域：
- name（字符串，必填）：服务器的标识符。 - 主机名（字符串，必填）：主机名（例如docs.mcp.org）。 - port（整数，必填）：端口号（例如443）。 - 协议（字符串，必填）：传输协议（http、https、ws、wss）。 - base_path（字符串）：API端点的基本路径（例如/API/v1）。 - endpoints（字符串/URI数组）：服务器的入口点列表。 - 新身份验证（对象）： 定义支持的身份验证方法（V0.3/V0.4.1功能）。 - methods（字符串数组）：允许的方法（mtls、oidc、jwt、hmac）。 - Jwks URI（字符串/类型）：JSON web密钥集端点的类型。 - token_scopes（字符串数组）：访问所需的OAuth/JWT作用域。
4.信封（新增部分）
- 类型： 对象
- 目的： 所有请求/响应有效载荷的标准化包装器，以确保分布式生产环境中的可靠性、跟踪和流式传输（V0.3/V0.4.1功能）。
- 领域：
- 请求（对象）： 代理在调用MCP服务器时使用的字段。 - id（字符串）：用于审核的唯一请求id。 - deadline_ms（整数）：请求超时。 - 幂等密钥（string）：确保安全重试的密钥。 - trace_id（字符串）：分布式跟踪标识符。 - 响应（对象）： MCP服务器返回的字段。 - status（字符串）：结果状态（成功、错误、部分）。 - error（ref）：参考errorEvelope定义进行标准化错误处理。 - stream_chunk（对象）： 定义实时数据流的结构（例如，LLM令牌流或数据库行批处理）。 - chunk_type（字符串）：有效载荷的类型（令牌、row_batch、日志）。 - sequence（整数）：流中块的排序。
5.意图
- 类型： 数组
- 目的： 服务器提供的功能（操作）列表。
5.1.意图/参数
本节定义了意图的输入要求。
- 类型： 对象数组 （V0.2结构已恢复）
- 目的： 明确界定合同和 治理标志 对于每一个论点。
- LLM治理和ACI的关键领域（论点正确性改进）：
- 名称、类型、描述、必填项、默认值。 - pii（布尔值）： （V0.2恢复） 关键标志，指示参数是否包含个人身份信息。用于LLM代理人的合规优先购买率（CPR）计算和拒绝。 - gdpr_sensitive（布尔值）： （V0.2恢复） 表示数据受GDPR/CCPA法规约束的关键标志。也用于心肺复苏术。 - 验证字段： 枚举、模式、最小值、最大值、格式。这些功能允许代理在呼叫之前进行ACI检查。
5.2.意图/反应
- 类型： 对象
- 目的： 定义成功和失败执行的预期输出结构。
- success/schema（对象）：成功数据有效载荷的JSON模式。 - error（ref）：引用标准化的errorEvelope定义。
6.定义/错误信封（新/更新的定义）
- 类型： 对象
- 目的： 用于处理所有意图中的系统和域错误的标准化分类。
- 领域：
- code（string，enum）：类别错误代码（例如，MCP-ERR-AUTH-FAILED、SQL-ERR-SYNTAX）。 （V0.3功能） - message（string）：人类可读的错误消息。 - 可重试（布尔值）：自动客户端重试逻辑的标志。 - correlation_id（string）：将错误链接到内部日志的id。 - 详细信息（对象）： 特定意图的错误数据有效载荷。 - payload_schema（对象）： （V0.4.1固定） 一个可选的JSON模式，定义了 详情 对象用于此特定错误类型，允许在标准化信封内提供特定意图的丰富错误数据。 - recovery_hints（字符串数组）：建议客户端执行的操作。
7.列举
- 类型： 对象
- 目的： 定义代理根据标准高效发现可用意图的机制。
- 领域： 过滤器、分页、版本控制、capability标签、intentgroups。
8.生命周期
- 类型： 对象
- 目的： 定义有关规范管理的元数据。
- 领域： 更新日志，兼容性。
9.测试
- 类型： 对象
- 目的： 定义钩子和元数据，用于测试合规性和正确性。
- 领域： mock_data、验证用例、bdd_case、一致性测试。
10.分析
- 类型： 对象
- 目的： 定义用于监视和可观察性的钩子。
- 领域： 日志记录、指标、监控簿、跟踪id支持、使用配额、延迟sla_ms。
⚙️ 更新日志
- 版本0.4.1（生产整合）
- 巩固： 将V0.3草案中的系统可靠性特征与V0.2中的LLM治理特征合并。 - 错误修复： 通过在全局errorEvelope中引入payload_schema字段来定义特定意图的错误数据模式，恢复了V0.2的丰富错误结构。 - 治理已恢复： 显式恢复意图/参数的数组结构，包括关键pii和gdpr_sensitive布尔标志，确保代理具有完全的合规性优先权（CPR）功能。 - API可靠性： 包含了标准请求/响应/流协议的顶级信封，包括幂等项key和trace_id。 - 安全标准化： 添加了server/auth对象来定义显式安全契约（mtls、oidc、jwt）。
- 0.2版（标准化草案）
- 建立了基本模式结构（openmcpspec、info、server、intent、枚举）。 - 在参数中引入了强制性LLM治理标志（pii、gdpr_sensitive）和ACI字段（模式、最小值、最大值）。
- 版本0.1（初稿）
- 建立了基本模式结构（openmcpspec、info、server、intent、枚举）。 - 添加了对参数、响应和元数据的支持。 - 引入了可选部分（生命周期、测试、分析）。
---
👥 贡献者
- Chaitanya Pinnamaraju --项目发起人、方案设计方向和规范作者。
- 微软副驾驶 --人工智能合作者、文档起草和模式细化。
🛣️ 路线图（更新）
计划版本0.5
- 支持具有向后兼容性准则的模式演化。
- 为特定于供应商的字段添加插件/模块扩展模式（x_dextensions）。
- 定义跨多个MCP服务器版本的生命周期管理的最佳实践。
- 为自动化规范验证和测试提供工具。
长期目标
- 将OpenMCPSpec确立为社区驱动的标准。
- 与流行的代理框架集成，实现无缝自动发现。
- 提供多种语言的参考实现和SDK。
- 鼓励在企业和开源MCP部署中采用。