# 1MCP 系统架构
> **愿景**：一个统一、可靠的代理，使多个 MCP 服务器看起来像一个，简化 AI 助手集成，同时保持安全性和性能。
## 🎯 目的与背景
**问题**：AI 助手需要连接到多个 MCP 服务器，但管理数十个单独的连接是复杂、不可靠且安全密集的。
**解决方案**：1MCP 充当统一的代理/多路复用器，将多个 MCP 服务器聚合在单个可靠的接口后面。
**成功指标**：
- **可靠性**：通过适当的错误处理实现稳定运行
- **性能**：高效地将请求转发到后端服务器
- **安全性**：OAuth 2.1 认证和安全默认设置
- **简单性**：单个配置文件，易于部署
```mermaid
graph TB
subgraph "AI 客户端"
C1[Claude Desktop]
C2[Cursor]
C3[Cherry Studio]
end
subgraph "1MCP 代理"
P[统一接口<br/>HTTP/SSE + OAuth]
end
subgraph "MCP 服务器"
S1[文件系统]
S2[网页搜索]
S3[数据库]
S4[内存]
end
C1 --> P
C2 --> P
C3 --> P
P --> S1
P --> S2
P --> S3
P --> S4
```
## 📏 系统约束
### **硬性约束**
- **单个二进制文件**：必须作为单个可执行文件部署，无外部依赖
- **MCP 协议**：必须 100% 兼容 MCP [最新规范](https://modelcontextprotocol.io/specification/latest)
- **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 安全层
- **连接多路复用器**：多对多客户端到服务器
- **进程管理器**：后端服务器的生命周期管理
### **我们不是什么**
- **业务逻辑引擎**：无数据转换或业务规则
- **缓存层**：每个请求都到后端 (目前)
- **服务网格**：不是通用的服务通信层
- **数据库**：不持久化存储应用程序数据
### **集成边界**
```mermaid
graph TB
subgraph "北向 (客户端)"
NB[HTTP/SSE + OAuth<br/>仅 MCP 协议]
end
subgraph "1MCP 核心"
C[代理逻辑]
end
subgraph "南向 (后端)"
SB[后端 MCP 服务器<br/>stdio/HTTP 传输]
end
subgraph "东西向 (对等)"
EW[无服务间<br/>通信]
end
NB --> C
C --> SB
C -.- EW
```
### **我们避免的反模式**
- **共享数据库**：实例之间无共享状态
- **网络依赖**：运行时不调用外部服务
- **协议扩展**：无 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，缺少服务器，权限错误
- **检测**：文件解析错误，验证失败
- **恢复**：保留以前的有效配置，记录错误
- **升级**：禁用热重载，需要手动干预
#### **资源耗尽**
- **症状**：高内存使用，达到连接限制，响应缓慢
- **检测**：资源监控，性能下降
- **恢复**：连接节流，优雅降级，负载削减
- **升级**：服务重启，水平扩展
#### **安全漏洞**
- **症状**：认证绕过，未经授权的访问，令牌泄露
- **检测**：安全监控，异常检测，审计日志
- **恢复**：立即隔离服务，撤销令牌，取证分析
- **升级**：完全关闭服务，事件响应程序
### **恢复期望**
- **后端重新连接**：自动重试逻辑
- **配置重载**：立即检测和应用
- **安全事件**：立即认证失败响应
- **系统恢复**：根据需要重启和重载
---
> **此架构作为我们的决策框架。如有疑问，请参考我们的原则和约束。所有更改都应加强这些基础，而不是削弱它们。**
