内容
# MCP HTTP 网关
[中文文档](README_CN.md)
基于MCP协议的HTTP网关服务，用于将LLM工具调用请求转发到HTTP REST接口。
---
## 双模式（双传输模式）
双模式同时启动STDIO和SSE传输模式，允许不同客户端同时连接：
- **Claude Code** 通过STDIO连接
- **VSCode / 其他工具** 通过SSE连接
### 启动命令
```bash
node dist/cli.cjs --transport=dual --sse-port=11114 --http-port=11115 --config=./tools.json
```
### 端口分配
| 模式 | SSE端口 | 控制台端口 | 描述 |
|------|----------|---------------|-------------|
| **dual** | `--sse-port`（默认11114） | `--http-port`（默认11115） | SSE + STDIO同时运行 |
| **sse** | `--sse-port`（默认11114） | SSE端口 - 1 | 仅SSE模式 |
| **stdio** | 无 | `--http-port`（默认11112） | 仅STDIO模式 |
### MCP配置（双模式）
```json
{
"mcpServers": {
"http-gateway": {
"type": "sse",
"url": "http://localhost:11114/sse",
"description": "HTTP API 网关（双模式）"
}
}
}
```
### 启动后访问URL
```
========================================
MCP HTTP 网关已启动
========================================
SSE连接： http://localhost:11114/sse
控制台： http://localhost:11115/dashboard
健康检查： http://localhost:11115/health
========================================
```
---
## 全局安全使用
### 配置优先级机制
配置优先级确保安全的配置管理：
```
命令行参数 > SQLite数据库 > 配置文件 > 默认值
```
**优先级说明**:
| 来源 | 描述 | 安全级别 |
|--------|-------------|--------|
| **命令行参数** | 通过命令行传递，优先级最高 | ✅ 最安全，不受配置文件影响 |
| **SQLite数据库** | 运行时持久化配置 | ✅ 安全，有审计记录 |
| **配置文件** | `tools.json`文件 | ⚠️ 需要文件权限控制 |
| **默认值** | 内置默认配置 | ⚠️ 仅作为备用 |
### 熔断器保护
防止级联故障，保护后端服务稳定性：
```json
{
"circuitBreaker": {
"enabled": true,
"failureThreshold": 5, // 连续5次失败后触发
"successThreshold": 2, // 连续2次成功后恢复
"halfOpenTime": 30000 // 30秒后尝试恢复
}
}
```
**状态流程**:
- `CLOSED` → 正常状态，请求正常转发
- `OPEN` → 熔断器状态，拒绝所有请求，触发备用策略
- `HALF_OPEN` → 半开状态，允许有限请求探测恢复
### 备用策略
请求失败时的安全备用链：
```
请求失败 → 缓存备用（忽略TTL）→ 模拟备用 → 返回错误
```
**配置示例**:
```json
{
"fallback": {
"enabled": true,
"useExpiredCache": true, // 使用过期缓存作为备用
"useMockAsFallback": true // 使用模拟数据作为备用
}
}
```
### 安全最佳实践
1. **不硬编码敏感信息**：使用`tokens`配置或环境变量
2. **日志净化**：不记录敏感信息
3. **参数化查询**：防止SQL注入
4. **输入验证**：所有外部输入必须验证
---
## 配置参考
📖 **完整配置参数**：参见[CONFIG_CN.md](CONFIG_CN.md)了解详细的配置参数描述、类型、必填/选填和默认值。
---
## 与Claude Code结合使用
Claude Code可以通过npx自动安装和使用。
### 1. 项目级配置（推荐）
在项目根目录创建`.mcp.json`文件：
**选项1：STDIO模式（Claude Code默认，自动管理进程）**
Claude Code自动管理进程，**无需手动启动**。
```json
{
"mcpServers": {
"http-gateway": {
"command": "npx",
"args": ["-y", "@lvdaxianer/mcp-http-gateway", "--config", "/绝对路径/to/tools.json"]
}
}
}
```
**选项2：SSE模式（持久连接，需要手动启动）**
手动启动服务，然后Claude Code通过SSE连接。
```json
{
"mcpServers": {
"http-gateway": {
"type": "sse",
"url": "http://localhost:11114/sse",
"description": "HTTP API 网关"
}
}
}
```
启动服务：
```bash
npx -y @lvdaxianer/mcp-http-gateway --transport=sse --config=./tools.json
```
**选项3：双模式（Claude Code + VSCode同时使用，需要手动启动）**
手动启动服务，支持STDIO和SSE连接。
```json
{
"mcpServers": {
"http-gateway": {
"type": "sse",
"url": "http://localhost:11114/sse"
}
}
}
```
启动服务：
```bash
npx -y @lvdaxianer/mcp-http-gateway --transport=dual --config=./tools.json
```
### 2. 全局安装（替代方案）
```bash
npm install -g @lvdaxianer/mcp-http-gateway
```
---
## 快速开始
```bash
# 安装
npm install @lvdaxianer/mcp-http-gateway
# 双模式启动
npx @lvdaxianer/mcp-http-gateway --transport=dual --config=./tools.json
```
---
## License
MIT
