MCP Server.json 完全指南：Server Card 标准化安装清单深度解析

🎯 背景：为什么需要标准化？

2026年6月22日，MCP 社区提出了一个重要议题（#2963）：server.json、Server Card 和客户端安装行为之间的边界不清晰。

这个问题之所以重要，是因为：

• MCP 生态已有 19,831+ 服务器，需要统一的安装标准
• 不同客户端（OpenClaw、Claude Desktop、Cursor）的安装行为不一致
• 安全要求（SEP-1024）需要明确的元数据支持

🔍 Server.json vs Server Card vs Registry

这三个概念经常被混淆，但它们有不同的职责：

📦 Server.json 结构详解

当前 server.json 已经支持以下字段：

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "description": "一个示例 MCP 服务器",
  "transport": {
    "type": "stdio",
    "command": "node",
    "args": ["dist/index.js"]
  },
  "env": {
    "API_KEY": {
      "description": "API 密钥",
      "required": true,
      "secret": true
    }
  },
  "packages": [
    {
      "registry": "npm",
      "name": "my-mcp-server",
      "version": "1.0.0"
    }
  ]
}

关键字段说明

• transport: 定义传输方式（stdio/SSE）
• env: 环境变量配置，支持 secret 标记敏感信息
• packages: 包管理器信息，支持 npm/pip/cargo 等

⚖️ 规范性字段 vs 发现性元数据

这是 #2963 提出的核心问题：哪些字段应该被客户端视为"必须遵守"，哪些只是"参考信息"？

建议的分类方案

🛠️ 实际实现建议

1. 安装行为标准化

// 推荐的客户端安装流程
async function installServer(serverJson) {
    // 1. 验证规范性字段
    validateNormativeFields(serverJson);
    
    // 2. 检查用户同意 (SEP-1024)
    await requestUserConsent(serverJson);
    
    // 3. 安装包
    await installPackage(serverJson.packages[0]);
    
    // 4. 配置环境变量
    await configureEnv(serverJson.env);
}

2. 安全考虑

根据 SEP-1024，客户端应该：

• 显示完整的命令和参数
• 要求用户确认敏感权限
• 验证包的完整性（哈希/签名）

🔄 迁移指南

如果你正在开发 MCP 服务器，建议：

1. 立即行动：确保你的 server.json 包含所有规范性字段
2. 添加元数据：补充描述、许可证、仓库链接
3. 测试兼容性：在多个客户端测试安装流程
4. 关注 SEP：跟踪相关 SEP 的进展

❓ 常见问题

Q: server.json 和 Server Card 会合并吗？

目前没有明确计划，但 Registry WG 正在讨论对齐方案。建议保持两者独立，通过引用关联。

Q: 如何处理私有服务器？

使用 env 中的 secret: true 标记敏感变量，客户端应提供安全的输入方式。

Q: 状态化 vs 无状态服务器？

注意：2026-07-28 是 MCP 无状态化截止日期。参见我们的 MCP 协议完全指南。

📚 相关资源

• GitHub Issue #2963: Server.json 标准化讨论
• MCP Registry 概述
• SEP-1024: 本地服务器安全要求
• MCP 协议完全指南
• ClawHub Skills 使用教程

由 妙趣AI 运营团队撰写
最后更新: 2026-06-22