# GPT Proxy MCP Server

一个用于 Claude Code 的 MCP (Model Context Protocol) 服务器，用于中转 GPT API 调用。

## 功能特点

- 🔄 GPT API 中转：支持所有主流 GPT 模型
- 🔒 安全：通过环境变量管理 API 密钥
- 🚀 流式响应：支持流式和常规两种响应模式
- ⚡ 高性能：基于 MCP SDK 构建，高效稳定
- 🛠️ 易用：简单的配置和启动流程

## 快速开始

### 本地部署（stdio 传输）

#### 1. 安装依赖

```bash
npm install
```

#### 2. 配置环境变量

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，添加你的 OpenAI API 密钥
nano .env
```

在 `.env` 文件中添加：

```env
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
```

#### 3. 启动服务器

```bash
# 开发模式启动（推荐）
npm run dev

# 或者使用启动脚本（会检查环境变量）
./start.sh

# 生产模式启动
npm run build
npm start
```

### 远程部署（HTTP 传输）

对于需要在远程服务器部署并从本地 Claude Code 连接的场景：

#### 1. 在远程服务器上部署

```bash
# 克隆项目到远程服务器
git clone <your-repo-url>
cd mcp-server

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
nano .env
```

在 `.env` 文件中配置：

```env
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
HTTP_PORT=3001
HTTP_HOST=0.0.0.0
```

#### 2. 启动 HTTP 服务器

```bash
# 使用启动脚本（推荐，会检查配置）
./start-http.sh

# 或者手动启动
npm run build
npm run start:http

# 开发模式
npm run dev:http
```

#### 3. 配置防火墙（如需要）

```bash
# Ubuntu/Debian 示例
sudo ufw allow 3001/tcp

# CentOS/RHEL 示例
sudo firewall-cmd --permanent --add-port=3001/tcp
sudo firewall-cmd --reload
```

## 在 Claude Code 中使用

### 本地连接配置

对于本地部署的 MCP 服务器，在你的 Claude Code MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "gpt-proxy": {
      "command": "node",
      "args": ["/path/to/your/mcp-server/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

或者对于开发环境：

```json
{
  "mcpServers": {
    "gpt-proxy": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/your/mcp-server",
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### 远程连接配置

对于部署在远程服务器的 MCP 服务器，在你的 Claude Code MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "gpt-proxy-remote": {
      "url": "http://your-server-ip:3001"
    }
  }
}
```

如果你使用了 HTTPS（推荐用于生产环境）：

```json
{
  "mcpServers": {
    "gpt-proxy-remote": {
      "url": "https://your-domain.com"
    }
  }
}
```

#### 远程连接使用步骤

1. **确保远程服务器正在运行**
   ```bash
   # 在远程服务器上检查服务状态
   curl http://localhost:3001
   ```

2. **更新 Claude Code 配置**
   - 找到你的 Claude Code MCP 配置文件（通常在 `~/.config/claude-code/` 目录）
   - 添加上述远程服务器配置
   - 重启 Claude Code

3. **测试连接**
   - 在 Claude Code 中应该能看到 `gpt_chat` 和 `gpt_chat_stream` 工具
   - 尝试使用工具发送消息测试连接

### 使用工具

配置完成后，在 Claude Code 中你可以使用以下工具：

#### `gpt_chat` - 标准聊天
```
使用 gpt_chat 工具发送消息到 GPT-4：
message: "请帮我解释什么是机器学习"
model: "gpt-4"
temperature: 0.7
```

#### `gpt_chat_stream` - 流式聊天
```
使用 gpt_chat_stream 工具获取流式响应：
message: "写一段关于 AI 发展历史的文章"
model: "gpt-4-turbo"
max_tokens: 2000
```

## 支持的模型

- `gpt-3.5-turbo` (默认)
- `gpt-3.5-turbo-16k`
- `gpt-4`
- `gpt-4-turbo`
- `gpt-4-turbo-preview`
- `gpt-4-0125-preview`
- `gpt-4-1106-preview`

## API 参数说明

### 通用参数

- `message` (必需): 发送给 GPT 的消息
- `model` (可选): 要使用的 GPT 模型，默认为 `gpt-3.5-turbo`
- `max_tokens` (可选): 响应的最大 token 数，默认为 1000
- `temperature` (可选): 响应的随机性 (0-2)，默认为 1
- `system_prompt` (可选): 系统提示词，用于设置 AI 的行为

## 项目结构

```
mcp-server/
├── src/
│   ├── index.ts          # 主服务器文件
│   └── types.ts          # TypeScript 类型定义
├── .env.example          # 环境变量模板
├── .gitignore           # Git 忽略文件
├── start.sh             # 启动脚本
├── package.json         # 项目配置
├── tsconfig.json        # TypeScript 配置
├── CLAUDE.md           # Claude Code 指导文件
└── README.md           # 项目说明
```

## 开发指南

### 本地开发

```bash
# 安装依赖
npm install

# 启动开发服务器（热重载）
npm run dev

# 类型检查
npm run type-check

# 构建项目
npm run build
```

### 环境变量

**通用配置:**
- `OPENAI_API_KEY` (必需): OpenAI API 密钥
- `OPENAI_BASE_URL` (可选): API 端点，默认为 `https://api.openai.com/v1`
- `OPENAI_ORGANIZATION` (可选): OpenAI 组织 ID

**HTTP 服务器配置（仅用于远程部署）:**
- `HTTP_PORT` (可选): HTTP 服务器端口，默认为 `3001`
- `HTTP_HOST` (可选): HTTP 服务器主机，默认为 `0.0.0.0`（监听所有网络接口）

## 故障排除

### 常见问题

1. **API 密钥错误**
   - 确保在 `.env` 文件中设置了正确的 `OPENAI_API_KEY`
   - 检查 API 密钥是否有效且有余额

2. **模型不可用**
   - 确认你的 API 密钥有访问所请求模型的权限
   - 某些模型可能需要等待列表或特殊权限

3. **连接问题**
   - 检查网络连接
   - 如果在中国大陆，可能需要配置代理

### 日志查看

服务器启动时会在控制台输出日志信息，包括：
- 启动状态
- 错误信息
- API 调用状态

## 安全注意事项

- 🔐 永远不要提交包含真实 API 密钥的 `.env` 文件
- 🛡️ 使用环境变量管理敏感配置
- 🔒 服务器通过 stdio 传输运行，确保安全的 Claude Code 集成
- 📝 定期轮换你的 API 密钥

## 许可证

MIT License

## 贡献

欢迎提交 Pull Request 和 Issue！

## 更新日志

### v1.0.0
- 初始版本发布
- 支持 GPT API 中转
- 支持流式和标准响应
- 完整的错误处理
- Claude Code MCP 集成