Mcp-Swagger-Server
by zaizaizhao
enterprise-token-integration-solution.md•23.6 kB
# 企业级业务系统Token认证集成方案
## 概述
本文档详细阐述了在mcp-swagger-server中集成企业级业务系统token认证的技术方案。该方案涵盖了从OpenAPI规范解析到MCP工具执行的完整认证流程，确保能够满足企业实际应用场景的安全需求。
## 1. 技术背景分析
### 1.1 现有架构分析
当前mcp-swagger-server的架构包含以下关键组件：
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Swagger Server │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ OpenAPI │ │ Tool │ │ MCP Server │ │
│ │ Parser │→ │ Generator │→ │ Runtime │ │
│ └─────────────┘ └──────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ Transform │ │ Validation │ │ Transport │ │
│ │ Layer │ │ Layer │ │ Adapter │ │
│ └─────────────┘ └──────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 1.2 认证需求分析
企业级业务系统通常需要以下认证机制：
- **Bearer Token**: JWT令牌，包含用户身份和权限信息
- **API Key**: 静态API密钥，用于系统间认证
- **Basic Auth**: 用户名密码认证
- **OAuth 2.0**: 第三方授权认证
- **自定义Header**: 企业特定的认证头
## 2. 技术方案设计
### 2.1 方案架构
```
┌─────────────────────────────────────────────────────────────┐
│ Token认证集成架构 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ 配置层 │ │ 认证中间件 │ │ Token管理器 │ │
│ │ (Config) │→ │ (AuthMiddle) │→ │ (TokenManager) │ │
│ └─────────────┘ └──────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ 工具执行层 │ │ HTTP客户端 │ │ 响应处理器 │ │
│ │ (ToolExec) │→ │ (HttpClient) │→ │ (ResponseHandle)│ │
│ └─────────────┘ └──────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 核心组件设计
#### 2.2.1 认证配置接口
```typescript
interface AuthenticationConfig {
// 认证类型
type: 'bearer' | 'apikey' | 'basic' | 'oauth2' | 'custom';
// 认证参数
credentials: {
// Bearer Token
token?: string;
// API Key
apiKey?: string;
apiKeyHeader?: string; // 默认为 'X-API-Key'
// Basic Auth
username?: string;
password?: string;
// OAuth 2.0
clientId?: string;
clientSecret?: string;
tokenUrl?: string;
scope?: string;
// 自定义认证头
customHeaders?: Record<string, string>;
};
// Token刷新配置
refresh?: {
enabled: boolean;
refreshUrl?: string;
refreshToken?: string;
refreshInterval?: number; // 秒
};
// 认证失效处理
onAuthFailure?: 'retry' | 'fail' | 'refresh';
// 调试模式
debug?: boolean;
}
```
#### 2.2.2 Token管理器
```typescript
interface TokenManager {
// 获取当前有效token
getToken(): Promise<string>;
// 刷新token
refreshToken(): Promise<string>;
// 验证token有效性
validateToken(token: string): Promise<boolean>;
// 处理认证失败
handleAuthFailure(error: AuthError): Promise<void>;
// 获取认证头
getAuthHeaders(): Promise<Record<string, string>>;
}
```
#### 2.2.3 工具执行增强
```typescript
interface EnhancedMCPTool extends MCPTool {
// 认证配置
authConfig?: AuthenticationConfig;
// 执行前钩子
beforeExecute?: (args: any, context: ExecutionContext) => Promise<any>;
// 执行后钩子
afterExecute?: (result: any, context: ExecutionContext) => Promise<any>;
// 错误处理钩子
onError?: (error: Error, context: ExecutionContext) => Promise<any>;
}
```
### 2.3 实现层次
#### 2.3.1 配置层实现
**全局配置方式**：
```typescript
// 在mcp-swagger-server启动时配置
const serverConfig = {
openapi: 'https://api.example.com/openapi.json',
transport: 'streamable',
port: 3322,
auth: {
type: 'bearer',
credentials: {
token: process.env.API_TOKEN || 'your-bearer-token'
},
refresh: {
enabled: true,
refreshUrl: 'https://api.example.com/auth/refresh',
refreshToken: process.env.REFRESH_TOKEN,
refreshInterval: 3600
}
}
};
```
**工具级别配置**：
```typescript
// 为特定工具配置认证
const toolConfig = {
toolId: 'getUserById',
auth: {
type: 'apikey',
credentials: {
apiKey: process.env.USER_API_KEY,
apiKeyHeader: 'X-User-API-Key'
}
}
};
```
#### 2.3.2 中间件实现
**认证中间件**：
```typescript
class AuthenticationMiddleware {
constructor(private config: AuthenticationConfig) {}
async authenticate(request: HttpRequest): Promise<HttpRequest> {
const headers = await this.getAuthHeaders();
return {
...request,
headers: {
...request.headers,
...headers
}
};
}
private async getAuthHeaders(): Promise<Record<string, string>> {
const { type, credentials } = this.config;
switch (type) {
case 'bearer':
return {
'Authorization': `Bearer ${credentials.token}`
};
case 'apikey':
return {
[credentials.apiKeyHeader || 'X-API-Key']: credentials.apiKey
};
case 'basic':
const encoded = Buffer.from(`${credentials.username}:${credentials.password}`).toString('base64');
return {
'Authorization': `Basic ${encoded}`
};
case 'custom':
return credentials.customHeaders || {};
default:
return {};
}
}
}
```
#### 2.3.3 HTTP客户端增强
```typescript
class AuthenticatedHttpClient {
constructor(
private authMiddleware: AuthenticationMiddleware,
private tokenManager: TokenManager
) {}
async request(config: HttpRequestConfig): Promise<HttpResponse> {
let attempts = 0;
const maxRetries = 3;
while (attempts < maxRetries) {
try {
// 添加认证头
const authenticatedConfig = await this.authMiddleware.authenticate(config);
// 发送请求
const response = await this.httpClient.request(authenticatedConfig);
return response;
} catch (error) {
if (this.isAuthError(error) && attempts < maxRetries - 1) {
// 认证失败，尝试刷新token
await this.tokenManager.refreshToken();
attempts++;
continue;
}
throw error;
}
}
}
private isAuthError(error: any): boolean {
return error.status === 401 || error.status === 403;
}
}
```
### 2.4 集成方式
#### 2.4.1 命令行集成
```bash
# 基础用法
mcp-swagger-server \
--openapi https://api.example.com/openapi.json \
--auth-type bearer \
--auth-token "your-bearer-token" \
--transport streamable \
--port 3322
# 高级用法
mcp-swagger-server \
--openapi https://api.example.com/openapi.json \
--auth-config ./auth-config.json \
--transport streamable \
--port 3322
```
**auth-config.json**：
```json
{
"type": "bearer",
"credentials": {
"token": "${API_TOKEN}"
},
"refresh": {
"enabled": true,
"refreshUrl": "https://api.example.com/auth/refresh",
"refreshToken": "${REFRESH_TOKEN}",
"refreshInterval": 3600
},
"onAuthFailure": "refresh",
"debug": false
}
```
#### 2.4.2 编程式集成
```typescript
import { createMcpServer } from 'mcp-swagger-server';
const server = await createMcpServer({
openapi: 'https://api.example.com/openapi.json',
transport: 'streamable',
port: 3322,
auth: {
type: 'bearer',
credentials: {
token: process.env.API_TOKEN
},
refresh: {
enabled: true,
refreshUrl: 'https://api.example.com/auth/refresh',
refreshToken: process.env.REFRESH_TOKEN,
refreshInterval: 3600
}
}
});
await server.start();
```
#### 2.4.3 API集成
```typescript
// 通过mcp-swagger-api服务
const response = await fetch('/api/v1/mcp/create', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key'
},
body: JSON.stringify({
openApiData: 'https://api.example.com/openapi.json',
config: {
name: 'enterprise-api',
version: '1.0.0',
port: 3322,
transport: 'streamable'
},
authConfig: {
type: 'bearer',
credentials: {
token: 'your-bearer-token'
},
refresh: {
enabled: true,
refreshUrl: 'https://api.example.com/auth/refresh',
refreshToken: 'your-refresh-token',
refreshInterval: 3600
}
}
})
});
```
## 3. 企业场景应用
### 3.1 场景一：微服务架构
**需求**：
- 多个微服务，每个服务有独立的认证
- 需要支持JWT令牌和API Key
- 需要自动token刷新
**解决方案**：
```typescript
const microserviceConfigs = [
{
name: 'user-service',
openapi: 'https://user-service.company.com/openapi.json',
auth: {
type: 'bearer',
credentials: { token: process.env.USER_SERVICE_TOKEN },
refresh: { enabled: true, refreshUrl: 'https://auth.company.com/refresh' }
}
},
{
name: 'order-service',
openapi: 'https://order-service.company.com/openapi.json',
auth: {
type: 'apikey',
credentials: {
apiKey: process.env.ORDER_SERVICE_API_KEY,
apiKeyHeader: 'X-Order-API-Key'
}
}
}
];
for (const config of microserviceConfigs) {
await createMcpServer(config);
}
```
### 3.2 场景二：第三方API集成
**需求**：
- 集成多个第三方API（如Salesforce、HubSpot等）
- 每个API有不同的认证方式
- 需要处理token过期和刷新
**解决方案**：
```typescript
const thirdPartyConfigs = {
salesforce: {
openapi: 'https://your-instance.salesforce.com/openapi.json',
auth: {
type: 'oauth2',
credentials: {
clientId: process.env.SALESFORCE_CLIENT_ID,
clientSecret: process.env.SALESFORCE_CLIENT_SECRET,
tokenUrl: 'https://login.salesforce.com/services/oauth2/token',
scope: 'api full'
},
refresh: { enabled: true, refreshInterval: 7200 }
}
},
hubspot: {
openapi: 'https://api.hubapi.com/openapi.json',
auth: {
type: 'bearer',
credentials: { token: process.env.HUBSPOT_ACCESS_TOKEN },
refresh: {
enabled: true,
refreshUrl: 'https://api.hubapi.com/oauth/v1/token',
refreshToken: process.env.HUBSPOT_REFRESH_TOKEN
}
}
}
};
```
### 3.3 场景三：企业内部系统
**需求**：
- 内部系统使用自定义认证头
- 需要支持多环境配置
- 需要支持认证失败重试
**解决方案**：
```typescript
const internalSystemConfig = {
development: {
openapi: 'https://dev-api.company.com/openapi.json',
auth: {
type: 'custom',
credentials: {
customHeaders: {
'X-Company-Token': process.env.DEV_COMPANY_TOKEN,
'X-Environment': 'development',
'X-Client-Version': '1.0.0'
}
},
onAuthFailure: 'retry'
}
},
production: {
openapi: 'https://api.company.com/openapi.json',
auth: {
type: 'custom',
credentials: {
customHeaders: {
'X-Company-Token': process.env.PROD_COMPANY_TOKEN,
'X-Environment': 'production',
'X-Client-Version': '1.0.0'
}
},
onAuthFailure: 'fail'
}
}
};
```
## 4. 技术实现细节
### 4.1 配置管理
**优先级顺序**：
1. 环境变量
2. 配置文件
3. 命令行参数
4. 默认值
**配置文件格式**：
```json
{
"servers": [
{
"id": "enterprise-api",
"openapi": "https://api.company.com/openapi.json",
"auth": {
"type": "bearer",
"credentials": {
"token": "${COMPANY_API_TOKEN}"
},
"refresh": {
"enabled": true,
"refreshUrl": "https://auth.company.com/refresh",
"refreshToken": "${COMPANY_REFRESH_TOKEN}",
"refreshInterval": 3600
}
},
"transport": {
"type": "streamable",
"port": 3322
}
}
]
}
```
### 4.2 Token管理
**Token存储**：
- 内存存储（默认）
- Redis存储（集群部署）
- 文件存储（持久化）
**Token刷新策略**：
- 定时刷新（基于过期时间）
- 被动刷新（认证失败时）
- 主动刷新（手动触发）
### 4.3 错误处理
**认证错误分类**：
- 401 Unauthorized：token无效或过期
- 403 Forbidden：权限不足
- 429 Too Many Requests：请求限流
- 500 Internal Server Error：服务器错误
**错误处理策略**：
```typescript
class AuthErrorHandler {
async handleError(error: AuthError, context: ExecutionContext): Promise<void> {
switch (error.status) {
case 401:
// Token过期，尝试刷新
await this.tokenManager.refreshToken();
break;
case 403:
// 权限不足，记录日志
this.logger.warn('Insufficient permissions', { context });
break;
case 429:
// 请求限流，等待重试
await this.delay(error.retryAfter || 60000);
break;
default:
// 其他错误，抛出异常
throw error;
}
}
}
```
### 4.4 监控和日志
**监控指标**：
- 认证成功率
- Token刷新频率
- API调用延迟
- 错误率统计
**日志记录**：
```typescript
class AuthLogger {
logAuthSuccess(toolName: string, duration: number): void {
this.logger.info('Authentication successful', {
tool: toolName,
duration,
timestamp: new Date().toISOString()
});
}
logAuthFailure(toolName: string, error: AuthError): void {
this.logger.error('Authentication failed', {
tool: toolName,
error: error.message,
status: error.status,
timestamp: new Date().toISOString()
});
}
logTokenRefresh(success: boolean): void {
this.logger.info('Token refresh attempt', {
success,
timestamp: new Date().toISOString()
});
}
}
```
## 5. 部署和运维
### 5.1 容器化部署
**Dockerfile**：
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
# 环境变量
ENV NODE_ENV=production
ENV API_TOKEN=""
ENV REFRESH_TOKEN=""
EXPOSE 3322
CMD ["mcp-swagger-server", "--config", "/app/config/auth.json"]
```
**Docker Compose**：
```yaml
version: '3.8'
services:
mcp-swagger-server:
build: .
ports:
- "3322:3322"
environment:
- NODE_ENV=production
- API_TOKEN=${API_TOKEN}
- REFRESH_TOKEN=${REFRESH_TOKEN}
volumes:
- ./config:/app/config
restart: unless-stopped
```
### 5.2 Kubernetes部署
**Deployment**：
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-swagger-server
spec:
replicas: 3
selector:
matchLabels:
app: mcp-swagger-server
template:
metadata:
labels:
app: mcp-swagger-server
spec:
containers:
- name: mcp-swagger-server
image: mcp-swagger-server:latest
ports:
- containerPort: 3322
env:
- name: API_TOKEN
valueFrom:
secretKeyRef:
name: api-secrets
key: token
- name: REFRESH_TOKEN
valueFrom:
secretKeyRef:
name: api-secrets
key: refresh-token
volumeMounts:
- name: config
mountPath: /app/config
volumes:
- name: config
configMap:
name: mcp-config
```
### 5.3 监控和告警
**Prometheus监控**：
```yaml
# prometheus.yml
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'mcp-swagger-server'
static_configs:
- targets: ['localhost:3322']
metrics_path: '/metrics'
```
**Grafana面板**：
- 认证成功率
- API调用QPS
- 响应时间分布
- 错误率趋势
## 6. 安全考虑
### 6.1 Token安全
**存储安全**：
- 使用环境变量存储敏感信息
- 避免在代码中硬编码token
- 使用加密存储敏感配置
**传输安全**：
- 强制使用HTTPS
- 实现证书校验
- 使用TLS 1.2+
### 6.2 访问控制
**权限管理**：
- 实现基于角色的访问控制（RBAC）
- 支持API级别的权限控制
- 实现请求频率限制
**审计日志**：
- 记录所有认证事件
- 记录API调用详情
- 实现日志完整性保护
## 7. 性能优化
### 7.1 连接池管理
```typescript
class ConnectionPoolManager {
private pools: Map<string, HttpConnectionPool> = new Map();
getPool(baseUrl: string): HttpConnectionPool {
if (!this.pools.has(baseUrl)) {
this.pools.set(baseUrl, new HttpConnectionPool({
maxConnections: 10,
keepAliveTimeout: 30000,
connectionTimeout: 5000
}));
}
return this.pools.get(baseUrl)!;
}
}
```
### 7.2 缓存策略
```typescript
class TokenCache {
private cache: Map<string, CacheEntry> = new Map();
set(key: string, token: string, ttl: number): void {
const expiry = Date.now() + ttl * 1000;
this.cache.set(key, { token, expiry });
}
get(key: string): string | null {
const entry = this.cache.get(key);
if (!entry || entry.expiry < Date.now()) {
this.cache.delete(key);
return null;
}
return entry.token;
}
}
```
## 8. 测试策略
### 8.1 单元测试
```typescript
describe('AuthenticationMiddleware', () => {
let middleware: AuthenticationMiddleware;
beforeEach(() => {
middleware = new AuthenticationMiddleware({
type: 'bearer',
credentials: { token: 'test-token' }
});
});
it('should add Bearer token to headers', async () => {
const request = { headers: {} };
const result = await middleware.authenticate(request);
expect(result.headers.Authorization).toBe('Bearer test-token');
});
});
```
### 8.2 集成测试
```typescript
describe('MCP Server with Authentication', () => {
let server: McpServer;
beforeEach(async () => {
server = await createMcpServer({
openapi: 'https://httpbin.org/spec.json',
auth: {
type: 'bearer',
credentials: { token: 'test-token' }
}
});
});
it('should make authenticated API calls', async () => {
const result = await server.callTool('get', { url: '/headers' });
expect(result.headers.Authorization).toBe('Bearer test-token');
});
});
```
## 9. 可行性分析
### 9.1 技术可行性
**优势**：
- 现有架构已支持HTTP客户端扩展
- TypeScript提供完整的类型安全
- 模块化设计便于集成认证功能
- 支持多种传输协议
**挑战**：
- 需要修改现有工具生成逻辑
- 需要实现复杂的token管理机制
- 需要考虑向后兼容性
### 9.2 企业适用性
**适用场景**：
- 微服务架构的企业
- 使用标准OAuth 2.0的系统
- 需要API统一管理的企业
- 有AI助手集成需求的企业
**限制条件**：
- 需要OpenAPI 3.0+规范
- 需要支持标准认证协议
- 需要网络访问权限
### 9.3 性能影响
**预期影响**：
- 增加认证处理时间（~10-50ms）
- 增加内存使用（token缓存）
- 增加网络请求（token刷新）
**优化措施**：
- 实现token缓存机制
- 使用连接池减少连接开销
- 实现智能token刷新策略
## 10. 实施计划
### 10.1 第一阶段（2周）
**目标**：基础认证功能实现
- 实现AuthenticationConfig接口
- 实现基础认证中间件
- 支持Bearer Token和API Key
- 添加基础测试用例
### 10.2 第二阶段（2周）
**目标**：高级认证功能
- 实现Token管理器
- 支持OAuth 2.0认证
- 实现token自动刷新
- 添加错误处理机制
### 10.3 第三阶段（1周）
**目标**：集成和测试
- 集成到现有CLI工具
- 实现API接口
- 完善文档和示例
- 进行端到端测试
### 10.4 第四阶段（1周）
**目标**：部署和监控
- 实现监控指标
- 完善日志记录
- 准备部署文档
- 进行性能测试
## 11. 总结
本方案提供了一个完整的企业级token认证集成解决方案，具有以下特点：
### 11.1 技术优势
1. **全面的认证支持**：支持Bearer Token、API Key、OAuth 2.0等多种认证方式
2. **智能token管理**：自动刷新、缓存、错误处理
3. **企业级特性**：监控、日志、部署支持
4. **向后兼容**：不影响现有功能
### 11.2 企业价值
1. **安全性**：确保API调用的安全性
2. **可维护性**：统一的认证管理
3. **可扩展性**：支持多种认证方式
4. **可观测性**：完整的监控和日志
### 11.3 实施建议
1. **分阶段实施**：按照实施计划逐步推进
2. **充分测试**：确保功能稳定性和性能
3. **文档完善**：提供详细的使用文档
4. **社区反馈**：收集用户反馈并持续改进
该方案能够有效解决企业级业务系统中的token认证问题，提供安全、可靠、高性能的API集成能力。
Latest Blog Posts
- MCP Moves to the Linux Foundation: Neutral Stewardship for Agentic InfrastructureBy Om-Shree-0709 on .mcpanthropicLinux Foundation
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/zaizaizhao/mcp-swagger-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server