8.4 KiB

Raw Blame History

Bearer Token认证快速开始指南

概述

本指南提供了在mcp-swagger-server中快速实现Bearer Token认证的最简方案。

核心需求

为业务系统API调用自动添加 Authorization: Bearer <token> 头
支持多种Token配置方式
保持向后兼容性
预留扩展接口

实现方案

1. 最小化实现架构

mcp-swagger-server
├── 认证配置解析 (Server层)
├── 认证配置传递 (传递给Parser)
├── Parser层增强 (核心修改点)
│   ├── TransformerOptions扩展
│   ├── BearerAuthManager
│   └── executeHttpRequest修改
└── CLI参数支持

2. 核心文件修改

2.1 Parser层认证支持

新增文件: packages/mcp-swagger-parser/src/auth/types.ts

export interface AuthConfig {
  type: 'bearer' | 'none';
  bearer?: {
    token: string;
    source: 'static' | 'env';
    envName?: string;
  };
}

export interface AuthManager {
  getAuthHeaders(): Promise<Record<string, string>>;
  getToken(): Promise<string>;
}

export class BearerAuthManager implements AuthManager {
  constructor(private config: AuthConfig) {}
  
  async getAuthHeaders(): Promise<Record<string, string>> {
    if (this.config.type !== 'bearer') return {};
    
    const token = await this.getToken();
    return { 'Authorization': `Bearer ${token}` };
  }
  
  private async getToken(): Promise<string> {
    const { bearer } = this.config;
    if (!bearer) throw new Error('Bearer config required');
    
    if (bearer.source === 'env') {
      const envToken = process.env[bearer.envName || 'API_TOKEN'];
      if (!envToken) throw new Error(`Environment variable ${bearer.envName} not found`);
      return envToken;
    }
    
    return bearer.token;
  }
}

2.2 扩展TransformerOptions

修改文件: packages/mcp-swagger-parser/src/transformer/types.ts

import { AuthConfig } from '../auth/types';

export interface TransformerOptions {
  baseUrl?: string;
  includeDeprecated?: boolean;
  includeTags?: string[];
  excludeTags?: string[];
  requestTimeout?: number;
  defaultHeaders?: Record<string, string>;
  customHandlers?: Record<string, (args: any) => Promise<MCPToolResponse>>;
  pathPrefix?: string;
  stripBasePath?: boolean;
  includeFieldAnnotations?: boolean;
  annotationOptions?: AnnotationOptions;
  
  // 新增：认证配置
  authConfig?: AuthConfig;
}

2.3 修改Transformer类

修改文件: packages/mcp-swagger-parser/src/transformer/index.ts

import { BearerAuthManager, AuthManager } from '../auth/types';

export class OpenAPIToMCPTransformer {
  private spec: OpenAPISpec;
  private options: Required<TransformerOptions>;
  private annotationExtractor: SchemaAnnotationExtractor;
  private authManager?: AuthManager; // 新增

  constructor(spec: OpenAPISpec, options: TransformerOptions = {}) {
    this.spec = spec;
    this.options = {
      // ...existing options...
      authConfig: options.authConfig || { type: 'none' }
    };

    this.annotationExtractor = new SchemaAnnotationExtractor(spec);
    
    // 初始化认证管理器
    if (this.options.authConfig?.type === 'bearer') {
      this.authManager = new BearerAuthManager(this.options.authConfig);
    }
  }

  // 修改executeHttpRequest方法
  private async executeHttpRequest(
    method: string,
    path: string,
    args: any,
    operation: OperationObject
  ): Promise<MCPToolResponse> {
    try {
      const { url, queryParams } = this.buildUrlWithParams(path, args, operation);
      
      // 准备请求头
      const headers = { ...this.options.defaultHeaders };
      
      // 新增：添加认证头
      if (this.authManager) {
        const authHeaders = await this.authManager.getAuthHeaders();
        Object.assign(headers, authHeaders);
      }

      const requestBody = this.buildRequestBody(args, operation);

      const response = await axios({
        method: method.toLowerCase() as any,
        url,
        params: queryParams,
        data: requestBody,
        headers, // 包含认证头
        timeout: this.options.requestTimeout,
        validateStatus: () => true,
        maxRedirects: 5,
        responseType: 'json'
      });

      return this.formatHttpResponse(response, method, path, operation);
    } catch (error) {
      return this.handleRequestError(error, method, path);
    }
  }
}

