1MCP 系统架构
愿景：一个统一、可靠的代理，使多个 MCP 服务器看起来像一个，简化 AI 助手集成，同时保持安全性和性能。
🎯 目的与背景
问题：AI 助手需要连接到多个 MCP 服务器，但管理数十个单独的连接是复杂、不可靠且安全密集的。
解决方案：1MCP 充当统一的代理/多路复用器，将多个 MCP 服务器聚合在单个可靠的接口后面。
成功指标：
- 可靠性：通过适当的错误处理实现稳定运行
- 性能：高效地将请求转发到后端服务器
- 安全性：OAuth 2.1 认证和安全默认设置
- 简单性：单个配置文件，易于部署
📏 系统约束
硬性约束
- 单个二进制文件：必须作为单个可执行文件部署，无外部依赖
- MCP 协议：必须 100% 兼容 MCP 最新规范
- Stdio 传输：后端服务器通过 stdio 或可流式传输的 http 通信 (安全边界)
- 配置：所有配置通过单个 JSON 文件，可热重载
软性约束
- 并发连接：处理多个同时的客户端连接
- 后端服务器：每个实例支持多个 MCP 服务器
- 网络：在企业防火墙后工作 (仅 HTTP/SSE)
- 启动时间：快速启动以进行开发迭代
- 依赖项：最少的外部依赖以确保安全
为何有这些约束
- 单个二进制文件：企业部署要求 - 无复杂设置
- 多传输：后端服务器支持 stdio、HTTP 和可流式传输的 HTTP 传输
- 热重载：需要零停机配置更新
🏗️ 架构原则
原则 1：可靠性优于性能
- 即使单个后端失败，系统也必须保持运行
- 优雅降级优于快速失败
- 具有重试逻辑和超时的连接管理
原则 2：默认安全
- 除非明确禁用，否则所有端点都需要认证
- 后端服务器在具有安全传输协议的隔离进程中运行
- 对所有外部数据进行输入清理
- 日志中无敏感数据
原则 3：简单性优于灵活性
- 单一部署模型，不可配置
- 尽可能约定优于配置
- 显式行为而非隐式行为
原则 4：对客户端透明
- MCP 协议合规性 - 客户端不知道它是一个代理
- 错误消息保留后端服务器上下文
- 无协议修改或扩展
🔄 决策框架
在评估新功能或更改时，请问：
可靠性问题
- 这会降低系统可用性吗？
- 如果此组件失败会怎样？
- 系统可以在没有它的情况下继续运行吗？
安全性问题
- 这会扩大攻击面吗？
- 这会泄露敏感信息吗？
- 我们是否在维护深度防御？
简单性问题
- 这会增加配置复杂性吗？
- 这会使部署更困难吗？
- 我们可以用现有的模式解决这个问题吗？
兼容性问题
- 这会破坏 MCP 协议合规性吗？
- 现有客户端会继续工作吗？
- 我们是否在保留后端服务器接口？
📊 质量属性场景
可靠性场景
- 情况：后端 MCP 服务器在请求处理期间崩溃
- 响应：系统检测到故障，将服务器标记为不可用，如果适用，在其他服务器上重试请求
- 衡量：<5 秒恢复，客户端收到适当的错误，系统保持可用
- 当前：带有健康检查的连接池，指数退避重试
安全性场景
- 情况：客户端尝试在没有适当授权的情况下访问 MCP 服务器
- 响应：OAuth 令牌验证，范围检查，请求被拒绝并返回 403
- 衡量：零未经授权的访问，所有尝试都与客户端上下文一起记录
- 当前：具有基于范围的授权的 OAuth 2.1，会话管理
性能场景
- 情况：多个并发客户端向后端服务器发出请求
- 响应：高效的请求转发，适当的错误处理，异步处理
- 衡量：可靠的请求处理，系统保持响应
- 当前：具有适当错误处理的 Express.js，异步请求转发
可维护性场景
- 情况：将新的 MCP 服务器添加到配置文件中
- 响应：热重载检测到更改，生成新的服务器进程，更新路由
- 衡量：<30 秒可用，零停机
- 当前：带有去抖动重载的文件系统监视，优雅的进程管理
🚫 系统边界与反模式
我们是什么
- MCP 协议代理：忠实实现 MCP 规范
- 认证网关：OAuth 2.1 安全层
- 连接多路复用器：多对多客户端到服务器
- 进程管理器：后端服务器的生命周期管理
我们不是什么
- 业务逻辑引擎：无数据转换或业务规则
- 缓存层：每个请求都到后端 (目前)
- 服务网格：不是通用的服务通信层
- 数据库：不持久化存储应用程序数据
集成边界
我们避免的反模式
- 共享数据库：实例之间无共享状态
- 网络依赖：运行时不调用外部服务
- 协议扩展：无 MCP 协议修改
- 同步链：请求路径中无阻塞调用
- 全局状态：所有状态都是请求范围或配置
🗺️ 演进策略
阶段 1：单实例代理 (当前)
- 范围：每次部署一个 1MCP 实例
- 功能：HTTP/SSE 传输，OAuth，基本连接池
- 约束：无水平扩展，仅本地配置
阶段 2：增强功能 (未来)
- 范围：基于用户反馈的其他操作功能
- 功能：增强的监控，高级配置选项
- 迁移：向后兼容，可选增强
阶段 3：高级功能 (未来)
- 范围：用于企业用例的高级功能
- 功能：增强的安全性，操作改进
- 迁移：配置扩展，无协议更改
演进原则
- 向后兼容性：现有部署继续工作
- 渐进增强：新功能是可选的
- 零停机：所有迁移都支持热升级
- 配置驱动：通过配置启用功能
⚡ 架构验证
自动化架构测试
typescript
// 示例：架构测试强制执行我们的边界
describe('架构约束', () => {
test('传输层中无业务逻辑', () => {
// 静态分析确保传输仅处理 HTTP/认证
});
test('所有外部调用都使用断路器', () => {
// 验证是否使用了弹性模式
});
test('存储库之外无直接数据库访问', () => {
// 强制执行数据访问模式
});
});架构指标
- 依赖违规：0 (由测试强制执行)
- 圈复杂度：<10 每个函数 (linting)
- 安全扫描：0 高/严重漏洞
- API 兼容性：100% MCP 协议合规性
- 测试覆盖率：>90% 关键路径
持续验证
- 架构测试在 CI/CD 管道中运行
- 拉取请求中的依赖分析
- 每次构建都进行安全扫描
- 性能回归测试
🔍 可观察性与监控
健康指标
- 系统健康：所有核心组件正常运行
- 后端健康：单个 MCP 服务器状态
- 连接健康：客户端连接池状态
- 配置健康：配置文件有效性和重载状态
关键指标
- 可用性：系统正常运行时间百分比
- 延迟：请求响应时间分布
- 吞吐量：每秒请求容量
- 错误率：失败请求百分比
- 资源使用：内存、CPU、连接数
监控指标
- 严重：系统不可用，认证失败，配置错误
- 警告：后端服务器断开连接，重复请求失败
- 信息：配置已重载，新的客户端连接，成功操作
🚨 故障模式与恢复
故障类别
后端服务器故障
- 症状：进程崩溃，无响应，无效响应
- 检测：健康检查，请求超时，错误模式
- 恢复：进程重启，连接重试，优雅降级
- 升级：从轮换中移除，提醒操作员
配置故障
- 症状：无效的 JSON，缺少服务器，权限错误
- 检测：文件解析错误，验证失败
- 恢复：保留以前的有效配置，记录错误
- 升级：禁用热重载，需要手动干预
资源耗尽
- 症状：高内存使用，达到连接限制，响应缓慢
- 检测：资源监控，性能下降
- 恢复：连接节流，优雅降级，负载削减
- 升级：服务重启，水平扩展
安全漏洞
- 症状：认证绕过，未经授权的访问，令牌泄露
- 检测：安全监控，异常检测，审计日志
- 恢复：立即隔离服务，撤销令牌，取证分析
- 升级：完全关闭服务，事件响应程序
恢复期望
- 后端重新连接：自动重试逻辑
- 配置重载：立即检测和应用
- 安全事件：立即认证失败响应
- 系统恢复：根据需要重启和重载
此架构作为我们的决策框架。如有疑问，请参考我们的原则和约束。所有更改都应加强这些基础，而不是削弱它们。