7.3 KiB

Raw Blame History

自定义请求头功能实现总结

📋 功能概述

MCP Swagger Server 现已支持自定义请求头功能，使其在代理 OpenAPI 接口时，除了认证 Bearer Token 外，还能灵活配置和传递常见的自定义 HTTP 请求头。

🎯 核心特性

✅ 已实现的功能

多种请求头类型支持
- 静态请求头：固定值的请求头
- 环境变量请求头：从环境变量获取值的请求头
- 动态请求头：基于请求上下文动态生成的请求头
- 条件请求头：根据条件决定是否添加的请求头
多种配置方式
- 命令行参数：--custom-header、--custom-header-env
- 配置文件：--custom-headers-config
- MCP 配置：在 MCP 配置文件中定义
- 环境变量：支持从环境变量读取值
调试和安全机制
- 调试模式：--debug-headers 显示请求头合并过程
- 受保护的请求头：防止覆盖关键系统请求头
- 优先级机制：CLI > 配置文件 > 环境变量

🏗️ 架构实现

核心组件

packages/
├── mcp-swagger-parser/
│   ├── src/
│   │   ├── headers/
│   │   │   ├── CustomHeadersManager.ts    # 自定义请求头管理器
│   │   │   ├── generators.ts              # 预定义动态头生成器
│   │   │   └── index.ts                   # 导出接口
│   │   ├── transformer/
│   │   │   ├── types.ts                   # 类型定义
│   │   │   └── index.ts                   # 集成到转换器
│   │   └── index.ts                       # 对外导出
│   └── tests/
│       └── unit/
│           └── auth.test.ts               # 单元测试
└── mcp-swagger-server/
    ├── src/
    │   ├── cli.ts                         # CLI 参数解析
    │   ├── server.ts                      # 服务器启动
    │   ├── tools/
    │   │   └── initTools.ts               # 工具初始化
    │   └── transform/
    │       └── transformOpenApiToMcpTools.ts  # OpenAPI 转换
    └── dist/                              # 编译输出

类型定义

// 自定义请求头配置
interface CustomHeaders {
  static?: Record<string, string>;
  env?: Record<string, string>;
  dynamic?: Record<string, string>;
  conditional?: Record<string, {
    condition: string | ((context: RequestContext) => boolean);
    value: string;
  }>;
}

// 请求上下文
interface RequestContext {
  method: string;
  path: string;
  args: any;
  operation?: OperationObject;
}

🔧 使用方式

1. 命令行参数

# 基本用法
mcp-swagger-server \
  --openapi ./api.json \
  --custom-header "X-Client-ID=my-client" \
  --custom-header "X-Version=1.0.0" \
  --custom-header-env "X-API-Key=API_KEY" \
  --debug-headers

# 完整示例
mcp-swagger-server \
  --openapi https://petstore.swagger.io/v2/swagger.json \
  --custom-header "X-Client-ID=mcp-client" \
  --custom-header "X-Request-Source=cli" \
  --custom-header-env "X-API-Key=PETSTORE_API_KEY" \
  --custom-header-env "X-User-Agent=USER_AGENT" \
  --debug-headers

2. 配置文件

{
  "static": {
    "X-Custom-Client": "mcp-swagger-client",
    "X-Version": "1.0.0",
    "X-Request-Source": "config"
  },
  "env": {
    "X-API-Key": "API_KEY",
    "X-User-Agent": "USER_AGENT",
    "X-Environment": "NODE_ENV"
  }
}

mcp-swagger-server \
  --openapi ./api.json \
  --custom-headers-config ./headers.json \
  --debug-headers

3. MCP 配置

{
  "name": "my-api-server",
  "version": "1.0.0",
  "openapi": "./api.json",
  "customHeaders": {
    "static": {
      "X-MCP-Client": "mcp-swagger-server",
      "X-Request-ID": "auto-generated"
    },
    "env": {
      "X-API-Key": "API_KEY",
      "X-Client-ID": "CLIENT_ID"
    }
  },
  "debugHeaders": true
}

mcp-swagger-server --config ./mcp-config.json

📊 测试结果

单元测试

✅ CustomHeadersManager
  ✅ getHeaders
    ✅ should handle static headers
    ✅ should handle environment variable headers  
    ✅ should return empty object for no config

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total

功能测试

✅ 静态请求头处理
✅ 环境变量请求头处理
✅ 配置文件加载
✅ 命令行参数解析
✅ 调试模式输出
✅ 优先级机制
✅ 受保护请求头机制

🚀 快速上手

1. 安装依赖

cd /path/to/mcp-swagger-server
pnpm install

2. 构建项目

npm run build

3. 基本使用

# 设置环境变量
export API_KEY="your-api-key"
export CLIENT_ID="your-client-id"

# 启动服务器
node packages/mcp-swagger-server/dist/cli.js \
  --openapi https://petstore.swagger.io/v2/swagger.json \
  --custom-header "X-Client-ID=mcp-client" \
  --custom-header-env "X-API-Key=API_KEY" \
  --debug-headers

4. 测试环境

# 创建测试环境
node create-test-environment.js

# 运行测试
cd test-custom-headers
bash run-tests.sh

📝 配置示例

完整配置文件示例

{
  "name": "production-api-server",
  "version": "1.0.0",
  "transport": "stdio",
  "openapi": "https://api.example.com/openapi.json",
  "auth": {
    "type": "bearer",
    "token": "$API_TOKEN"
  },
  "customHeaders": {
    "static": {
      "X-Client-Name": "mcp-swagger-server",
      "X-Client-Version": "1.2.2",
      "X-Request-Source": "mcp",
      "Accept": "application/json",
      "Content-Type": "application/json"
    },
    "env": {
      "X-API-Key": "API_KEY",
      "X-Client-ID": "CLIENT_ID",
      "X-Environment": "NODE_ENV",
      "X-User-Agent": "USER_AGENT"
    }
  },
  "debugHeaders": false
}

🔍 调试和故障排除

启用调试模式

# 命令行
--debug-headers

# 配置文件
"debugHeaders": true

常见问题

环境变量未找到
- 检查环境变量是否正确设置
- 使用 --debug-headers 查看实际值
请求头被覆盖
- 检查优先级：CLI > 配置文件 > 环境变量
- 查看受保护请求头列表
配置文件未加载
- 检查文件路径是否正确
- 检查 JSON 格式是否有效

🎯 最佳实践

安全性
- 敏感信息使用环境变量
- 避免在配置文件中硬编码密钥
- 使用 .env 文件管理环境变量
性能
- 避免过多的动态请求头
- 优先使用静态请求头
- 合理使用条件请求头
维护性
- 使用配置文件管理复杂配置
- 为不同环境创建不同配置
- 使用有意义的请求头名称

📚 相关文档

🤝 贡献

如果您发现问题或有改进建议，请：

查看 GitHub Issues
创建新的 Issue 或 Pull Request
遵循项目的贡献指南

📄 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

实现完成日期: 2025年7月10日
实现者: GitHub Copilot
版本: mcp-swagger-server v1.2.2

7.3 KiB Raw Blame History Unescape Escape