MCP OpenAPI Server 开发指南：架构设计与核心实现解析

项目概述

MCP OpenAPI Server 是一个基于 OpenAPI 规范的 API 服务端实现框架，它提供了一套完整的工具链，用于将 OpenAPI 规范转换为可执行的 API 服务。本文将从架构设计、核心概念到具体实现细节，全面解析该项目的技术实现。

架构设计

核心组件架构

MCP OpenAPI Server 采用模块化设计，主要包含以下核心组件：

1. OpenAPIServer：服务入口，负责服务器初始化和请求路由
2. ToolsManager：工具管理核心，实现工具过滤和查找功能
3. OpenAPISpecLoader：OpenAPI 规范加载器，负责解析和工具创建
4. ApiClient：HTTP 客户端，处理实际 API 请求
5. AuthProvider：认证系统，支持动态认证管理
6. Tool ID Utils：工具 ID 生成与解析工具

各组件之间通过清晰的接口定义进行通信，形成松耦合的架构体系。

核心概念解析

ExtendedTool 接口

项目扩展了标准的 MCP Tool 接口，增加了用于高效过滤的元数据：

interface ExtendedTool extends Tool {
  tags?: string[]        // 关联的 OpenAPI 标签
  httpMethod?: string    // HTTP 方法类型
  resourceName?: string  // 从路径提取的主资源名
  originalPath?: string  // 转换前的原始路径
}

这些元数据在工具创建时计算，避免了重复解析带来的性能开销。

工具加载模式

系统支持三种不同的工具加载策略：

1. 全量模式（"all"）：默认模式，加载所有符合过滤条件的工具
2. 动态模式（"dynamic"）：仅加载用于 API 探索的元工具
3. 显式模式（"explicit"）：仅加载明确指定的工具，忽略其他过滤条件

工具 ID 系统详解

ID 格式规范

工具 ID 采用统一格式标识 API 端点：METHOD::pathPart

典型示例：

• GET::users → GET /users
• POST::api__v1__users → POST /api/v1/users

路径分隔方案

系统采用双下划线(__)作为路径分隔符，解决了传统方案中的连字符转义问题：

1. 路径转换规则：

   • 斜杠(/)替换为双下划线(__)
   • 路径中的合法连字符保留原样

2. 生成算法：

function generateToolId(path) {
  return path.replace(/\//g, "__")  // 转换斜杠
            .replace(/^\//, "")    // 去除开头斜杠
}

3. 解析算法：

function parseToolId(toolId) {
  const [method, pathPart] = toolId.split("::")
  return { 
    method, 
    path: "/" + pathPart.replace(/__/g, "/") 
  }
}

字符安全处理

为确保 ID 安全性，系统会对特殊字符进行处理：

1. 仅保留字母、数字、下划线和连字符
2. 连续多个下划线合并为双下划线
3. 去除首尾的特殊字符

工具名称缩写系统

缩写处理流程

名称缩写经过多阶段处理：

1. 基础清洗：替换非字母数字字符为连字符
2. 词汇拆分：按驼峰、下划线和数字拆分
3. 通用词移除：过滤"api"、"service"等通用词
4. 标准缩写：应用预定义的缩写规则
5. 元音移除：对长词汇进行简化
6. 哈希后缀：超长名称添加唯一哈希值

缩写示例

原始名称	处理结果
getUserDetails	get-user-details
ServiceUsersManagementController_update...	svc-usrs-mgmt-upd-svc-usrs-auth-grp-a1b2

资源名提取算法

系统从路径中提取主资源名用于过滤：

function extractResourceName(path) {
  const segments = path.split('/')
  // 逆向查找第一个非参数段
  for (let i = segments.length - 1; i >= 0; i--) {
    const seg = segments[i]
    if (!seg.includes("{") && seg.length > 0) {
      return seg
    }
  }
  return segments[0] || undefined
}

典型提取示例：

• /users/{id} → "users"
• /api/v1/user-profile → "user-profile"

过滤系统实现

过滤优先级

系统按照严格顺序应用过滤条件：

1. 包含工具列表（最高优先级）
2. HTTP 方法过滤
3. 资源名过滤
4. 标签过滤

过滤模式对比

模式类型	特点	适用场景
全量模式	应用所有过滤条件	常规API服务
显式模式	仅加载指定工具	特定端点调试
动态模式	仅加载元工具	API探索

认证系统设计

认证提供者接口

interface AuthProvider {
  getAuthHeaders(): Promise<Record<string, string>>
  handleAuthError(error: AxiosError): Promise<boolean>
}

认证流程

1. 请求前获取认证头信息
2. 遇到401/403错误时处理
3. 根据处理结果决定是否重试

开发实践指南

项目结构

src/
├── config.ts          # 配置管理
├── server.ts          # 服务主类
├── tools-manager.ts   # 工具管理
└── utils/            # 核心工具

测试建议

1. 工具ID系统：验证生成与解析的对称性
2. 缩写系统：覆盖各种命名模式
3. 过滤逻辑：测试条件组合
4. OpenAPI处理：验证规范解析

最佳实践

1. 工具ID设计：保持路径语义清晰
2. 名称缩写：平衡可读性与简洁性
3. 过滤策略：合理选择过滤模式
4. 认证实现：处理好令牌刷新逻辑

通过本文的详细解析，开发者可以全面理解 MCP OpenAPI Server 的设计理念和实现细节，为项目开发和定制化提供坚实的技术基础。