VocabCoach-MCP-Server

techeditor/VocabCoach-MCP-Server

3.2

If you are the rightful owner of VocabCoach-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

VocabCoach MCP Server is a Model Context Protocol-based server designed to aid in English vocabulary learning and memory retention using the Ebbinghaus forgetting curve theory.

Tools
5
Resources
0
Prompts
0

VocabCoach MCP 服务器 (VocabCoach MCP Server)

本项目是一个基于MCP（Model Context Protocol）协议的英文单词学习和记忆辅助服务器，采用艾宾浩斯遗忘曲线理论，为中学英语词汇学习提供科学的复习计划管理功能。

功能特性

  • 🎯 智能单词查询 - 支持按课本和单元范围获取词汇，支持随机或顺序选择。
  • 🧠 艾宾浩斯遗忘曲线 - 科学的复习时间点设置（20分钟、1天、3天、1周、2周、1个月）。
  • 📅 复习计划管理 - 自动生成和跟踪复习进度，智能推送复习提醒。
  • 📊 Excel数据支持 - 兼容现有教学资源，支持数据持久化。
  • 🔄 MCP协议兼容 - 支持标准MCP客户端通信（Claude Desktop、Cline等）。
  • 🌐 多种运行模式 - stdio、HTTP、SSE、流式HTTP等多种服务器模式。
  • 🔍 统计分析功能 - 提供单词数量统计、学习进度分析。
  • 🛡️ 健康检查 - 内置健康检查和服务器状态监控。
  • 🐳 Docker支持 - 容器化部署方案。
  • 📝 完善的日志 - 详细的日志记录和错误追踪。

项目结构

vocab-coach-mcp-server/
├── src/                      # 核心代码模块
│   ├── __init__.py          # 模块初始化
│   ├── main.py              # 主入口点
│   ├── mcp_server.py        # MCP服务器实现
│   ├── mcp_tools.py         # MCP工具函数
│   ├── data_access.py       # 数据访问层
│   ├── ebbinghaus.py        # 艾宾浩斯遗忘曲线管理器
│   ├── models.py            # 数据模型定义
│   ├── exceptions.py        # 自定义异常
│   ├── config.py            # 配置管理
│   ├── launcher.py          # 服务启动器
│   ├── server_manager.py    # 服务器管理器
│   ├── backup_manager.py    # 备份管理器
│   ├── logging_config.py    # 日志配置
│   └── mcp_sdk/             # MCP SDK实现
├── data/                    # 数据文件
│   └── Middle School English Vocabulary.xlsx # 示例文件
├── docs/                     # 文档
│   ├── API_REFERENCE.md     # API参考文档
│   ├── USER_GUIDE.md        # 用户指南
│   ├── DEPLOYMENT_GUIDE.md  # 部署指南
│   └── DOCKER_USAGE.md      # Docker使用说明
├── .env.example             # 环境变量示例
├── requirements.txt          # 生产依赖
├── requirements_prod.txt     # 精简生产依赖
├── pyproject.toml           # 项目配置
├── Dockerfile               # Docker镜像构建文件
├── Makefile                 # 构建和管理命令
└── README.md                # 项目说明

快速开始

1. 安装依赖

# 克隆项目
git clone https://github.com/your-repo/vocab-coach-mcp-server.git
cd vocab-coach-mcp-server

# 创建虚拟环境（推荐）
python -m venv venv
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

2. 配置环境

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，配置参数：
EXCEL_FILE_PATH=
MCP_ACCESS_ID=
MCP_ACCESS_SECRET=

3. 运行服务器

方式1：直接运行（推荐）
# 启动stdio模式MCP服务器（用于MCP客户端）
python src/main.py

# 启动HTTP调试服务器
python src/main.py --mode http --port 8000

# 启动SSE服务器
python src/main.py --mode sse --port 8001

# 启动流式HTTP服务器
python src/main.py --mode streamable_http --port 8002
方式2：使用Makefile
# 查看所有可用命令
make help

# Docker方式启动Server和Client
make run-all

# 本地方式启动Server和Client
make local-all
方式3：使用Docker
# 使用docker-compose（推荐）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

4. 验证安装

# 检查服务器健康状态（HTTP模式）
curl http://localhost:8000/health

