ToolHive MCP注册表架构研究
概述
该存储库包含全面的研究和体系结构文档，用于在气隙Kubernetes环境中集成集群范围的MCP Catalog API和命名空间范围的MCP注册表。该研究侧重于MCP服务器管理的企业部署模式、安全模型和操作框架。
🎯 项目重点
首要目标：设计并记录MCP服务器目录集成的稳健架构，该架构支持：
- 气隙企业部署
- 命名空间范围的安全隔离
- 用户驱动的资源创建工作流
- 多层安全控制
- 可扩展的注册表管理
📚 文档结构
核心架构文档
主要交付成果是位于 docs/architecture/:
🏗️ 集成体系结构
🔧 技术参考
- MCPRegistry API参考 -完整的CRD规范和操作指南
- MCP服务器部署指南 -全面的服务器部署和配置
- 操作员架构说明 -关键操作员行为和模式
🔒 安全框架
- 安全和访问控制模型 -具有RBAC、网络策略和合规框架的多层安全架构
支持材料
📋 操作资源
- Kubernetes部署 -MCPServer工作示例和集群配置
- Helm安装说明 -ToolHive操作员部署指南
- 注册表示例 -用于测试的注册表数据和模式示例
🛠️ 开发工具
🏗️ 关键架构模式
气隙设计原则
- 基于ConfigMap的注册表 -存储在Kubernetes ConfigMaps中的所有注册表数据（无Git依赖关系）
- 私人图像支持 -具有摘要验证的自定义容器注册表
- 离线操作 -无需外部网络访问即可完成功能
- 用户驱动工作流 -目录提供元数据；用户手动创建Kubernetes资源
安全架构层
┌─────────────────────────────────────────────────────┐
│ Catalog API │
│ (Cluster-wide) │
│ ┌─────────────────────────────────────────────┐ │
│ │ Authentication & RBAC │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────┬───────────────────────────────────┘
│
▼ User queries metadata
┌─────────────────────────────────────────────────────┐
│ Namespace Level │
│ (User Creates Resources) │
│ ┌─────────────────────────────────────────────┐ │
│ │ MCPRegistry Access Control │ │
│ │ (enforce servers, filtering) │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Network Policies │ │
│ │ (API service isolation) │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────┬───────────────────────────────────┘
│
▼ Operator deploys automatically
┌─────────────────────────────────────────────────────┐
│ Server Level │
│ (MCP Server Runtime) │
│ ┌─────────────────────────────────────────────┐ │
│ │ Permission Profiles │ │
│ │ (network, filesystem, capabilities) │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Tool Filtering │ │
│ │ (MCPToolConfig restrictions) │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘集成数据流
User Discovery → Catalog API → Metadata Export → User Creates Resources → Operator Deploys
├── ConfigMap (registry data)
├── MCPRegistry (deployment spec)
└── MCPToolConfig (tool filtering)
↓
Automatic API Service Deployment
(per-registry endpoints)🎯 研究成果
分布式注册表模式
ToolHive运算符实现了 分布式注册表体系结构:
- 没有集中式注册表API -每个MCPRegistry CRD都部署自己的API服务
- 命名空间隔离 -注册表API的作用域为特定命名空间
- 自动服务部署 -运营商处理API服务生命周期
- 每个注册表端点 -每个注册表都有自己的HTTP API
目录集成模型
通过本研究确定的最佳整合方法：
- 目录作为元数据存储库 -服务器定义和配置的中心来源
- 用户驱动的资源创建 -用户使用目录元数据手动创建Kubernetes资源
- 操作员自动化 -ToolHive操作员处理部署和API服务创建
- 安全边界 -多层访问控制和隔离
安全控制点
记录了三种主要的安全模型：
- 基于命名空间的隔离 -具有不同信任级别的不同安全区域
- 基于角色的访问控制 -基于用户角色的细粒度权限
- 服务网格集成 -具有双向TLS和授权策略的高级安全性
🚀 入门指南
亲身体验（推荐第一步）
\*\*希望部署和体验MCP注册表的工程师：\*\*
🎯 完整部署指南 -逐步执行以下任务：
- 使用ToolHive操作符设置Kubernetes集群
- 部署和测试MCP服务器
- 创建和配置自定义注册表
- 体验完整的注册表工作流程
本指南为每个阶段提供了复制粘贴命令和验证步骤。
用于架构审查
用于实施规划
- 注册表API参考: MCPRegistry API参考
- 服务器部署: MCP服务器部署指南
- 操作员行为: 操作员架构说明
快速验证命令
# Automated cluster setup
./scripts/setup/setup-cluster.sh
# Install ToolHive operator
helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace
# Test MCPServer deployment
kubectl apply -f deploy/kubernetes/osv-mcpserver.yaml
kubectl get mcpservers
# Validate registry schema
python3 -m json.tool registry/registry.json > /dev/null && echo "Valid JSON"📊 存储库组织
toolhive-research/
├── docs/architecture/ # 📚 Primary deliverable - complete architecture docs
├── deploy/ # 🚀 Working Kubernetes manifests and deployment guides
├── registry/ # 📋 Example registry data and schemas
├── scripts/ # 🛠️ Automation for testing and validation
├── examples/advanced/ # 🔧 Advanced configuration patterns
└── docs/troubleshooting/ # 🩺 Operational guidance and issue resolution📋 实施指南
最低目录要求
为了支持文档化的架构，目录系统需要：
| 组件 | 需求 要求 规格 | 目的 | |---------------|-----------------|-------------| | 服务器发现API |用于浏览已验证/社区服务器的REST端点|用户服务器选择| | 元数据导出API |完整的服务器规格，包括工具、安全配置文件|资源创建数据| | 类别式组织 |已验证与社区服务器分类|安全区域定位| | 工具信息 |包含描述的全面工具定义|MCPToolConfig创建| |
气隙元数据
|图像摘要、离线文档、依赖关系跟踪|企业部署|
- 用户工作流 文档化的工作流程消除了CLI依赖性：
- 查询目录 -用户通过目录API浏览可用服务器
- 导出元数据 -目录提供完整的资源创建数据
- 创建配置映射 -用户使用选定的服务器手动创建ConfigMgr
- 部署MCPRegistry -用户应用指向ConfigMgrap的MCPRegistry资源
- 配置工具 -用户应用MCPToolConfig进行工具筛选（可选）
自动部署 -ToolHive运算符处理API服务创建
- 📚 参考资料
- ToolHive文档 -官方ToolHive操作员文档
- 模型上下文协议 -MCP规范和标准
- Kubernetes文档 -CRD和操作员模式
气隙部署模式 -企业Kubernetes指南
🤝
- 贡献 该研究库遵循文档驱动开发：
- 建筑优先 -实施前记录的所有模式
- 注重安全 -所有设计决策都考虑了安全影响
- 企业就绪 -针对生产气隙环境验证的模式
实施无关 -独立于特定技术选择的架构
📄