2.4 Server层集成

修改文件: packages/mcp-swagger-server/src/server/index.ts

import { OpenAPIToMCPTransformer } from 'mcp-swagger-parser';

export class McpServer {
  constructor(private config: McpServerConfig) {}
  
  async start(): Promise<void> {
    const spec = await this.loadOpenApiSpec();
    
    // 创建transformer时传递认证配置
    const transformer = new OpenAPIToMCPTransformer(spec, {
      baseUrl: this.config.baseUrl,
      authConfig: this.config.auth, // 关键：传递认证配置
      requestTimeout: this.config.timeout
    });
    
    const tools = transformer.transformToMCPTools();
    await this.startMcpServer(tools);
  }
}

使用方式

1. 命令行使用

# 使用静态token
mcp-swagger-server \
  --openapi https://api.example.com/openapi.json \
  --auth-type bearer \
  --bearer-token "your-token-here"

# 使用环境变量
export API_TOKEN="your-token-here"
mcp-swagger-server \
  --openapi https://api.example.com/openapi.json \
  --auth-type bearer \
  --bearer-env API_TOKEN

2. 配置文件使用

{
  "openapi": "https://api.example.com/openapi.json",
  "auth": {
    "type": "bearer",
    "bearer": {
      "source": "env",
      "envName": "API_TOKEN"
    }
  }
}

3. 编程式使用

import { createServer } from 'mcp-swagger-server';
import { BearerAuth } from 'mcp-swagger-server/auth';

const auth = new BearerAuth({
  type: 'bearer',
  bearer: {
    token: 'your-token',
    source: 'static'
  }
});

const server = await createServer({
  openapi: 'https://api.example.com/openapi.json',
  auth
});

await server.start();

实施步骤

第1天：Parser层认证基础

创建认证类型定义 (auth/types.ts)
实现BearerAuthManager类
扩展TransformerOptions接口
添加基础测试

第2天：Parser层HTTP请求增强

修改OpenAPIToMCPTransformer构造函数
修改executeHttpRequest方法添加认证头
测试HTTP请求包含Bearer Token
验证认证流程

第3天：Server层集成

修改McpServerConfig支持认证
更新McpServer类传递认证配置到Parser
测试端到端认证流程
确保配置正确传递

第4天：CLI和API集成

添加CLI参数支持认证配置
更新mcp-swagger-api支持认证
添加配置文件支持
测试不同配置方式

第5天：测试和文档

完善测试覆盖
编写使用文档和示例
准备发布
端到端验证

验证方式

1. 单元测试

describe('BearerAuth', () => {
  it('should add authorization header', async () => {
    const auth = new BearerAuth({
      type: 'bearer',
      bearer: { token: 'test-token', source: 'static' }
    });
    
    const headers = await auth.getHeaders();
    expect(headers.Authorization).toBe('Bearer test-token');
  });
});

2. 集成测试

# 启动测试服务器
mcp-swagger-server --openapi https://httpbin.org/spec.json --auth-type bearer --bearer-token test-token

# 验证API调用包含认证头
curl -X GET http://localhost:3322/mcp/tools/get/headers

3. 手工测试

使用httpbin.org测试认证头传递
测试不同Token配置方式
验证错误处理

风险和注意事项

安全风险

避免在日志中记录Token
使用环境变量存储敏感信息
确保HTTPS传输

兼容性风险

保持现有API不变
认证功能可选启用
向后兼容现有配置

性能考虑

避免频繁Token获取
复用HTTP连接
合理的错误重试

扩展计划

短期扩展

API Key认证
Basic认证
自定义Header认证

长期扩展

OAuth2认证
JWT Token刷新
多认证方式组合

总结

这个方案提供了最小化的Bearer Token认证实现，具有以下特点：

简单易用: 核心功能只需4个文件修改
配置灵活: 支持静态Token和环境变量
向后兼容: 不影响现有功能
易于扩展: 为其他认证方式预留接口

该方案可以在5天内完成实施，满足基本的Bearer Token认证需求。

8.4 KiB Raw Blame History Unescape Escape