内容
<div align="center">
# 🧠 LeetCode AI MCP 助手
### AI 驱动的 LeetCode 伴侣 — 全栈版
* 使用 Claude AI、Model Context Protocol（MCP）服务器、实时 WebSockets 和精致的 React 仪表盘增强您的 LeetCode 学习体验。*
[](https://github.com/your-org/leetcode-ai-mcp-assistant/actions)
[](https://nodejs.org)
[](https://react.dev)
[](https://vitejs.dev)
[](https://tailwindcss.com)
[](https://opensource.org/licenses/MIT)
[概述](#-概述) • [功能](#-功能) • [架构](#-架构) • [快速入门](#-快速入门) • [API 文档](#-api-文档) • [MCP 服务器设置](#-mcp-服务器设置) • [部署](#-部署)
</div>
---
## 📋 目录
- [概述](#-概述)
- [功能](#-功能)
- [架构](#-架构)
- [技术栈](#-技术栈)
- [单体仓库结构](#-单体仓库结构)
- [前提条件](#-前提条件)
- [快速入门](#-快速入门)
- [环境变量](#-环境变量)
- [Docker 设置](#-docker-设置)
- [运行项目](#-运行项目)
- [前端页面](#-前端页面)
- [API 文档](#-api-文档)
- [MCP 服务器设置](#-mcp-服务器设置)
- [WebSocket 协议](#-websocket-协议)
- [测试](#-测试)
- [部署](#-部署)
- [许可证](#-许可证)
---
## 🚀 概述
**LeetCode AI MCP 助手** 是一个全栈应用，它将 LeetCode 的问题库与 Claude AI 配对，并封装在一个精致的、生产就绪的软件包中：
- 🖥️ **后端（Node.js/Express）** — REST API、MCP 服务器、WebSockets、Redis 缓存和 Claude 驱动的 AI 工具
- 🎨 **前端（React 19）** — ChatGPT 风格的 AI 助手、实时仪表盘、热图和完整的问题解决工作流
- 🔌 **MCP 服务器** — 让 Claude Desktop、Cursor 和其他 MCP 兼容工具原生查询 LeetCode
- ⚡ **实时** — 提交状态的 WebSocket 通知和实时更新
无论您是构建自己的 AI 增强编码实践工具，还是将 LeetCode 集成到 AI 助手的工具带中，该项目都为您提供引擎和仪表盘。
---
## ✨ 功能
<table>
<tr>
<td width="50%" valign="top">
### 🔧 后端
| 类别 | 功能 |
|---|---|
| **身份验证** | 注册、登录、JWT 访问 + 刷新令牌、注销 |
| **个人资料** | 查看、更新、删除帐户 |
| **LeetCode** | 搜索、问题详情、每日挑战、比赛、用户统计 |
| **AI 工具** | 解释问题、提示、解释解决方案、分析代码、优化、时间和空间复杂度 |
| **MCP 服务器** | 7 个 AI 助手的原生工具 |
| **收藏夹** | 添加、删除、列出 |
| **历史记录** | 搜索历史记录、最近查看、清除 |
| **每日** | 今日挑战、历史记录、AI 解释 |
| **基础设施** | PostgreSQL、Redis、WebSockets、Docker、GitHub Actions CI |
</td>
<td width="50%" valign="top">
### 🎨 前端
| 类别 | 功能 |
|---|---|
| **身份验证流程** | 登录、注册、忘记密码 UI |
| **仪表盘** | 实时统计、每日挑战、收藏夹、最近活动 |
| **问题** | 搜索、过滤、分页、详细问题视图 |
| **AI 助手** | ChatGPT 风格的聊天界面 |
| **每日挑战** | 倒计时器 + AI 解释 |
| **收藏夹** | 保存的问题网格 |
| **历史记录** | 搜索历史记录 + 最近查看 |
| **个人资料** | LeetCode 统计、提交热图 |
| **设置** | 主题切换（暗模式）、帐户、危险区域 |
| **用户体验** | 骨架加载器、吐司、动画 |
</td>
</tr>
</table>
---
## 🏗️ 架构
```
┌──────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ React 19 SPA │ Claude Desktop │ Cursor │ Continue │
└─────────┬──────────────────┬─────────────────┬────────────────┘
│ REST / WS │ MCP（stdio）
▼ ▼
┌──────────────┐ ┌────────────────┐
│ Express │ │ MCP 服务器 │
│ REST API │ │ （stdio NDJSON）│
└──────┬────────┘ └───────┬────────┘
│ │
▼ ▼
┌────────────────────────────────────┐
│ 服务层 │
│ authService │ leetcodeService │
│ aiService（Anthropic Claude） │
└──────┬───────────────────┬─────────┘
│ │
▼ ▼
┌────────────┐ ┌─────────────┐
│ PostgreSQL │ │ Redis │
│ （pg 池） │ │ （缓存） │
└────────────┘ └─────────────┘
```
**关键设计决策**
- 🗂️ **仓库模式** — 所有 SQL 隔离在 `repositories/` 中；服务永远不会编写原始查询
- 🧩 **服务层** — 所有业务逻辑都在 `services/` 中；控制器保持薄
- ♻️ **单例连接** — 应用程序中只有一个共享的 DB 池和一个 Redis 客户端
- 🛑 **优雅关闭** — SIGTERM 关闭正在进行的请求后退出（对 Docker/K8s 至关重要）
- 📦 **通过 TanStack Query 进行服务器状态** — 前端自动缓存和同步 API 数据
- 🌓 **暗模式优先** — 状态通过 Zustand 存储持久化
---
## 🧰 技术栈
<table>
<tr>
<td valign="top" width="50%">
**后端**
- Node.js 20+ / Express
- PostgreSQL（通过 `pg`）
- Redis（缓存）
- WebSockets（`ws`）
- JWT 身份验证（访问 + 刷新）
- Anthropic Claude API
- Model Context Protocol SDK
- Jest（单元测试 + 集成测试）
- Docker / Docker Compose
- GitHub Actions CI
</td>
<td valign="top" width="50%">
**前端**
| 工具 | 用途 |
|---|---|
| React 19 + Vite | UI 框架 + 构建 |
| Tailwind CSS v4 | 样式设计，支持暗模式 |
| React Router DOM | 客户端路由 |
| TanStack Query | 服务器状态和缓存 |
| Zustand | 身份验证和主题状态 |
| Axios | HTTP 客户端，带有 JWT 拦截器 |
| React Hook Form | 表单验证 |
| Framer Motion | 动画 |
| Recharts | 图表（甜甜圈、热图） |
| React Hot Toast | 通知 |
| Lucide React | 图标 |
</td>
</tr>
</table>
---
## 📁 单体仓库结构
```
leetcode-ai-mcp-assistant/
├── backend/
│ ├── src/
│ │ ├── config/ # DB、Redis、logger、Swagger 配置
│ │ ├── controllers/ # 薄 HTTP 处理程序
│ │ ├── middleware/ # 身份验证、错误处理程序、速率限制器、验证
│ │ ├── repositories/ # 所有 SQL 代码
│ │ ├── routes/ # Express Router 定义
│ │ ├── services/
│ │ │ ├── authService.js
│ │ │ ├── ai/aiService.js # Anthropic Claude 集成
│ │ │ ├── leetcode/leetcodeService.js
│ │ │ └── mcp/mcpServer.js # MCP 工具定义
│ │ ├── utils/ # AppError、响应帮助程序
│ │ ├── validators/
│ │ ├── websocket/ # wsHandler.js
│ │ ├── app.js # Express 应用（无 server.listen）
│ │ └── server.js # 入口点
│ ├── mcp/index.js # 独立 MCP 服务器入口点
│ ├── migrations/run.js
│ ├── tests/
│ │ ├── unit/
│ │ └── integration/
│ ├── Dockerfile
│ ├── docker-compose.yml
│ └── package.json
│
└── frontend/
├── src/
│ ├── components/
│ │ ├── ui/ # Skeleton、Badge、EmptyState、Spinner、CopyButton
│ │ ├── layout/ # AppLayout、Sidebar、Header
│ │ ├── problems/ # ProblemCard
│ │ ├── dashboard/ # StatsCard
│ │ └── charts/ # SolvedDonut、SubmissionHeatmap
│ ├── pages/ # 每个路由一个文件
│ ├── routes/ # Router + ProtectedRoute + PublicRoute
│ ├── services/ # api.js（axios）+ 端点定义
│ ├── store/ # authStore.js、themeStore.js（Zustand）
│ ├── utils/ # cn、getDifficultyClass、formatDate...
│ └── constants/ # QUERY_KEYS、DIFFICULTIES、TAGS、LANGUAGES
└── package.json
```
---
## ✅ 前提条件
- **Node.js** >= 20.0.0
- **PostgreSQL** >= 14
- **Redis** >= 6
- **Anthropic API 密钥** — [在此处获取](https://console.anthropic.com)
---
## ⚡ 快速入门
### 1. 克隆仓库
```bash
git clone https://github.com/your-org/leetcode-ai-mcp-assistant.git
cd leetcode-ai-mcp-assistant
```
### 2. 设置后端
```bash
cd backend
npm install
cp .env.example .env
# 编辑 .env 文件，填写实际值
npm run migrate
npm run dev # 运行于 http://localhost:3000
```
### 3. 设置前端
```bash
cd ../frontend
npm install
npm run dev # 运行于 http://localhost:5173，代理 /api → :3000
```
在 **http://localhost:5173** 打开 — 仪表盘现在应该正在与本地后端通信。 🎉
---
## 🔐 环境变量
### 后端（`backend/.env`）
| 变量 | 描述 | 默认值 |
|---|---|---|
| `PORT` | HTTP 服务器端口 | `3000` |
| `DB_HOST` | PostgreSQL 主机 | `localhost` |
| `DB_PORT` | PostgreSQL 端口 | `5432` |
| `DB_NAME` | 数据库名称 | `leetcode_mcp` |
| `DB_USER` | 数据库用户 | `postgres` |
| `DB_PASSWORD` | 数据库密码 | — |
| `REDIS_HOST` | Redis 主机 | `localhost` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `JWT_SECRET` | JWT 签名密钥 | — **（必填）** |
| `JWT_ACCESS_EXPIRES` | 访问令牌生命周期 | `15m` |
| `JWT_REFRESH_EXPIRES` | 刷新令牌生命周期 | `7d` |
| `ANTHROPIC_API_KEY` | Claude API 密钥 | — **（必填）** |
| `ANTHROPIC_MODEL` | 使用的 Claude 模型 | `claude-sonnet-4-6` |
| `CORS_ORIGIN` | 允许的 CORS 源 | `*` |
| `LOG_LEVEL` | 日志级别 | `info` |
### 前端（`frontend/.env`）
```env
# 可选 — 开发服务器代理自动处理此部分
VITE_API_URL=http://localhost:3000/api/v1
```
---
## 🐳 Docker 设置
```bash
cd backend
cp .env.example .env
# 使用一个命令启动所有服务（应用 + postgres + redis）
docker compose up --build
# 在 Docker 中运行迁移
docker compose run --rm migrate
# 查看日志
docker compose logs -f app
# 停止所有服务
docker compose down
# 停止并删除卷（⚠️ 删除所有数据）
docker compose down -v
```
---
## 🏃 运行项目
### 后端
```bash
npm run dev # 开发（自动重启文件更改）
npm start # 生产
npm run migrate # 运行数据库迁移
node mcp/index.js # 独立启动 MCP 服务器（适用于 Claude Desktop）
```
### 前端
```bash
npm run dev # 开发服务器，支持热重载
npm run build # 生产构建 → dist/
npm run preview # 预览生产构建
```
---
## 🖼️ 前端页面
| 路由 | 页面 |
|---|---|
| `/login` | JWT 登录 |
| `/register` | 注册 |
| `/forgot-password` | 密码重置（仅 UI） |
| `/dashboard` | 统计数据、每日挑战、收藏夹、最近活动 |
| `/problems` | 搜索、过滤、分页问题 |
| `/problems/:slug` | 完整问题详情 + AI 工具 |
| `/ai` | ChatGPT 风格的 AI 助手 |
| `/daily` | 每日挑战 + 倒计时 + AI 解释 |
| `/favorites` | 保存的问题网格 |
| `/history` | 搜索历史记录 + 最近查看 |
| `/profile` | LeetCode 统计数据、提交热图、编辑表单 |
| `/settings` | 主题切换、帐户设置、危险区域 |
---
## 📚 API 文档
交互式 Swagger UI 可访问： **http://localhost:3000/api-docs`
### 身份验证
所有受保护的端点都需要：
```
Authorization: Bearer <accessToken>
```
### 端点摘要
<details>
<summary><strong>🔑 身份验证 — <code>/api/v1/auth</code></summary>
| 方法 | 路径 | 身份验证 | 描述 |
|---|---|:---:|---|
| POST | `/register` | ❌ | 注册新用户 |
| POST | `/login` | ❌ | 登录 |
| POST | `/refresh` | ❌ | 刷新访问令牌 |
| POST | `/logout` | ❌ | 注销 |
| GET | `/me` | ✅ | 获取当前用户 |
</details>
<details>
<summary><strong>🧩 问题 — <code>/api/v1/problems</code></summary>
| 方法 | 路径 | 身份验证 | 描述 |
|---|---|:---:|---|
| GET | `/` | 可选 | 搜索问题（`?q=two+sum&difficulty=easy`） |
| GET | `/:titleSlug` | 可选 | 获取问题详情 |
| GET | `/daily` | 可选 | 今日的每日挑战 |
| GET | `/contests` | ❌ | 即将到来的比赛 |
| GET | `/user/:username/stats` | ❌ | 用户的 LeetCode 统计数据 |
</details>
<details>
<summary><strong>🤖 AI 工具 — <code>/api/v1/ai</code></strong></summary>
| 方法 | 路径 | 身份验证 | 描述 |
|---|---|:---:|---|
| POST | `/problems/:titleSlug/explain` | ✅ | AI 问题解释 |
| POST | `/problems/:titleSlug/hints` | ✅ | 分级提示 |
| POST | `/problems/:titleSlug/explain-solution` | ✅ | 解释解决方案 |
| POST | `/analyze-code` | ✅ | 代码质量分析 |
| POST | `/optimize-code` | ✅ | 优化建议 |
| POST | `/time-complexity` | ✅ | 时间复杂度分析 |
| POST | `/space-complexity` | ✅ | 空间复杂度分析 |
</details>
<details>
<summary><strong>⭐ 收藏夹 — <code>/api/v1/favorites</code></strong></summary>
| 方法 | 路径 | 身份验证 | 描述 |
|---|---|:---:|---|
| GET | `/` | ✅ | 列出收藏夹 |
| POST | `/` | ✅ | 添加收藏夹 |
| DELETE | `/:problemSlug` | ✅ | 删除收藏夹 |
</details>
<details>
<summary><strong>🕘 历史记录 — <code>/api/v1/history</code></strong></summary>
| 方法 | 路径 | 身份验证 | 描述 |
|---|---|:---:|---|
| GET | `/` | ✅ | 搜索历史记录 |
| DELETE | `/` | ✅ | 清除所有历史记录 |
| GET | `/recent` | ✅ | 最近查看的问题 |
| DELETE | `/:id` | ✅ | 删除一个历史记录项 |
</details>
<details>
<summary><strong>📅 每日 — <code>/api/v1/daily</code></strong></summary>
| 方法 | 路径 | 身份验证 | 描述 |
|---|---|:---:|---|
| GET | `/` | 可选 | 今日挑战 |
| GET | `/history` | ❌ | 挑战历史记录 |
| GET | `/explain` | ✅ | 今日挑战的 AI 解释 |
</details>
---
## 🔌 MCP 服务器设置
MCP 服务器允许 Claude Desktop 和其他 AI 工具直接使用 LeetCode，无需浏览器。
### 添加到 Claude Desktop
编辑 `~/.config/claude/claude_desktop_config.json`
（Mac： `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"leetcode": {
"command": "node",
"args": ["/绝对路径/项目/backend/mcp/index.js"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-your-key",
"DB_HOST": "localhost",
"DB_NAME": "leetcode_mcp",
"DB_USER": "postgres",
"DB_PASSWORD": "your-password",
"REDIS_HOST": "localhost"
}
}
}
}
```
### 可用的 MCP 工具
| 工具 | 描述 |
|---|---|
| `search_problems` | 按关键词、难度、标签搜索 |
| `get_problem` | 通过 slug 获取完整问题详情 |
| `get_daily_problem` | 今日挑战 |
| `explain_problem` | AI 解释 |
| `get_hints` | 分级提示 |
| `analyze_solution` | 代码分析 |
| `get_user_stats` | LeetCode 用户统计数据 |
---
## 🔄 WebSocket 协议
连接到： `ws://localhost:3000/ws`
```javascript
const ws = new WebSocket('ws://localhost:3000/ws');
// 1. 连接后认证
ws.onopen = () => {
ws.send(JSON.stringify({ type: 'AUTH', token: 'your-access-token' }));
};
// 2. 处理消息
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
console.log(msg.type, msg); // AUTH_SUCCESS, NOTIFICATION, etc.
};
// 3. 心跳
setInterval(() => ws.send(JSON.stringify({ type: 'PING' })), 25000);
```
---
## 🧪 测试
```bash
cd backend
npm test # 运行所有测试
npm run test:unit # 仅单元测试（快速，无网络/数据库）
npm run test:integration # 仅集成测试
npm test -- --coverage # 带有覆盖率报告
```
测试使用 Jest，支持 ES 模块。所有外部依赖项（PostgreSQL、Redis、Anthropic API、LeetCode GraphQL）都被模拟，因此测试运行速度很快，无需基础设施。
---
## 🚢 部署
### Docker（推荐）
```bash
cd backend
# 构建生产镜像
docker build -t leetcode-mcp:latest --target production .
# 运行环境变量
docker run -p 3000:3000 \
-e JWT_SECRET=your_secret \
-e ANTHROPIC_API_KEY=sk-ant-... \
-e DB_HOST=your-db-host \
-e REDIS_HOST=your-redis-host \
leetcode-mcp:latest
```
### 前端静态构建
```bash
cd frontend
npm run build
# 将 dist/ 部署到 Vercel、Netlify、Cloudflare Pages、S3 + CloudFront 等。
```
### 手动
```bash
cd backend
NODE_ENV=production npm start
```
### ✅ 生产环境检查清单
- [ ] `JWT_SECRET` 是一个长随机字符串（至少 64 个字符）
- [ ] `ANTHROPIC_API_KEY` 已设置
- [ ] `DB_PASSWORD` 已设置且强度高
- [ ] `CORS_ORIGIN` 限制为您的前端域名
- [ ] `NODE_ENV=production` 已设置
- [ ] HTTPS/TLS 在负载均衡器或反向代理处终止
- [ ] 前端 `VITE_API_URL` 指向生产 API URL
- [ ] Redis 和 PostgreSQL 已配置备份启用
---
## 📄 许可证
MIT — 免费使用、修改和分发。
<div align="center">
**使用 Claude、Express 和 React 构建 💕**
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器