mirrors/mcphub
1
0
Fork 0
mirror of https://github.com/samanhappy/mcphub.git synced 2025-12-23 18:29:21 -05:00
Code Issues Packages Projects Releases Wiki Activity

Remove outdated documentation files (#458)

Browse Source
This commit is contained in:
samanhappy
2025-11-30 17:29:37 +08:00
committed by GitHub
parent 884870c9de
commit 19f11a0927
12 changed files with 10 additions and 2179 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
SECURITY_SUMMARY.md
View File

@@ -1,187 +0,0 @@
# Security Summary - OAuth Authorization Server Implementation
## Overview
This document summarizes the security analysis and measures taken for the OAuth 2.0 authorization server implementation in MCPHub.
## Vulnerability Scan Results
### Dependency Vulnerabilities
✅ **PASSED**: No vulnerabilities found in dependencies
- `@node-oauth/oauth2-server@5.2.1` - Clean scan, no known vulnerabilities
- All other dependencies scanned and verified secure
### Code Security Analysis (CodeQL)
⚠️ **ADVISORY**: 12 alerts found regarding missing rate limiting on authentication endpoints
**Details:**
- **Issue**: Authorization routes do not have rate limiting middleware
- **Impact**: Potential brute force attacks on authentication endpoints
- **Severity**: Medium
- **Status**: Documented, not critical
**Affected Endpoints:**
- `/oauth/authorize` (GET/POST)
- `/oauth/token` (POST)
- `/api/oauth/clients/*` (various methods)
**Mitigation:**
1. All endpoints require proper authentication
2. Authorization codes expire after 5 minutes by default
3. Access tokens expire after 1 hour by default
4. Failed authentication attempts are logged
5. Documentation includes rate limiting recommendations for production
**Recommended Actions for Production:**
- Implement `express-rate-limit` middleware on OAuth endpoints
- Consider using reverse proxy rate limiting (nginx, Cloudflare)
- Monitor for suspicious authentication patterns
- Set up alerting for repeated failed attempts
## Security Features Implemented
### Authentication & Authorization
✅ **OAuth 2.0 Compliance**: Fully compliant with RFC 6749
✅ **PKCE Support**: RFC 7636 implementation for public clients
✅ **Token-based Authentication**: Access tokens and refresh tokens
✅ **JWT Integration**: Backward compatible with existing JWT auth
✅ **User Permissions**: Proper admin status lookup for OAuth users
### Input Validation
✅ **Query Parameter Validation**: All OAuth parameters validated with regex patterns
✅ **Client ID Validation**: Alphanumeric with hyphens/underscores only
✅ **Redirect URI Validation**: Strict matching against registered URIs
✅ **Scope Validation**: Only allowed scopes can be requested
✅ **State Parameter**: CSRF protection via state validation
### Output Security
✅ **XSS Protection**: All user input HTML-escaped in authorization page
✅ **HTML Escaping**: Custom escapeHtml function for template rendering
✅ **Safe Token Handling**: Tokens never exposed in URLs or logs
### Token Security
✅ **Secure Token Generation**: Cryptographically random tokens (32 bytes)
✅ **Token Expiration**: Configurable lifetimes for all token types
✅ **Token Revocation**: Support for revoking access and refresh tokens
✅ **Automatic Cleanup**: Expired tokens automatically removed from memory
### Transport Security
✅ **HTTPS Ready**: Designed for HTTPS in production
✅ **No Tokens in URL**: Access tokens never passed in query parameters
✅ **Secure Headers**: Proper Content-Type and security headers
### Client Security
✅ **Client Secret Support**: Optional for confidential clients
✅ **Public Client Support**: PKCE for clients without secrets
✅ **Redirect URI Whitelist**: Strict validation of redirect destinations
✅ **Client Registration**: Secure client management API
### Code Quality
✅ **TypeScript Strict Mode**: Full type safety
✅ **ESLint Clean**: No linting errors
✅ **Test Coverage**: 180 tests passing, including 11 OAuth-specific tests
✅ **Async Safety**: Proper async/await usage throughout
✅ **Resource Cleanup**: Graceful shutdown support with interval cleanup
## Security Best Practices Followed
1. **Defense in Depth**: Multiple layers of security (auth, validation, escaping)
2. **Principle of Least Privilege**: Scopes limit what clients can access
3. **Fail Securely**: Invalid requests rejected with appropriate errors
4. **Security by Default**: Secure settings out of the box
5. **Standard Compliance**: Following OAuth 2.0 and PKCE RFCs
6. **Code Reviews**: All changes reviewed for security implications
7. **Documentation**: Comprehensive security guidance provided
## Known Limitations
### In-Memory Token Storage
**Issue**: Tokens stored in memory, not persisted to database
**Impact**: Tokens lost on server restart
**Mitigation**: Refresh tokens allow users to re-authenticate
**Future**: Consider database storage for production deployments
### Rate Limiting
**Issue**: No built-in rate limiting on OAuth endpoints
**Impact**: Potential brute force attacks
**Mitigation**:
- Short-lived authorization codes (5 min default)
- Authentication required for authorization endpoint
- Documented recommendations for production
**Future**: Consider adding rate limiting middleware
### Token Introspection
**Issue**: No token introspection endpoint (RFC 7662)
**Impact**: Limited third-party token validation
**Mitigation**: Clients can use userinfo endpoint
**Future**: Consider implementing RFC 7662 if needed
## Production Deployment Recommendations
### Critical
1. ✅ Use HTTPS in production (SSL/TLS certificates)
2. ✅ Change default admin password immediately
3. ✅ Use strong client secrets for confidential clients
4. ⚠️ Implement rate limiting (express-rate-limit or reverse proxy)
5. ✅ Enable proper logging and monitoring
### Recommended
6. Consider using a database for token storage
7. Set up automated security scanning in CI/CD
8. Use a reverse proxy (nginx) with security headers
9. Implement IP whitelisting for admin endpoints
10. Regular security audits and dependency updates
### Optional
11. Implement token introspection endpoint
12. Add support for JWT-based access tokens
13. Integrate with external OAuth providers
14. Implement advanced scope management
15. Add OAuth client approval workflow
## Compliance & Standards
✅ **OAuth 2.0 (RFC 6749)**: Full authorization code grant implementation
✅ **PKCE (RFC 7636)**: Code challenge and verifier support
✅ **OAuth Server Metadata (RFC 8414)**: Discovery endpoint available
✅ **OpenID Connect Compatible**: Basic userinfo endpoint
## Vulnerability Disclosure
If you discover a security vulnerability in MCPHub's OAuth implementation, please:
1. **Do Not** create a public GitHub issue
2. Email the maintainers privately
3. Provide detailed reproduction steps
4. Allow time for a fix before public disclosure
## Security Update Policy
- **Critical vulnerabilities**: Patched within 24-48 hours
- **High severity**: Patched within 1 week
- **Medium severity**: Patched in next minor release
- **Low severity**: Patched in next patch release
## Conclusion
The OAuth 2.0 authorization server implementation in MCPHub follows security best practices and is production-ready with the noted limitations. The main advisory regarding rate limiting should be addressed in production deployments through application-level or reverse proxy rate limiting.
**Overall Security Assessment**: ✅ **SECURE** with production hardening recommendations
**Last Updated**: 2025-11-02
**Next Review**: Recommended quarterly or after major changes

5
docs/configuration/database-configuration.mdx
View File

@@ -1,3 +1,8 @@
---
title: 'Database Configuration'
description: 'Configuring MCPHub to use a PostgreSQL database as an alternative to the mcp_settings.json file.'
---
# Database Configuration for MCPHub # Database Configuration for MCPHub
## Overview ## Overview

210
docs/dao-implementation-summary.md
View File

@@ -1,210 +0,0 @@
# MCPHub DAO Layer 实现总结
## 项目概述
本次开发为MCPHub项目引入了独立的数据访问对象(DAO)层，用于管理`mcp_settings.json`中的不同类型数据的增删改查操作。
## 已实现的功能
### 1. 核心DAO层架构
#### 基础架构
- **BaseDao.ts**: 定义了通用的CRUD接口和抽象实现
- **JsonFileBaseDao.ts**: 提供JSON文件操作的基础类，包含缓存机制
- **DaoFactory.ts**: 工厂模式实现，提供DAO实例的创建和管理
#### 具体DAO实现
1. **UserDao**: 用户数据管理
- 用户创建（含密码哈希）
- 密码验证
- 权限管理
- 管理员查询
2. **ServerDao**: 服务器配置管理
- 服务器CRUD操作
- 按所有者/类型/状态查询
- 工具和提示配置管理
- 启用/禁用控制
3. **GroupDao**: 群组管理
- 群组CRUD操作
- 服务器成员管理
- 按所有者查询
- 群组-服务器关系管理
4. **SystemConfigDao**: 系统配置管理
- 系统级配置的读取和更新
- 分段配置管理
- 配置重置功能
5. **UserConfigDao**: 用户个人配置管理
- 用户个人配置的CRUD操作
- 分段配置管理
- 批量配置查询
### 2. 配置服务集成
#### DaoConfigService
- 使用DAO层重新实现配置加载和保存
- 支持用户权限过滤
- 提供配置合并和验证功能
#### ConfigManager
- 双模式支持：传统文件方式 + 新DAO层
- 运行时切换机制
- 环境变量控制 (`USE_DAO_LAYER`)
- 迁移工具集成
### 3. 迁移和验证工具
#### 迁移功能
- 从传统JSON文件格式迁移到DAO层
- 数据完整性验证
- 性能对比分析
- 迁移报告生成
#### 测试工具
- DAO操作完整性测试
- 示例数据生成和清理
- 性能基准测试
## 文件结构
```
src/
├── dao/ # DAO层核心
│ ├── base/
│ │ ├── BaseDao.ts # 基础DAO接口
│ │ └── JsonFileBaseDao.ts # JSON文件基础类
│ ├── UserDao.ts # 用户数据访问
│ ├── ServerDao.ts # 服务器配置访问
│ ├── GroupDao.ts # 群组数据访问
│ ├── SystemConfigDao.ts # 系统配置访问
│ ├── UserConfigDao.ts # 用户配置访问
│ ├── DaoFactory.ts # DAO工厂
│ ├── examples.ts # 使用示例
│ └── index.ts # 统一导出
├── config/
│ ├── DaoConfigService.ts # DAO配置服务
│ ├── configManager.ts # 配置管理器
│ └── migrationUtils.ts # 迁移工具
├── scripts/
│ └── dao-demo.ts # 演示脚本
└── docs/
└── dao-layer.md # 详细文档
```
## 主要特性
### 1. 类型安全
- 完整的TypeScript类型定义
- 编译时类型检查
- 接口约束和验证
### 2. 模块化设计
- 每种数据类型独立的DAO
- 清晰的关注点分离
- 可插拔的实现方式
### 3. 缓存机制
- JSON文件读取缓存
- 文件修改时间检测
- 缓存失效和刷新
### 4. 向后兼容
- 保持现有API不变
- 支持传统和DAO双模式
- 平滑迁移路径
### 5. 未来扩展性
- 数据库切换准备
- 新数据类型支持
- 复杂查询能力
## 使用方法
### 启用DAO层
```bash
# 环境变量配置
export USE_DAO_LAYER=true
```
### 基本操作示例
```typescript
import { getUserDao, getServerDao } from './dao/index.js';
// 用户操作
const userDao = getUserDao();
await userDao.createWithHashedPassword('admin', 'password', true);
const user = await userDao.findByUsername('admin');
// 服务器操作
const serverDao = getServerDao();
await serverDao.create({
name: 'my-server',
command: 'node',
args: ['server.js']
});
```
### 迁移操作
```typescript
import { migrateToDao, validateMigration } from './config/configManager.js';
// 执行迁移
await migrateToDao();
// 验证迁移
await validateMigration();
```
## 依赖包
新增的依赖包：
- `bcrypt`: 用户密码哈希
- `@types/bcrypt`: bcrypt类型定义
- `uuid`: UUID生成（群组ID）
- `@types/uuid`: uuid类型定义
## 测试状态
✅ **编译测试**: 项目成功编译，无TypeScript错误
✅ **类型检查**: 所有类型定义正确
✅ **依赖安装**: 必要依赖包已安装
⏳ **运行时测试**: 需要在实际环境中测试
⏳ **迁移测试**: 需要使用真实数据测试迁移
## 下一步计划
### 短期目标
1. 在开发环境中测试DAO层功能
2. 完善错误处理和边界情况
3. 添加更多单元测试
4. 性能优化和监控
### 中期目标
1. 集成到现有业务逻辑中
2. 提供Web界面的DAO层管理
3. 添加数据备份和恢复功能
4. 实现配置版本控制
### 长期目标
1. 实现数据库后端支持
2. 添加分布式配置管理
3. 实现实时配置同步
4. 支持配置审计和日志
## 优势总结
通过引入DAO层，MCPHub获得了以下优势：
1. **🏗️ 架构清晰**: 数据访问逻辑与业务逻辑分离
2. **🔄 易于扩展**: 为未来数据库支持做好准备
3. **🧪 便于测试**: 接口可以轻松模拟和单元测试
4. **🔒 类型安全**: 完整的TypeScript类型支持
5. **⚡ 性能优化**: 内置缓存和批量操作
6. **🛡️ 数据完整性**: 强制数据验证和约束
7. **📦 模块化**: 每种数据类型独立管理
8. **🔧 可维护性**: 代码结构清晰，易于维护
这个DAO层的实现为MCPHub项目提供了坚实的数据管理基础，支持项目的长期发展和扩展需求。

254
docs/dao-layer.md
View File

@@ -1,254 +0,0 @@
# MCPHub DAO Layer 设计文档
## 概述
MCPHub的数据访问对象(DAO)层为项目中`mcp_settings.json`文件中的不同数据类型提供了统一的增删改查操作接口。这个设计使得未来从JSON文件存储切换到数据库存储变得更加容易。
## 架构设计
### 核心组件
```
src/dao/
├── base/
│ ├── BaseDao.ts # 基础DAO接口和抽象实现
│ └── JsonFileBaseDao.ts # JSON文件操作的基础类
├── UserDao.ts # 用户数据访问对象
├── ServerDao.ts # 服务器配置数据访问对象
├── GroupDao.ts # 群组数据访问对象
├── SystemConfigDao.ts # 系统配置数据访问对象
├── UserConfigDao.ts # 用户配置数据访问对象
├── DaoFactory.ts # DAO工厂类
├── examples.ts # 使用示例
└── index.ts # 统一导出
```
### 数据类型映射
| 数据类型 | 原始位置 | DAO类 | 主要功能 |
|---------|---------|-------|---------|
| IUser | `settings.users[]` | UserDao | 用户管理、密码验证、权限控制 |
| ServerConfig | `settings.mcpServers{}` | ServerDao | 服务器配置、启用/禁用、工具管理 |
| IGroup | `settings.groups[]` | GroupDao | 群组管理、服务器分组、成员管理 |
| SystemConfig | `settings.systemConfig` | SystemConfigDao | 系统级配置、路由设置、安装配置 |
| UserConfig | `settings.userConfigs{}` | UserConfigDao | 用户个人配置 |
## 主要特性
### 1. 统一的CRUD接口
所有DAO都实现了基础的CRUD操作：
```typescript
interface BaseDao<T, K = string> {
findAll(): Promise<T[]>;
findById(id: K): Promise<T | null>;
create(entity: Omit<T, 'id'>): Promise<T>;
update(id: K, entity: Partial<T>): Promise<T | null>;
delete(id: K): Promise<boolean>;
exists(id: K): Promise<boolean>;
count(): Promise<number>;
}
```
### 2. 特定业务操作
每个DAO还提供了针对其数据类型的特定操作：
#### UserDao 特殊功能
- `createWithHashedPassword()` - 创建用户时自动哈希密码
- `validateCredentials()` - 验证用户凭据
- `updatePassword()` - 更新用户密码
- `findAdmins()` - 查找管理员用户
#### ServerDao 特殊功能
- `findByOwner()` - 按所有者查找服务器
- `findEnabled()` - 查找启用的服务器
- `findByType()` - 按类型查找服务器
- `setEnabled()` - 启用/禁用服务器
- `updateTools()` - 更新服务器工具配置
#### GroupDao 特殊功能
- `findByOwner()` - 按所有者查找群组
- `findByServer()` - 查找包含特定服务器的群组
- `addServerToGroup()` - 向群组添加服务器
- `removeServerFromGroup()` - 从群组移除服务器
- `findByName()` - 按名称查找群组
### 3. 配置管理特殊功能
#### SystemConfigDao
- `getSection()` - 获取特定配置段
- `updateSection()` - 更新特定配置段
- `reset()` - 重置为默认配置
#### UserConfigDao
- `getSection()` - 获取用户特定配置段
- `updateSection()` - 更新用户特定配置段
- `getAll()` - 获取所有用户配置
## 使用方法
### 1. 基本使用
```typescript
import { getUserDao, getServerDao, getGroupDao } from './dao/index.js';
// 用户操作
const userDao = getUserDao();
const newUser = await userDao.createWithHashedPassword('username', 'password', false);
const user = await userDao.findByUsername('username');
const isValid = await userDao.validateCredentials('username', 'password');
// 服务器操作
const serverDao = getServerDao();
const server = await serverDao.create({
name: 'my-server',
command: 'node',
args: ['server.js'],
enabled: true
});
// 群组操作
const groupDao = getGroupDao();
const group = await groupDao.create({
name: 'my-group',
description: 'Test group',
servers: ['my-server']
});
```
### 2. 配置服务集成
```typescript
import { DaoConfigService, createDaoConfigService } from './config/DaoConfigService.js';
const daoService = createDaoConfigService();
// 加载完整配置
const settings = await daoService.loadSettings();
// 保存配置
await daoService.saveSettings(updatedSettings);
```
### 3. 迁移管理
```typescript
import { migrateToDao, switchToDao, switchToLegacy } from './config/configManager.js';
// 迁移到DAO层
const success = await migrateToDao();
// 运行时切换
switchToDao(); // 切换到DAO层
switchToLegacy(); // 切换回传统方式
```
## 配置选项
可以通过环境变量控制使用哪种数据访问方式：
```bash
# 使用DAO层 (推荐)
USE_DAO_LAYER=true
# 使用传统文件方式 (默认，向后兼容)
USE_DAO_LAYER=false
```
## 未来扩展
### 数据库支持
DAO层的设计使得切换到数据库变得容易，只需要：
1. 实现新的DAO实现类（如DatabaseUserDao）
2. 创建新的DaoFactory
3. 更新配置以使用新的工厂
```typescript
// 未来的数据库实现示例
class DatabaseUserDao implements UserDao {
constructor(private db: Database) {}
async findAll(): Promise<IUser[]> {
return this.db.query('SELECT * FROM users');
}
// ... 其他方法
}
```
### 新数据类型
添加新数据类型只需要：
1. 定义数据接口
2. 创建对应的DAO接口和实现
3. 更新DaoFactory
4. 更新配置服务
## 迁移指南
### 从传统方式迁移到DAO层
1. **备份数据**
```bash
cp mcp_settings.json mcp_settings.json.backup
```
2. **运行迁移**
```typescript
import { performMigration } from './config/migrationUtils.js';
await performMigration();
```
3. **验证迁移**
```typescript
import { validateMigration } from './config/migrationUtils.js';
const isValid = await validateMigration();
```
4. **切换到DAO层**
```bash
export USE_DAO_LAYER=true
```
### 性能对比
可以使用内置工具对比性能：
```typescript
import { performanceComparison } from './config/migrationUtils.js';
await performanceComparison();
```
## 最佳实践
1. **类型安全**: 始终使用TypeScript接口确保类型安全
2. **错误处理**: 在DAO操作周围实现适当的错误处理
3. **事务**: 对于复杂操作，考虑使用事务（未来数据库实现）
4. **缓存**: DAO层包含内置缓存机制
5. **测试**: 使用DAO接口进行单元测试的模拟
## 示例代码
查看以下文件获取完整示例：
- `src/dao/examples.ts` - 基本DAO操作示例
- `src/config/migrationUtils.ts` - 迁移和验证工具
- `src/scripts/dao-demo.ts` - 交互式演示脚本
## 总结
DAO层为MCPHub提供了：
- 🏗️ **模块化设计**: 每种数据类型都有专门的访问层
- 🔄 **易于迁移**: 为未来切换到数据库做好准备
- 🧪 **可测试性**: 接口可以轻松模拟和测试
- 🔒 **类型安全**: 完整的TypeScript类型支持
- ⚡ **性能优化**: 内置缓存和批量操作支持
- 🛡️ **数据完整性**: 强制数据验证和约束
通过引入DAO层，MCPHub的数据管理变得更加结构化、可维护和可扩展。

267
docs/environment-variables.md
View File

@@ -1,267 +0,0 @@
# Environment Variable Expansion in mcp_settings.json
## Overview
MCPHub now supports comprehensive environment variable expansion throughout the entire `mcp_settings.json` configuration file. This allows you to externalize sensitive information and configuration values, making your setup more secure and flexible.
## Supported Formats
MCPHub supports two environment variable formats:
1. **${VAR}** - Standard format (recommended)
2. **$VAR** - Unix-style format (variable name must start with an uppercase letter or underscore, followed by uppercase letters, numbers, or underscores)
## What Can Be Expanded
Environment variables can now be used in **ANY** string value throughout your configuration:
- Server URLs
- Commands and arguments
- Headers
- Environment variables passed to child processes
- OpenAPI specifications and security configurations
- OAuth credentials
- System configuration values
- Any other string fields
## Examples
### 1. SSE/HTTP Server Configuration
```json
{
"mcpServers": {
"my-api-server": {
"type": "sse",
"url": "${MCP_SERVER_URL}",
"headers": {
"Authorization": "Bearer ${API_TOKEN}",
"X-Custom-Header": "${CUSTOM_VALUE}"
}
}
}
}
```
Environment variables:
```bash
export MCP_SERVER_URL="https://api.example.com/mcp"
export API_TOKEN="secret-token-123"
export CUSTOM_VALUE="my-custom-value"
```
### 2. Stdio Server Configuration
```json
{
"mcpServers": {
"my-python-server": {
"type": "stdio",
"command": "${PYTHON_PATH}",
"args": ["-m", "${MODULE_NAME}", "--api-key", "${API_KEY}"],
"env": {
"DATABASE_URL": "${DATABASE_URL}",
"DEBUG": "${DEBUG_MODE}"
}
}
}
}
```
Environment variables:
```bash
export PYTHON_PATH="/usr/bin/python3"
export MODULE_NAME="my_mcp_server"
export API_KEY="secret-api-key"
export DATABASE_URL="postgresql://localhost/mydb"
export DEBUG_MODE="true"
```
### 3. OpenAPI Server Configuration
```json
{
"mcpServers": {
"openapi-service": {
"type": "openapi",
"openapi": {
"url": "${OPENAPI_SPEC_URL}",
"security": {
"type": "apiKey",
"apiKey": {
"name": "X-API-Key",
"in": "header",
"value": "${OPENAPI_API_KEY}"
}
}
}
}
}
}
```
Environment variables:
```bash
export OPENAPI_SPEC_URL="https://api.example.com/openapi.json"
export OPENAPI_API_KEY="your-api-key-here"
```
### 4. OAuth Configuration
```json
{
"mcpServers": {
"oauth-server": {
"type": "sse",
"url": "${OAUTH_SERVER_URL}",
"oauth": {
"clientId": "${OAUTH_CLIENT_ID}",
"clientSecret": "${OAUTH_CLIENT_SECRET}",
"accessToken": "${OAUTH_ACCESS_TOKEN}"
}
}
}
}
```
Environment variables:
```bash
export OAUTH_SERVER_URL="https://oauth.example.com/mcp"
export OAUTH_CLIENT_ID="my-client-id"
export OAUTH_CLIENT_SECRET="my-client-secret"
export OAUTH_ACCESS_TOKEN="my-access-token"
```
### 5. System Configuration
```json
{
"systemConfig": {
"install": {
"pythonIndexUrl": "${PYTHON_INDEX_URL}",
"npmRegistry": "${NPM_REGISTRY}"
},
"mcpRouter": {
"apiKey": "${MCPROUTER_API_KEY}",
"referer": "${MCPROUTER_REFERER}"
}
}
}
```
Environment variables:
```bash
export PYTHON_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
export NPM_REGISTRY="https://registry.npmmirror.com"
export MCPROUTER_API_KEY="router-api-key"
export MCPROUTER_REFERER="https://myapp.com"
```
## Complete Example
See [examples/mcp_settings_with_env_vars.json](../examples/mcp_settings_with_env_vars.json) for a comprehensive example configuration using environment variables.
## Best Practices
### Security
1. **Never commit sensitive values to version control** - Use environment variables for all secrets
2. **Use .env files for local development** - MCPHub automatically loads `.env` files
3. **Use secure secret management in production** - Consider using Docker secrets, Kubernetes secrets, or cloud provider secret managers
### Organization
1. **Group related variables** - Use prefixes for related configuration (e.g., `API_`, `DB_`, `OAUTH_`)
2. **Document required variables** - Maintain a list of required environment variables in your README
3. **Provide example .env file** - Create a `.env.example` file with placeholder values
### Example .env File
```bash
# Server Configuration
MCP_SERVER_URL=https://api.example.com/mcp
API_TOKEN=your-api-token-here
# Python Server
PYTHON_PATH=/usr/bin/python3
MODULE_NAME=my_mcp_server
# Database
DATABASE_URL=postgresql://localhost/mydb
# OpenAPI
OPENAPI_SPEC_URL=https://api.example.com/openapi.json
OPENAPI_API_KEY=your-openapi-key
# OAuth
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_ACCESS_TOKEN=your-access-token
```
## Docker Usage
When using Docker, pass environment variables using `-e` flag or `--env-file`:
```bash
# Using individual variables
docker run -e API_TOKEN=secret -e SERVER_URL=https://api.example.com mcphub
# Using env file
docker run --env-file .env mcphub
```
Or in docker-compose.yml:
```yaml
version: '3.8'
services:
mcphub:
image: mcphub
env_file:
- .env
environment:
- MCP_SERVER_URL=${MCP_SERVER_URL}
- API_TOKEN=${API_TOKEN}
```
## Troubleshooting
### Variable Not Expanding
If a variable is not expanding:
1. Check that the variable is set: `echo $VAR_NAME`
2. Verify the variable name matches exactly (case-sensitive)
3. Ensure the variable is exported: `export VAR_NAME=value`
4. Restart MCPHub after setting environment variables
### Empty Values
If an environment variable is not set, it will be replaced with an empty string. Make sure all required variables are set before starting MCPHub.
### Nested Variables
Environment variables in nested objects and arrays are fully supported:
```json
{
"nested": {
"deep": {
"value": "${MY_VAR}"
}
},
"array": ["${VAR1}", "${VAR2}"]
}
```
## Migration from Previous Version
If you were previously using environment variables only in headers, no changes are needed. The new implementation is backward compatible and simply extends support to all configuration fields.
## Technical Details
- Environment variables are expanded once when the configuration is loaded
- Expansion is recursive and handles nested objects and arrays
- Non-string values (booleans, numbers, null) are preserved as-is
- Empty string is used when an environment variable is not set

169
docs/oauth-dynamic-registration-implementation.md
View File

@@ -1,169 +0,0 @@
# OAuth 动态客户端注册实现总结
## 概述
成功为 MCPHub 的 OAuth 2.0 授权服务器添加了 RFC 7591 标准的动态客户端注册功能。此功能允许 OAuth 客户端在运行时自动注册，无需管理员手动配置。
## 实现的功能
### 1. 核心端点
#### POST /oauth/register - 注册新客户端
- 公开端点，支持动态客户端注册
- 自动生成 client_id 和可选的 client_secret
- 返回 registration_access_token 用于后续管理
- 支持 PKCE 流程（token_endpoint_auth_method: "none"）
#### GET /oauth/register/:clientId - 读取客户端配置
- 需要 registration_access_token 认证
- 返回完整的客户端元数据
#### PUT /oauth/register/:clientId - 更新客户端配置
- 需要 registration_access_token 认证
- 支持更新 redirect_uris、scopes、metadata 等
#### DELETE /oauth/register/:clientId - 删除客户端注册
- 需要 registration_access_token 认证
- 删除客户端并清理相关 tokens
### 2. 配置选项
在 `mcp_settings.json` 中添加：
```json
{
"systemConfig": {
"oauthServer": {
"enabled": true,
"dynamicRegistration": {
"enabled": true,
"allowedGrantTypes": ["authorization_code", "refresh_token"],
"requiresAuthentication": false
}
}
}
}
```
### 3. 客户端元数据支持
实现了 RFC 7591 定义的完整客户端元数据：
- `application_type`: "web" 或 "native"
- `response_types`: OAuth 响应类型数组
- `token_endpoint_auth_method`: 认证方法
- `contacts`: 联系邮箱数组
- `logo_uri`: 客户端 logo URL
- `client_uri`: 客户端主页 URL
- `policy_uri`: 隐私政策 URL
- `tos_uri`: 服务条款 URL
- `jwks_uri`: JSON Web Key Set URL
- `jwks`: 内联 JSON Web Key Set
### 4. 安全特性
- **Registration Access Token**: 每个注册的客户端获得唯一的访问令牌
- **Token 过期**: Registration tokens 30 天后过期
- **HTTPS 验证**: Redirect URIs 必须使用 HTTPS（localhost 除外）
- **Scope 验证**: 只允许配置中定义的 scopes
- **Grant Type 限制**: 只允许配置中定义的 grant types
## 文件变更
### 新增文件
1. `src/controllers/oauthDynamicRegistrationController.ts` - 动态注册控制器
2. `examples/oauth-dynamic-registration-config.json` - 配置示例
### 修改文件
1. `src/types/index.ts` - 添加元数据字段到 IOAuthClient 和 OAuthServerConfig
2. `src/routes/index.ts` - 注册新的动态注册端点
3. `src/controllers/oauthServerController.ts` - 元数据端点包含 registration_endpoint
4. `docs/oauth-server.md` - 添加完整的动态注册文档
## 使用示例
### 注册新客户端
```bash
curl -X POST http://localhost:3000/oauth/register \
-H "Content-Type: application/json" \
-d '{
"client_name": "My Application",
"redirect_uris": ["https://example.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"scope": "read write",
"token_endpoint_auth_method": "none",
"logo_uri": "https://example.com/logo.png",
"client_uri": "https://example.com",
"contacts": ["admin@example.com"]
}'
```
响应：
```json
{
"client_id": "a1b2c3d4e5f6g7h8",
"client_name": "My Application",
"redirect_uris": ["https://example.com/callback"],
"registration_access_token": "reg_token_xyz123",
"registration_client_uri": "http://localhost:3000/oauth/register/a1b2c3d4e5f6g7h8",
"client_id_issued_at": 1699200000
}
```
### 读取客户端配置
```bash
curl http://localhost:3000/oauth/register/CLIENT_ID \
-H "Authorization: Bearer REGISTRATION_ACCESS_TOKEN"
```
### 更新客户端
```bash
curl -X PUT http://localhost:3000/oauth/register/CLIENT_ID \
-H "Authorization: Bearer REGISTRATION_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"client_name": "Updated Name",
"redirect_uris": ["https://example.com/callback", "https://example.com/callback2"]
}'
```
### 删除客户端
```bash
curl -X DELETE http://localhost:3000/oauth/register/CLIENT_ID \
-H "Authorization: Bearer REGISTRATION_ACCESS_TOKEN"
```
## 测试结果
✅ 所有 180 个测试通过
✅ TypeScript 编译成功
✅ 代码覆盖率维持在合理水平
✅ 与现有功能完全兼容
## RFC 合规性
完全遵循以下 RFC 标准：
- **RFC 7591**: OAuth 2.0 Dynamic Client Registration Protocol
- **RFC 8414**: OAuth 2.0 Authorization Server Metadata
- **RFC 7636**: Proof Key for Code Exchange (PKCE)
- **RFC 9728**: OAuth 2.0 Protected Resource Metadata
## 下一步建议
1. **持久化存储**: 当前 registration tokens 存储在内存中，生产环境应使用数据库
2. **速率限制**: 添加注册端点的速率限制以防止滥用
3. **客户端证明**: 考虑添加软件声明（software_statement）支持
4. **审计日志**: 记录所有注册、更新和删除操作
5. **通知机制**: 在客户端注册时通知管理员（可选）
## 兼容性
- 与 ChatGPT Web 完全兼容
- 支持所有标准 OAuth 2.0 客户端库
- 向后兼容现有的手动客户端配置方式

538
docs/oauth-server.md
View File

@@ -1,538 +0,0 @@
# OAuth 2.0 Authorization Server
MCPHub can act as an OAuth 2.0 authorization server, allowing external applications like ChatGPT Web to securely authenticate and access your MCP servers.
## Overview
The OAuth 2.0 authorization server feature enables MCPHub to:
- Provide standard OAuth 2.0 authentication flows
- Issue and manage access tokens for external clients
- Support secure authorization without exposing user credentials
- Enable integration with services that require OAuth (like ChatGPT Web)
## Configuration
### Enable OAuth Server
Add the following configuration to your `mcp_settings.json`:
```json
{
"systemConfig": {
"oauthServer": {
"enabled": true,
"accessTokenLifetime": 3600,
"refreshTokenLifetime": 1209600,
"authorizationCodeLifetime": 300,
"requireClientSecret": false,
"allowedScopes": ["read", "write"],
"requireState": false
}
}
}
```
### Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable/disable OAuth authorization server |
| `accessTokenLifetime` | number | `3600` | Access token lifetime in seconds (1 hour) |
| `refreshTokenLifetime` | number | `1209600` | Refresh token lifetime in seconds (14 days) |
| `authorizationCodeLifetime` | number | `300` | Authorization code lifetime in seconds (5 minutes) |
| `requireClientSecret` | boolean | `false` | Whether client secret is required (set to false for PKCE) |
| `allowedScopes` | string[] | `["read", "write"]` | List of allowed OAuth scopes |
| `requireState` | boolean | `false` | When `true`, rejects authorization requests that omit the `state` parameter |
## OAuth Clients
### Creating OAuth Clients
#### Via API (Recommended)
Create an OAuth client using the API:
```bash
curl -X POST http://localhost:3000/api/oauth/clients \
-H "Content-Type: application/json" \
-H "x-auth-token: YOUR_JWT_TOKEN" \
-d '{
"name": "My Application",
"redirectUris": ["https://example.com/callback"],
"grants": ["authorization_code", "refresh_token"],
"scopes": ["read", "write"],
"requireSecret": false
}'
```
Response:
```json
{
"success": true,
"message": "OAuth client created successfully",
"client": {
"clientId": "a1b2c3d4e5f6g7h8",
"clientSecret": null,
"name": "My Application",
"redirectUris": ["https://example.com/callback"],
"grants": ["authorization_code", "refresh_token"],
"scopes": ["read", "write"],
"owner": "admin"
}
}
```
**Important**: If `requireSecret` is true, the `clientSecret` will be shown only once. Save it securely!
#### Via Configuration File
Alternatively, add OAuth clients directly to `mcp_settings.json`:
```json
{
"oauthClients": [
{
"clientId": "my-app-client",
"clientSecret": "optional-secret-for-confidential-clients",
"name": "My Application",
"redirectUris": ["https://example.com/callback"],
"grants": ["authorization_code", "refresh_token"],
"scopes": ["read", "write"],
"owner": "admin"
}
]
}
```
### Managing OAuth Clients
#### List All Clients
```bash
curl http://localhost:3000/api/oauth/clients \
-H "x-auth-token: YOUR_JWT_TOKEN"
```
#### Get Specific Client
```bash
curl http://localhost:3000/api/oauth/clients/CLIENT_ID \
-H "x-auth-token: YOUR_JWT_TOKEN"
```
#### Update Client
```bash
curl -X PUT http://localhost:3000/api/oauth/clients/CLIENT_ID \
-H "Content-Type: application/json" \
-H "x-auth-token: YOUR_JWT_TOKEN" \
-d '{
"name": "Updated Name",
"redirectUris": ["https://example.com/callback", "https://example.com/callback2"]
}'
```
#### Delete Client
```bash
curl -X DELETE http://localhost:3000/api/oauth/clients/CLIENT_ID \
-H "x-auth-token: YOUR_JWT_TOKEN"
```
#### Regenerate Client Secret
```bash
curl -X POST http://localhost:3000/api/oauth/clients/CLIENT_ID/regenerate-secret \
-H "x-auth-token: YOUR_JWT_TOKEN"
```
## OAuth Flow
MCPHub supports the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange).
### 1. Authorization Request
The client application redirects the user to the authorization endpoint:
```
GET /oauth/authorize?
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
response_type=code&
scope=read%20write&
state=RANDOM_STATE&
code_challenge=CODE_CHALLENGE&
code_challenge_method=S256
```
Parameters:
- `client_id`: OAuth client ID
- `redirect_uri`: Redirect URI (must match registered URI)
- `response_type`: Must be `code`
- `scope`: Space-separated list of scopes (e.g., `read write`)
- `state`: Random string to prevent CSRF attacks
- `code_challenge`: PKCE code challenge (optional but recommended)
- `code_challenge_method`: PKCE method (`S256` or `plain`)
### 2. User Authorization
The user is presented with a consent page showing:
- Application name
- Requested scopes
- Approve/Deny buttons
If the user approves, they are redirected to the redirect URI with an authorization code:
```
https://example.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE
```
### 3. Token Exchange
The client exchanges the authorization code for an access token:
```bash
curl -X POST http://localhost:3000/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AUTHORIZATION_CODE" \
-d "redirect_uri=REDIRECT_URI" \
-d "client_id=CLIENT_ID" \
-d "code_verifier=CODE_VERIFIER"
```
Response:
```json
{
"access_token": "ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "REFRESH_TOKEN",
"scope": "read write"
}
```
### 4. Using Access Token
Use the access token to make authenticated requests:
```bash
curl http://localhost:3000/api/servers \
-H "Authorization: Bearer ACCESS_TOKEN"
```
### 5. Refreshing Token
When the access token expires, use the refresh token to get a new one:
```bash
curl -X POST http://localhost:3000/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=REFRESH_TOKEN" \
-d "client_id=CLIENT_ID"
```
## PKCE (Proof Key for Code Exchange)
PKCE is a security extension to OAuth 2.0 that prevents authorization code interception attacks. It's especially important for public clients (mobile apps, SPAs).
### Generating PKCE Parameters
1. Generate a code verifier (random string):
```javascript
const codeVerifier = crypto.randomBytes(32).toString('base64url');
```
2. Generate code challenge from verifier:
```javascript
const codeChallenge = crypto
.createHash('sha256')
.update(codeVerifier)
.digest('base64url');
```
3. Include in authorization request:
- `code_challenge`: The generated challenge
- `code_challenge_method`: `S256`
4. Include in token request:
- `code_verifier`: The original verifier
## OAuth Scopes
MCPHub supports the following default scopes:
| Scope | Description |
|-------|-------------|
| `read` | Read access to MCP servers and tools |
| `write` | Execute tools and modify MCP server configurations |
You can customize allowed scopes in the `oauthServer.allowedScopes` configuration.
## Dynamic Client Registration (RFC 7591)
MCPHub supports RFC 7591 Dynamic Client Registration, allowing OAuth clients to register themselves programmatically without manual configuration.
### Enable Dynamic Registration
Add to your `mcp_settings.json`:
```json
{
"systemConfig": {
"oauthServer": {
"enabled": true,
"dynamicRegistration": {
"enabled": true,
"allowedGrantTypes": ["authorization_code", "refresh_token"],
"requiresAuthentication": false
}
}
}
}
```
### Register a New Client
**POST /oauth/register**
```bash
curl -X POST http://localhost:3000/oauth/register \
-H "Content-Type: application/json" \
-d '{
"client_name": "My Application",
"redirect_uris": ["https://example.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"scope": "read write",
"token_endpoint_auth_method": "none"
}'
```
Response:
```json
{
"client_id": "a1b2c3d4e5f6g7h8",
"client_name": "My Application",
"redirect_uris": ["https://example.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"scope": "read write",
"token_endpoint_auth_method": "none",
"registration_access_token": "reg_token_xyz123",
"registration_client_uri": "http://localhost:3000/oauth/register/a1b2c3d4e5f6g7h8",
"client_id_issued_at": 1699200000
}
```
**Important:** Save the `registration_access_token` - it's required to read, update, or delete the client registration.
### Read Client Configuration
**GET /oauth/register/:clientId**
```bash
curl http://localhost:3000/oauth/register/CLIENT_ID \
-H "Authorization: Bearer REGISTRATION_ACCESS_TOKEN"
```
### Update Client Configuration
**PUT /oauth/register/:clientId**
```bash
curl -X PUT http://localhost:3000/oauth/register/CLIENT_ID \
-H "Authorization: Bearer REGISTRATION_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"client_name": "Updated Application Name",
"redirect_uris": ["https://example.com/callback", "https://example.com/callback2"]
}'
```
### Delete Client Registration
**DELETE /oauth/register/:clientId**
```bash
curl -X DELETE http://localhost:3000/oauth/register/CLIENT_ID \
-H "Authorization: Bearer REGISTRATION_ACCESS_TOKEN"
```
### Optional Client Metadata
When registering a client, you can include additional metadata:
- `application_type`: `"web"` or `"native"` (default: `"web"`)
- `contacts`: Array of email addresses
- `logo_uri`: URL of client logo
- `client_uri`: URL of client homepage
- `policy_uri`: URL of privacy policy
- `tos_uri`: URL of terms of service
- `jwks_uri`: URL of JSON Web Key Set
- `jwks`: Inline JSON Web Key Set
Example:
```json
{
"client_name": "My Application",
"redirect_uris": ["https://example.com/callback"],
"application_type": "web",
"contacts": ["admin@example.com"],
"logo_uri": "https://example.com/logo.png",
"client_uri": "https://example.com",
"policy_uri": "https://example.com/privacy",
"tos_uri": "https://example.com/terms"
}
```
## Server Metadata
MCPHub provides OAuth 2.0 Authorization Server Metadata (RFC 8414) at:
```
GET /.well-known/oauth-authorization-server
```
Response (with dynamic registration enabled):
```json
{
"issuer": "http://localhost:3000",
"authorization_endpoint": "http://localhost:3000/oauth/authorize",
"token_endpoint": "http://localhost:3000/oauth/token",
"userinfo_endpoint": "http://localhost:3000/oauth/userinfo",
"registration_endpoint": "http://localhost:3000/oauth/register",
"scopes_supported": ["read", "write"],
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
"code_challenge_methods_supported": ["S256", "plain"]
}
```
## User Info Endpoint
Get authenticated user information (OpenID Connect compatible):
```bash
curl http://localhost:3000/oauth/userinfo \
-H "Authorization: Bearer ACCESS_TOKEN"
```
Response:
```json
{
"sub": "username",
"username": "username"
}
```
## Integration with ChatGPT Web
To integrate MCPHub with ChatGPT Web:
1. Enable OAuth server in MCPHub configuration
2. Create an OAuth client with ChatGPT's redirect URI
3. Configure ChatGPT Web MCP Connector:
- **MCP Server URL**: `http://your-mcphub-url/mcp`
- **Authentication**: OAuth
- **OAuth Client ID**: Your client ID
- **OAuth Client Secret**: Leave empty (PKCE flow)
- **Authorization URL**: `http://your-mcphub-url/oauth/authorize`
- **Token URL**: `http://your-mcphub-url/oauth/token`
- **Scopes**: `read write`
## Security Considerations
1. **HTTPS in Production**: Always use HTTPS in production to protect tokens in transit
2. **Secure Client Secrets**: If using confidential clients, store client secrets securely
3. **Token Storage**: Access tokens are stored in memory by default. For production, consider using a database
4. **Token Rotation**: Implement token rotation by using refresh tokens
5. **Scope Limitation**: Grant only necessary scopes to clients
6. **Redirect URI Validation**: Always validate redirect URIs strictly
7. **State Parameter**: Always use the state parameter to prevent CSRF attacks
8. **PKCE**: Use PKCE for public clients (strongly recommended)
9. **Rate Limiting**: For production deployments, implement rate limiting on OAuth endpoints to prevent brute force attacks. Consider using middleware like `express-rate-limit`
10. **Input Validation**: All OAuth parameters are validated, but additional application-level validation may be beneficial
11. **XSS Protection**: The authorization page escapes all user input to prevent XSS attacks
## Troubleshooting
### "OAuth server not available"
Make sure `oauthServer.enabled` is set to `true` in your configuration and restart MCPHub.
### "Invalid redirect_uri"
Ensure the redirect URI in the authorization request exactly matches one of the registered redirect URIs for the client.
### "Invalid client"
Verify the client ID is correct and the OAuth client exists in the configuration.
### Token expired
Use the refresh token to obtain a new access token, or re-authorize the application.
## Example: JavaScript Client
```javascript
// Generate PKCE parameters
const codeVerifier = crypto.randomBytes(32).toString('base64url');
const codeChallenge = crypto
.createHash('sha256')
.update(codeVerifier)
.digest('base64url');
// Store code verifier for later use
sessionStorage.setItem('codeVerifier', codeVerifier);
// Redirect to authorization endpoint
const authUrl = new URL('http://localhost:3000/oauth/authorize');
authUrl.searchParams.set('client_id', 'my-client-id');
authUrl.searchParams.set('redirect_uri', 'http://localhost:8080/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'read write');
authUrl.searchParams.set('state', crypto.randomBytes(16).toString('hex'));
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authUrl.toString();
// In callback handler:
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const codeVerifier = sessionStorage.getItem('codeVerifier');
// Exchange code for token
const tokenResponse = await fetch('http://localhost:3000/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'authorization_code',
code: code,
redirect_uri: 'http://localhost:8080/callback',
client_id: 'my-client-id',
code_verifier: codeVerifier,
}),
});
const tokens = await tokenResponse.json();
// Store tokens securely
localStorage.setItem('accessToken', tokens.access_token);
localStorage.setItem('refreshToken', tokens.refresh_token);
// Use access token
const response = await fetch('http://localhost:3000/api/servers', {
headers: { Authorization: `Bearer ${tokens.access_token}` },
});
```
## References
- [OAuth 2.0 - RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)
- [OAuth 2.0 Authorization Server Metadata - RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)
- [PKCE - RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
- [OAuth 2.0 for Browser-Based Apps](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps)

209
docs/openapi-schema-support.md
View File

@@ -1,209 +0,0 @@
# OpenAPI Schema Support in MCPHub
MCPHub now supports both OpenAPI specification URLs and complete JSON schemas for OpenAPI server configuration. This allows you to either reference an external OpenAPI specification file or embed the complete schema directly in your configuration.
## Configuration Options
### 1. Using OpenAPI Specification URL (Traditional)
```json
{
"type": "openapi",
"openapi": {
"url": "https://api.example.com/openapi.json",
"version": "3.1.0",
"security": {
"type": "apiKey",
"apiKey": {
"name": "X-API-Key",
"in": "header",
"value": "your-api-key"
}
}
}
}
```
### 2. Using Complete JSON Schema (New)
```json
{
"type": "openapi",
"openapi": {
"schema": {
"openapi": "3.1.0",
"info": {
"title": "My API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.example.com"
}
],
"paths": {
"/users": {
"get": {
"operationId": "getUsers",
"summary": "Get all users",
"responses": {
"200": {
"description": "List of users"
}
}
}
}
}
},
"version": "3.1.0",
"security": {
"type": "apiKey",
"apiKey": {
"name": "X-API-Key",
"in": "header",
"value": "your-api-key"
}
}
}
}
```
## Benefits of JSON Schema Support
1. **Offline Development**: No need for external URLs during development
2. **Version Control**: Schema changes can be tracked in your configuration
3. **Security**: No external dependencies or network calls required
4. **Customization**: Full control over the API specification
5. **Testing**: Easy to create test configurations with mock schemas
## Frontend Form Support
The web interface now includes:
- **Input Mode Selection**: Choose between "Specification URL" or "JSON Schema"
- **URL Input**: Traditional URL input field for external specifications
- **Schema Editor**: Large text area with syntax highlighting for JSON schema input
- **Validation**: Client-side JSON validation before submission
- **Help Text**: Contextual help for schema format
## API Validation
The backend validates that:
- At least one of `url` or `schema` is provided for OpenAPI servers
- JSON schemas are properly formatted when provided
- Security configurations are valid for both input modes
- All required OpenAPI fields are present
## Migration Guide
### From URL to Schema
If you want to convert an existing URL-based configuration to schema-based:
1. Download your OpenAPI specification from the URL
2. Copy the JSON content
3. Update your configuration to use the `schema` field instead of `url`
4. Paste the JSON content as the value of the `schema` field
### Maintaining Both
You can include both `url` and `schema` in your configuration. The system will prioritize the `schema` field if both are present.
## Examples
See the `examples/openapi-schema-config.json` file for complete configuration examples showing both URL and schema-based configurations.
## Technical Implementation
- **Backend**: OpenAPI client supports both SwaggerParser.dereference() with URLs and direct schema objects
- **Frontend**: Dynamic form rendering based on selected input mode
- **Validation**: Enhanced validation logic in server controllers
- **Type Safety**: Updated TypeScript interfaces for both input modes
## Header Passthrough Support
MCPHub supports passing through specific headers from tool call requests to upstream OpenAPI endpoints. This is useful for authentication tokens, API keys, and other request-specific headers.
### Configuration
Add `passthroughHeaders` to your OpenAPI configuration:
```json
{
"type": "openapi",
"openapi": {
"url": "https://api.example.com/openapi.json",
"version": "3.1.0",
"passthroughHeaders": ["Authorization", "X-API-Key", "X-Custom-Header"],
"security": {
"type": "apiKey",
"apiKey": {
"name": "X-API-Key",
"in": "header",
"value": "your-api-key"
}
}
}
}
```
### How It Works
1. **Configuration**: List header names in the `passthroughHeaders` array
2. **Tool Calls**: When calling tools via HTTP API, include headers in the request
3. **Passthrough**: Only configured headers are forwarded to the upstream API
4. **Case Insensitive**: Header matching is case-insensitive for flexibility
### Example Usage
```bash
# Call an OpenAPI tool with passthrough headers
curl -X POST "http://localhost:3000/api/tools/myapi/createUser" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-H "X-API-Key: your-api-key" \
-H "X-Custom-Header: custom-value" \
-d '{"name": "John Doe", "email": "john@example.com"}'
```
In this example:
- If `passthroughHeaders` includes `["Authorization", "X-API-Key"]`
- Only `Authorization` and `X-API-Key` headers will be forwarded
- `X-Custom-Header` will be ignored (not in passthrough list)
- `Content-Type` is handled by the OpenAPI operation definition
### Security Considerations
- **Whitelist Only**: Only explicitly configured headers are passed through
- **Sensitive Data**: Be careful with headers containing sensitive information
- **Validation**: Upstream APIs should validate all received headers
- **Logging**: Headers may appear in logs - consider this for sensitive data
## Security Considerations
When using JSON schemas:
- Ensure schemas are properly validated before use
- Be aware that large schemas increase configuration file size
- Consider using URL-based approach for frequently changing APIs
- Store sensitive information (like API keys) in environment variables, not in schemas
## Troubleshooting
### Common Issues
1. **Invalid JSON**: Ensure your schema is valid JSON format
2. **Missing Required Fields**: OpenAPI schemas must include `openapi`, `info`, and `paths` fields
3. **Schema Size**: Very large schemas may impact performance
4. **Server Configuration**: Ensure the `servers` field in your schema points to the correct endpoints
### Validation Errors
The system provides detailed error messages for:
- Malformed JSON in schema field
- Missing required OpenAPI fields
- Invalid security configurations
- Network issues with URL-based configurations

172
docs/openapi-support.md
View File

@@ -1,172 +0,0 @@
# OpenAPI Support in MCPHub
MCPHub now supports OpenAPI 3.1.1 servers as a new server type, allowing you to integrate REST APIs directly into your MCP workflow.
## Features
- ✅ **Full OpenAPI 3.1.1 Support**: Load and parse OpenAPI specifications
- ✅ **Multiple Security Types**: None, API Key, HTTP Authentication, OAuth 2.0, OpenID Connect
- ✅ **Dynamic Tool Generation**: Automatically creates MCP tools from OpenAPI operations
- ✅ **Type Safety**: Full TypeScript support with proper type definitions
- ✅ **Frontend Integration**: Easy-to-use forms for configuring OpenAPI servers
- ✅ **Internationalization**: Support for English and Chinese languages
## Configuration
### Basic Configuration
```json
{
"type": "openapi",
"openapi": {
"url": "https://api.example.com/v1/openapi.json",
"version": "3.1.0",
"security": {
"type": "none"
}
}
}
```
### With API Key Authentication
```json
{
"type": "openapi",
"openapi": {
"url": "https://api.example.com/v1/openapi.json",
"version": "3.1.0",
"security": {
"type": "apiKey",
"apiKey": {
"name": "X-API-Key",
"in": "header",
"value": "your-api-key-here"
}
}
},
"headers": {
"Accept": "application/json"
}
}
```
### With HTTP Bearer Authentication
```json
{
"type": "openapi",
"openapi": {
"url": "https://api.example.com/v1/openapi.json",
"version": "3.1.0",
"security": {
"type": "http",
"http": {
"scheme": "bearer",
"credentials": "your-bearer-token-here"
}
}
}
}
```
## Supported Security Types
1. **None**: No authentication required
2. **API Key**: API key in header or query parameter
3. **HTTP**: Basic, Bearer, or Digest authentication
4. **OAuth 2.0**: OAuth 2.0 access tokens
5. **OpenID Connect**: OpenID Connect ID tokens
## How It Works
1. **Specification Loading**: The OpenAPI client fetches and parses the OpenAPI specification
2. **Tool Generation**: Each operation in the spec becomes an MCP tool
3. **Request Handling**: Tools handle parameter validation and API calls
4. **Response Processing**: API responses are returned as tool results
## Frontend Usage
1. Navigate to the Servers page
2. Click "Add Server"
3. Select "OpenAPI" as the server type
4. Enter the OpenAPI specification URL
5. Configure security settings if needed
6. Add any additional headers
7. Save the configuration
## Testing
You can test the OpenAPI integration using the provided test scripts:
```bash
# Test OpenAPI client directly
npx tsx test-openapi.ts
# Test full integration
npx tsx test-integration.ts
```
## Example: Swagger Petstore
The Swagger Petstore API is a perfect example for testing:
```json
{
"type": "openapi",
"openapi": {
"url": "https://petstore3.swagger.io/api/v3/openapi.json",
"version": "3.1.0",
"security": {
"type": "none"
}
}
}
```
This will create tools like:
- `addPet`: Add a new pet to the store
- `findPetsByStatus`: Find pets by status
- `getPetById`: Find pet by ID
- And many more...
## Error Handling
The OpenAPI client includes comprehensive error handling:
- Network errors are properly caught and reported
- Invalid specifications are rejected with clear error messages
- API errors include response status and body information
- Type validation ensures proper parameter handling
## Limitations
- Only supports OpenAPI 3.x specifications (3.0.0 and above)
- Complex authentication flows (like OAuth 2.0 authorization code flow) require manual token management
- Large specifications may take time to parse initially
- Some advanced OpenAPI features may not be fully supported
## Contributing
To add new features or fix bugs in the OpenAPI integration:
1. Backend types: `src/types/index.ts`
2. OpenAPI client: `src/clients/openapi.ts`
3. Service integration: `src/services/mcpService.ts`
4. Frontend forms: `frontend/src/components/ServerForm.tsx`
5. Internationalization: `frontend/src/locales/`
## Troubleshooting
**Q: My OpenAPI server won't connect**
A: Check that the specification URL is accessible and returns valid JSON/YAML
**Q: Tools aren't showing up**
A: Verify that your OpenAPI specification includes valid operations with required fields
**Q: Authentication isn't working**
A: Double-check your security configuration matches the API's requirements
**Q: Getting CORS errors**
A: The API server needs to allow CORS requests from your MCPHub domain

172
docs/testing-framework.md
View File

@@ -1,172 +0,0 @@
# 测试框架和自动化测试实现报告
## 概述
本项目已成功引入现代化的测试框架和自动化测试流程。实现了基于Jest的测试环境，支持TypeScript、ES模块，并包含完整的CI/CD配置。
## 已实现的功能
### 1. 测试框架配置
- **Jest配置**: 使用`jest.config.cjs`配置文件，支持ES模块和TypeScript
- **覆盖率报告**: 配置了代码覆盖率收集和报告
- **测试环境**: 支持Node.js环境的单元测试和集成测试
- **模块映射**: 配置了路径别名支持
### 2. 测试工具和辅助函数
创建了完善的测试工具库 (`tests/utils/testHelpers.ts`):
- **认证工具**: JWT token生成和管理
- **HTTP测试**: Supertest集成用于API测试
- **数据生成**: 测试数据工厂函数
- **响应断言**: 自定义API响应验证器
- **环境管理**: 测试环境变量配置
### 3. 测试用例实现
已实现的测试场景：
#### 基础配置测试 (`tests/basic.test.ts`)
- Jest配置验证
- 异步操作支持测试
- 自定义匹配器验证
#### 认证逻辑测试 (`tests/auth.logic.test.ts`)
- 用户登录逻辑
- 密码验证
- JWT生成和验证
- 错误处理场景
- 用户数据验证
#### 路径工具测试 (`tests/utils/pathLogic.test.ts`)
- 配置文件路径解析
- 环境变量处理
- 文件系统操作
- 错误处理和边界条件
- 跨平台路径处理
### 4. CI/CD配置
GitHub Actions配置 (`.github/workflows/ci.yml`):
- **多Node.js版本支持**: 18.x和20.x
- **自动化测试流程**:
- 代码检查 (ESLint)
- 类型检查 (TypeScript)
- 单元测试执行
- 覆盖率报告
- **构建验证**: 应用构建和产物验证
- **集成测试**: 包含数据库环境的集成测试
### 5. 测试脚本
在`package.json`中添加的测试命令：
```json
{
"test": "jest",
"test:watch": "jest --watch",
"test:coverage": "jest --coverage",
"test:verbose": "jest --verbose",
"test:ci": "jest --ci --coverage --watchAll=false"
}
```
## 测试结果
当前测试统计：
- **测试套件**: 3个
- **测试用例**: 19个
- **通过率**: 100%
- **执行时间**: ~15秒
### 测试覆盖的功能模块
1. **认证系统**: 用户登录、JWT处理、密码验证
2. **配置管理**: 文件路径解析、环境变量处理
3. **基础设施**: Jest配置、测试工具验证
## 技术特点
### 现代化特性
- **ES模块支持**: 完全支持ES2022模块语法
- **TypeScript集成**: 类型安全的测试编写
- **异步测试**: Promise和async/await支持
- **模拟系统**: Jest mock功能的深度使用
- **参数化测试**: 数据驱动的测试用例
### 最佳实践
- **测试隔离**: 每个测试用例独立运行
- **Mock管理**: 统一的mock清理和重置
- **错误处理**: 完整的错误场景测试
- **边界测试**: 输入验证和边界条件覆盖
- **文档化**: 清晰的测试用例命名和描述
## 后续扩展计划
### 短期目标
1. **API测试**: 为REST API端点添加集成测试
2. **数据库测试**: 添加数据模型和存储层测试
3. **中间件测试**: 认证和权限中间件测试
4. **服务层测试**: 核心业务逻辑测试
### 中期目标
1. **端到端测试**: 使用Playwright或Cypress
2. **性能测试**: API响应时间和负载测试
3. **安全测试**: 输入验证和安全漏洞测试
4. **契约测试**: API契约验证
### 长期目标
1. **测试数据管理**: 测试数据库和fixture管理
2. **视觉回归测试**: UI组件的视觉测试
3. **监控集成**: 生产环境测试监控
4. **自动化测试报告**: 详细的测试报告和趋势分析
## 开发指南
### 添加新测试用例
1. 在`tests/`目录下创建对应的测试文件
2. 使用`testHelpers.ts`中的工具函数
3. 遵循命名约定: `*.test.ts`或`*.spec.ts`
4. 确保测试用例具有清晰的描述和断言
### 运行测试
```bash
# 运行所有测试
pnpm test
# 监听模式
pnpm test:watch
# 生成覆盖率报告
pnpm test:coverage
# CI模式运行
pnpm test:ci
```
### Mock最佳实践
- 在`beforeEach`中清理所有mock
- 使用具体的mock实现而不是空函数
- 验证mock被正确调用
- 保持mock的一致性和可维护性
## 结论
本项目已成功建立了完整的现代化测试框架，具备以下优势：
1. **高度可扩展**: 易于添加新的测试用例和测试类型
2. **开发友好**: 丰富的工具函数和清晰的结构
3. **CI/CD就绪**: 完整的自动化流水线配置
4. **质量保证**: 代码覆盖率和持续测试验证
这个测试框架为项目的持续发展和质量保证提供了坚实的基础，支持敏捷开发和持续集成的最佳实践。

5
docs/zh/configuration/database-configuration.mdx
View File

@@ -1,3 +1,8 @@
---
title: '数据库配置'
description: '使用 PostgreSQL 数据库配置 MCPHub 作为 mcp_settings.json 文件的替代方案。'
---
# MCPHub 数据库配置 # MCPHub 数据库配置
## 概述 ## 概述

1
googled76ca578b6543fbc.html
View File

@@ -1 +0,0 @@
google-site-verification: googled76ca578b6543fbc.html