# 或在MCP客户端中调用
health_check()
get_server_info()

核心功能

MCP工具函数

服务器提供以下MCP工具函数：

1. 单词查询
  • get_words_by_range - 按课本和单元范围获取单词
  • get_available_textbooks - 获取支持的课本列表
  • get_available_subjects - 获取指定课本的单元列表
  • get_word_count_statistics - 获取单词数量统计
  • get_range_query_help - 获取查询帮助信息
2. 复习管理
  • set_review_schedule - 为单词设置艾宾浩斯复习计划
  • get_review_words - 获取需要复习的单词列表
  • update_review_status - 更新单词复习状态
3. 系统工具
  • get_server_info - 获取服务器信息和状态
  • health_check - 执行健康检查

支持的课本

  • 七上（七年级上册）
  • 七下（七年级下册）
  • 八上（八年级上册）
  • 八下（八年级下册）
  • 九全（九年级全册）
  • 全部（所有课本）

艾宾浩斯复习时间点

  • 学习后 20 分钟
  • 学习后 1 天
  • 学习后 3 天
  • 学习后 1 周（7天）
  • 学习后 2 周（14天）
  • 学习后 1 个月（30天）

使用示例

示例1：获取单词并设置复习计划

// 1. 获取七年级上册Unit 1的5个随机单词
const result = get_words_by_range("七上", "Unit 1", 5, true);

// 2. 为每个单词设置复习计划
for (const word of result.words) {
    set_review_schedule(word.row_index);
}

示例2：复习单词

// 1. 获取当前需要复习的10个单词
const reviewWords = get_review_words(null, 10, true);

// 2. 用户完成复习后更新状态
for (const word of reviewWords.words) {
    update_review_status(word.row_index, true);
}

示例3：查看统计信息

// 获取七年级上册的单词统计
const stats = get_word_count_statistics("七上");

// 获取服务器信息
const serverInfo = get_server_info();

// 执行健康检查
const health = health_check();

开发状态

✅ 项目已完成核心功能开发

已完成功能：

  • ✅ 完整的MCP服务器实现（stdio、HTTP、SSE、流式HTTP模式）
  • ✅ 10个MCP工具函数
  • ✅ Excel数据访问层（支持缓存和异步操作）
  • ✅ 艾宾浩斯遗忘曲线管理器
  • ✅ 复习计划自动生成和跟踪
  • ✅ 数据持久化和备份管理
  • ✅ 错误处理和日志系统
  • ✅ 健康检查和服务器监控
  • ✅ Docker容器化部署
  • ✅ 文档（API参考、用户指南、部署指南）
  • ✅ 服务启动器和管理器

持续改进：

  • 🔄 性能优化
  • 🔄 更多测试用例
  • 🔄 监控和告警功能
  • 🔄 多语言支持

技术栈

核心框架

  • MCP框架: FastMCP >= 0.9.0
  • 数据处理: pandas >= 2.0.0, openpyxl >= 3.1.0
  • 异步处理: asyncio, aiohttp >= 3.8.0
  • HTTP服务器: uvicorn >= 0.20.0, starlette >= 0.25.0

部署工具

  • 容器化: Docker, Docker Compose

系统要求

  • Python: 3.8 或更高版本
  • 操作系统: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+)
  • 内存: 最少 512MB，推荐 1GB+
  • 存储: 最少 100MB，推荐 500MB+
  • 网络: HTTP模式需要开放相应端口

常见问题

Q: 如何更换词汇数据文件？

A: 使用 --excel-file 参数指定文件路径，或在 .env 文件中设置 EXCEL_FILE_PATH。

Q: 如何查看日志？

A: 日志文件位于 logs/ 目录，或使用 --log-level DEBUG 查看详细日志。

故障排除

服务器启动失败

# 检查Python版本
python --version

# 检查依赖
pip install -r requirements.txt

# 查看详细错误
python src/main.py --log-level DEBUG

版本历史

  • v1.0.0 (2024-09) - 首个正式版本
    • 完整的MCP服务器实现
    • 10个核心工具函数
    • 艾宾浩斯复习计划管理
    • Docker支持
    • 文档

许可证

本项目采用 MIT 许可证 - 查看 文件了解详情。