MonstraVocab 🚀

一个智能的词汇学习系统，专为开发者设计，支持MCP集成，让你在编程时无缝管理技术词汇。

✨ 特色功能

• 🎯 双向学习模式: 英译中 & 中译英
• 🤖 MCP服务器集成: 在Cursor、Claude Desktop、Codex、Kiro中无缝添加词汇
• 📊 智能统计分析: 学习进度追踪和掌握程度评估
• 🔊 音标支持: 完整的发音标注系统
• 🌐 跨平台启动: 支持macOS、Linux、Windows
• 📱 响应式设计: 完美适配移动端和桌面端

🚀 快速开始

一键启动（推荐）

# 启动完整的后端服务器
./start.sh

# 可用的启动选项：
./start.sh 1      # 生产模式
./start.sh 2      # 开发模式（自动打开浏览器）
./start.sh 3      # 后台模式
./start.sh 4      # 调试模式
./start.sh 5      # 停止所有服务器
./start.sh --help # 显示帮助

手动启动

如果需要手动启动，可以使用以下命令：

# 安装依赖
npm install

# 启动服务器
npm start

然后在浏览器中访问 http://localhost:8964

MCP服务器设置

快速设置

# 安装MCP服务器依赖
./setup-mcp.sh

# 测试MCP服务器
python3 test-mcp.py

配置MCP客户端

Kiro/Cursor/Claude Desktop 将以下配置添加到你的MCP设置中：

{
  "mcpServers": {
    "vocabulary-learning": {
      "command": "python3",
      "args": ["/path/to/your/project/mcp-server.py"],
      "env": {
        "VOCABULARY_API_BASE": "http://localhost:8964/api",
        "CSV_FILE_PATH": "/path/to/your/project/data/wordlist.csv"
      }
    }
  }
}

Codex 在 ~/.codex/config.toml 文件中添加以下配置：

[mcp_servers.vocabulary-learning]
command = "python3"
args = ["/path/to/your/project/mcp-server.py"]

[mcp_servers.vocabulary-learning.env]
VOCABULARY_API_BASE = "http://localhost:8964/api"
CSV_FILE_PATH = "/path/to/your/project/data/wordlist.csv"

使用示例

在支持MCP的编程环境中，你可以使用自然语言：

• "添加单词 algorithm，中文意思是算法，音标是 /ˈælɡərɪðəm/"
• "检查单词 function 是否已存在"
• "显示我的词汇统计信息"
• "搜索包含 data 的单词"

✨ 功能特性

核心功能

• ✅ 添加和管理词汇（支持音标）
• ✅ 英译中和中译英学习模式
• ✅ 学习记录追踪和统计
• ✅ 搜索和过滤词汇
• ✅ 学习统计分析
• ✅ 响应式设计
• ✅ 完整的后端API支持

高级功能

• 🔧 MCP服务器集成 - 在编程环境中无缝添加词汇
• 🖥️ 跨平台支持 - 支持macOS、Linux、Windows
• ⚙️ 智能进程管理 - 自动端口检测和进程管理
• � 系统健康检查- - 资源监控和状态检测
• 🚀 多种启动模式 - 生产、开发、后台、调试模式

🎯 使用说明

1. 添加词汇：在"添加词汇"页面输入英文单词和中文释义
2. 开始学习：在"开始学习"页面选择学习模式
3. 查看词汇：在"词汇列表"页面浏览和搜索已添加的词汇
4. 查看统计：在"学习统计"页面查看学习进度和表现

🔧 技术架构

后端

• Node.js + Express - RESTful API服务器
• CSV文件存储 - 轻量级数据持久化
• CORS支持 - 跨域请求处理
• 错误处理 - 完善的异常处理机制

前端

• 原生HTML/CSS/JavaScript - 无框架依赖
• 响应式设计 - 支持移动端和桌面端
• API客户端 - 与后端服务通信
• 学习引擎 - 智能学习算法

MCP集成

• Model Context Protocol服务器 - 支持Cursor、Claude Desktop、Codex、Kiro
• 自然语言接口 - 在编程时轻松添加词汇
• 双重存储 - API优先，CSV备用

🎯 为什么选择 MonstraVocab？

MonstraVocab 专为程序员设计，解决了技术英语学习中的痛点：

• 📖 边编程边学习: 遇到新术语时无需切换应用，直接添加到词汇库
• 🧠 智能记忆算法: 根据掌握程度智能安排复习
• 🔊 标准发音: 每个词汇都配有国际音标
• 📊 进度可视化: 清晰了解学习进展和薄弱环节

📝 使用建议

• 推荐通过启动脚本运行以获得完整功能体验
• 配置MCP服务器后可在编程时无缝添加词汇
• 定期查看学习统计了解掌握情况

🛠️ 开发说明

项目结构

├── server.js              # Express服务器
├── package.json           # Node.js依赖
├── start.sh               # 启动脚本
├── mcp-server.py          # MCP服务器
├── setup-mcp.sh           # MCP设置脚本
├── public/                # 前端文件
│   ├── index.html
│   ├── app.js
│   ├── api-client.js
│   ├── learning-engine.js
│   └── styles.css
├── routes/                # API路由
│   ├── words.js
│   └── records.js
├── utils/                 # 工具函数
│   └── csvManager.js
└── data/                  # 数据文件
    └── wordlist.csv

API端点

• GET /api/words - 获取所有词汇
• POST /api/words - 添加新词汇
• GET /api/records/:mode - 获取学习记录
• POST /api/records/:mode - 保存学习记录
• GET /api/stats - 获取统计信息

故障排除

服务器无法启动

# 检查端口占用
lsof -i :8964

# 强制停止相关进程
./start.sh 5

MCP服务器问题

# 重新安装依赖
pip3 install --user -r requirements-mcp.txt

# 测试MCP服务器
python3 test-mcp.py

数据同步

确保前端和后端数据同步，如有显示问题请刷新页面。