1MCP Server

# 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，缺少服务器，权限错误 - **检测**：文件解析错误，验证失败 - **恢复**：保留以前的有效配置，记录错误 - **升级**：禁用热重载，需要手动干预 #### **资源耗尽** - **症状**：高内存使用，达到连接限制，响应缓慢 - **检测**：资源监控，性能下降 - **恢复**：连接节流，优雅降级，负载削减 - **升级**：服务重启，水平扩展 #### **安全漏洞** - **症状**：认证绕过，未经授权的访问，令牌泄露 - **检测**：安全监控，异常检测，审计日志 - **恢复**：立即隔离服务，撤销令牌，取证分析 - **升级**：完全关闭服务，事件响应程序 ### **恢复期望** - **后端重新连接**：自动重试逻辑 - **配置重载**：立即检测和应用 - **安全事件**：立即认证失败响应 - **系统恢复**：根据需要重启和重载 ## 🏗️ 代码结构与组织 ### **项目布局** 代码库遵循分层架构，具有清晰的关注点分离： ``` src/ ├── application/ # 应用级服务 │ └── services/ # 横切编排服务 │ ├── configReloadService.ts │ ├── healthService.ts │ └── tokenEstimationService.ts ├── auth/ # 认证与授权 │ ├── storage/ # 认证数据仓库模式 │ ├── sdkOAuthClientProvider.ts │ ├── sdkOAuthServerProvider.ts │ └── sessionTypes.ts ├── commands/ # CLI 命令实现 │ ├── app/ # 应用管理命令 │ ├── mcp/ # MCP 服务器管理命令 │ ├── preset/ # 预设管理命令 │ ├── proxy/ # 代理命令 │ ├── serve/ # 服务器命令 │ └── shared/ # 共享命令工具 ├── config/ # 配置管理 │ ├── configContext.ts │ ├── mcpConfigManager.ts │ ├── envProcessor.ts │ ├── projectConfigLoader.ts │ └── projectConfigTypes.ts ├── constants/ # 按域组织的常量 │ ├── api.ts # API 端点、端口、主机 │ ├── auth.ts # 认证常量 │ ├── mcp.ts # MCP 协议常量 │ ├── paths.ts # 文件路径、目录 │ └── index.ts # 桶导出 ├── core/ # 核心业务逻辑 │ ├── capabilities/ # MCP 能力管理 │ ├── client/ # 客户端管理 │ ├── filtering/ # 请求过滤逻辑 │ ├── instructions/ # 模板引擎 │ ├── loading/ # 异步加载编排 │ ├── notifications/ # 通知系统 │ ├── protocol/ # 协议消息处理器 │ ├── server/ # 服务器生命周期管理 │ └── types/ # 共享类型定义 ├── domains/ # 域模块 │ ├── backup/ # 备份管理域 │ ├── discovery/ # 应用发现域 │ └── preset/ # 预设管理域 │ ├── manager/ # PresetManager │ ├── parsers/ # 标签查询解析 │ ├── services/ # 预设服务 │ └── types/ # 预设类型 ├── logger/ # 日志基础设施 │ ├── configureGlobalLogger.ts │ └── [6 个其他日志文件] ├── transport/ # 传输层实现 │ ├── http/ # HTTP/SSE 传输 │ │ ├── middlewares/ # Express 中间件 │ │ └── routes/ # API 路由处理器 │ └── [5 个传输文件] └── utils/ # 通用工具 ├── core/ # 核心工具 ├── ui/ # CLI 工具 └── validation/ # 输入验证 ``` ### **架构层** #### **1. 应用层 (`application/`)** - **目的**：横切编排服务 - **职责**：配置重载、健康监控、令牌估算 - **依赖**：可以依赖核心和域 - **示例**：`configReloadService`、`healthService` #### **2. 核心层 (`core/`)** - **目的**：核心业务逻辑和域实体 - **职责**：MCP 协议处理、能力管理、服务器生命周期 - **依赖**：不应依赖应用层 - **示例**：`ServerManager`、`ClientManager`、`CapabilityManager` #### **3. 域层 (`domains/`)** - **目的**：自包含的业务域 - **职责**：特定业务逻辑（预设、发现、备份） - **依赖**：可以依赖核心，应该独立 - **示例**：`PresetManager`、`BackupManager`、`AppDiscovery` #### **4. 传输层 (`transport/`)** - **目的**：协议实现和通信 - **职责**：HTTP/SSE、STDIO、消息路由 - **依赖**：可以依赖核心和应用 - **示例**：`ExpressServer`、`StdioTransport` #### **5. 基础设施层 (`auth/`、`config/`、`logger/`)** - **目的**：横切基础设施关注点 - **职责**：认证、配置、日志 - **依赖**：最小依赖，被所有层使用 - **示例**：`McpConfigManager`、`OAuthClientProvider` ### **设计原则** #### **领域驱动设计** - **域**：具有清晰边界的自包含模块 - **服务**：应用级编排 - **核心**：共享业务逻辑和实体 #### **依赖方向** ``` 应用 → 核心 → 域 ↓ ↓ 传输 → 基础设施 ``` #### **文件组织** - **共置**：相关文件分组在一起 - **桶导出**：使用 `index.ts` 的清晰导入路径 - **域边界**：清晰的所有权和职责 #### **命名约定** - **管理器**：`*Manager.ts` 用于有状态服务 - **服务**：`*Service.ts` 用于无状态操作 - **类型**：`*Types.ts` 用于类型定义 - **工具**：仅通用工具 ### **迁移收益** 重构后的代码库提供： - **57% 减少** 工具文件（47 → 20） - **清晰的域边界** 与专用模块 - **更好的可维护性** 通过有组织的结构 - **改进的可扩展性** 与独立域 - **增强的开发者体验** 与清晰的文件位置 ## 工作原理 1MCP 作为代理，管理和聚合多个 MCP 服务器。它启动和停止这些服务器作为子进程，并将来自 AI 助手的请求转发到适当的服务器。这种架构允许所有 MCP 流量的单一入口点，简化管理并减少开销。 ### 系统架构 ```mermaid graph TB subgraph "AI 助手" A1[Claude Desktop] A2[Cursor] A3[Cherry Studio] A4[Roo Code] end subgraph "1MCP 代理" P[1MCP 代理<br/>STDIO 桥接] end subgraph "1MCP 服务器" MCP[1MCP Agent<br/>HTTP/SSE] end subgraph "MCP 服务器" S1[服务器 1] S2[服务器 2] S3[服务器 3] end A1 -->|stdio| P A2 -->|http| MCP A3 -->|http| MCP A4 -->|http| MCP P -->|http| MCP MCP --> |http| S1 MCP --> |stdio| S2 MCP --> |stdio| S3 ``` ### 请求流程 ```mermaid sequenceDiagram participant Client as AI 助手 participant Proxy as 1MCP 代理 participant Server as 1MCP 服务器 participant MCP as MCP 服务器 Note over Client, MCP: HTTP/SSE 客户端 (Cursor, Cherry Studio 等) Client->>Server: 发送 MCP 请求 activate Server Server->>Server: 验证请求 Server->>Server: 加载配置 Server->>MCP: 转发请求 activate MCP MCP-->>Server: 响应 deactivate MCP Server-->>Client: 转发响应 deactivate Server Note over Client, MCP: STDIO 客户端 (Claude Desktop) 通过代理 Client->>Proxy: 发送 MCP 请求 (STDIO) activate Proxy Proxy->>Server: 转发请求 (HTTP) activate Server Server->>Server: 验证请求 Server->>Server: 加载配置 Server->>MCP: 转发请求 activate MCP MCP-->>Server: 响应 deactivate MCP Server-->>Proxy: 转发响应 (HTTP) deactivate Server Proxy-->>Client: 转发响应 (STDIO) deactivate Proxy ``` --- > **此架构作为我们的决策框架。如有疑问，请参考我们的原则和约束。所有更改都应加强这些基础，而不是削弱它们。**