mcp-swagger-server/docs/custom-headers-implementation-summary.md

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

## 📋 功能概述

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

## 🎯 核心特性

### ✅ 已实现的功能

1. **多种请求头类型支持**
   - 静态请求头：固定值的请求头
   - 环境变量请求头：从环境变量获取值的请求头
   - 动态请求头：基于请求上下文动态生成的请求头
   - 条件请求头：根据条件决定是否添加的请求头

2. **多种配置方式**
   - 命令行参数：`--custom-header`、`--custom-header-env`
   - 配置文件：`--custom-headers-config`
   - MCP 配置：在 MCP 配置文件中定义
   - 环境变量：支持从环境变量读取值

3. **调试和安全机制**
   - 调试模式：`--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/                              # 编译输出
```

### 类型定义

```typescript
// 自定义请求头配置
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. 命令行参数

```bash
# 基本用法
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. 配置文件

```json
{
  "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"
  }
}
```

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

### 3. MCP 配置

```json
{
  "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
}
```

```bash
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. 安装依赖

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

### 2. 构建项目

```bash
npm run build
```

### 3. 基本使用

```bash
# 设置环境变量
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. 测试环境

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

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

## 📝 配置示例

### 完整配置文件示例

```json
{
  "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
}
```

## 🔍 调试和故障排除

### 启用调试模式

```bash
# 命令行
--debug-headers

# 配置文件
"debugHeaders": true
```

### 常见问题

1. **环境变量未找到**
   - 检查环境变量是否正确设置
   - 使用 `--debug-headers` 查看实际值

2. **请求头被覆盖**
   - 检查优先级：CLI > 配置文件 > 环境变量
   - 查看受保护请求头列表

3. **配置文件未加载**
   - 检查文件路径是否正确
   - 检查 JSON 格式是否有效

## 🎯 最佳实践

1. **安全性**
   - 敏感信息使用环境变量
   - 避免在配置文件中硬编码密钥
   - 使用 `.env` 文件管理环境变量

2. **性能**
   - 避免过多的动态请求头
   - 优先使用静态请求头
   - 合理使用条件请求头

3. **维护性**
   - 使用配置文件管理复杂配置
   - 为不同环境创建不同配置
   - 使用有意义的请求头名称

## 📚 相关文档

- [自定义请求头设计文档](./docs/custom-headers-design.md)
- [实现指南](./docs/custom-headers-implementation.md)
- [快速上手指南](./docs/custom-headers-quickstart.md)
- [API 认证指南](./docs/api-authentication-guide.md)

## 🤝 贡献

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

1. 查看 [GitHub Issues](https://github.com/zaizaizhao/mcp-swagger-server/issues)
2. 创建新的 Issue 或 Pull Request
3. 遵循项目的贡献指南

## 📄 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](./LICENSE) 文件。

---

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