vocabcube-mcp-server-js

techeditor/vocabcube-mcp-server-js

3.2

If you are the rightful owner of vocabcube-mcp-server-js 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.

VocabCube is an intelligent English vocabulary learning and memory aid system based on the Ebbinghaus forgetting curve, implemented as an MCP (Model Context Protocol) server.

Tools
4
Resources
0
Prompts
0

VocabCube - 英文单词学习和记忆辅助MCP服务器

License: MIT Node.js MCP Compatible

VocabCube是一个基于艾宾浩斯遗忘曲线的智能英文单词学习和记忆辅助系统，实现为MCP (Model Context Protocol) 服务器。它帮助中学生科学地学习和复习英语词汇，提高记忆效果。

✨ 核心特性

  • 🧠 科学记忆算法: 基于艾宾浩斯遗忘曲线的智能复习计划
  • 📚 丰富词汇库: 包含2305个中学英语词汇，覆盖七年级到九年级
  • 🎯 精准筛选: 支持按课本、单元范围获取单词
  • 📊 进度跟踪: 自动记录学习进度和复习状态
  • 🔄 智能复习: 根据遗忘曲线自动安排复习时间
  • 🛠️ MCP标准: 完全兼容MCP协议，可集成到各种AI应用

📖 词汇数据覆盖

  • 七年级上册 (七上): Starter Unit 1-3, Unit 1-9
  • 七年级下册 (七下): Unit 1-12
  • 八年级上册 (八上): Unit 1-10
  • 八年级下册 (八下): Unit 1-10
  • 九年级全册 (九全): Unit 1-14

每个单词包含：单词、中文释义、音标、课本信息、单元信息。 因版权原因，本仓库中只提供示例文件。

🚀 快速开始

环境要求

  • Node.js 18.0 或更高版本
  • npm 或 pnpm 包管理器

安装依赖

# 使用pnpm
pnpm install

启动服务器

# 通过xiaozhi-client启动
xiaozhi start

# 或直接启动MCP服务器
node mcpServers/VocabCube/index.js

配置说明

VocabCube已预配置在 xiaozhi.config.json 中：

{
  "mcpServers": {
    "vocabCube": {
      "command": "node",
      "args": ["./mcpServers/VocabCube/index.js"],
      "env": {},
      "disabled": false
    }
  }
}

🛠️ MCP工具接口

VocabCube提供4个核心MCP工具：

1. get_words_by_range - 按范围获取单词

根据课本和单元范围获取英语单词。

参数:

  • text_book (可选): 课本名称 - "七上"、"七下"、"八上"、"八下"、"九全"、"全部"
  • text_book_subject (可选): 主题名称 - 如"Starter Unit 1"、"Unit 1"等
  • word_count (可选): 返回单词数量，默认为1
  • is_random (可选): 是否随机选择，默认为true

示例:

{
  "name": "get_words_by_range",
  "arguments": {
    "text_book": "七上",
    "text_book_subject": "Starter Unit 1",
    "word_count": 3,
    "is_random": false
  }
}

2. set_memory_plan - 设置记忆计划

为指定单词设置基于艾宾浩斯遗忘曲线的复习计划。

参数:

  • word (必需): 要设置记忆计划的单词
  • start_time (可选): 开始学习时间，ISO格式，默认为当前时间

复习时间间隔:

  • 20分钟后
  • 1天后
  • 3天后
  • 1周后
  • 2周后
  • 1个月后

示例:

{
  "name": "set_memory_plan",
  "arguments": {
    "word": "good",
    "start_time": "2024-01-01T10:00:00.000Z"
  }
}

3. get_review_words - 获取复习单词

获取当前需要复习的单词列表。

参数:

  • review_time (可选): 复习时间点，ISO格式，默认为当前时间
  • word_count (可选): 返回单词数量，默认为1
  • is_random (可选): 是否随机选择，默认为true

示例:

{
  "name": "get_review_words",
  "arguments": {
    "word_count": 5,
    "is_random": false
  }
}

4. mark_review_complete - 标记复习完成

标记单词复习完成，自动计算下次复习时间。

参数:

  • word (必需): 完成复习的单词
  • review_time (可选): 复习完成时间，默认为当前时间

示例:

{
  "name": "mark_review_complete",
  "arguments": {
    "word": "good"
  }
}

📁 项目结构

mcpServers/VocabCube/
├── index.js                    # 主服务器入口文件
├── lib/
│   ├── ExcelManager.js         # Excel数据处理管理器
│   ├── EbbinghausAlgorithm.js  # 艾宾浩斯遗忘曲线算法
│   └── Logger.js               # 日志记录工具
└── data/
    └── Middle School English Vocabulary.demo.xlsx  # 中学英语词汇数据示例

💡 使用场景

场景1: 开始学习新单词

  1. 使用 get_words_by_range 获取要学习的单词
  2. 使用 set_memory_plan 为单词设置复习计划
  3. 系统自动安排科学的复习时间表

场景2: 进行复习

  1. 使用 get_review_words 获取当前需要复习的单词
  2. 完成复习后使用 mark_review_complete 标记完成
  3. 系统自动计算下次复习时间

场景3: 按教材学习

  1. 指定课本和单元，如"七上 Starter Unit 1"
  2. 获取该单元的所有单词进行学习
  3. 为每个单词设置个性化的复习计划

🔧 技术架构

核心组件

  • ExcelManager: 负责Excel文件的读取、写入和数据管理
  • EbbinghausAlgorithm: 实现艾宾浩斯遗忘曲线算法
  • Logger: 提供统一的日志记录功能
  • MCP Server: 标准MCP协议服务器实现

数据存储

  • 使用Excel文件存储词汇数据和学习进度
  • 自动备份机制防止数据丢失
  • 支持并发访问和数据一致性

算法原理

艾宾浩斯遗忘曲线表明，遗忘在学习之后立即开始，而且遗忘的进程并不是均匀的。VocabCube根据这一原理设置了科学的复习间隔：

  1. 第1次复习: 学习后20分钟
  2. 第2次复习: 学习后1天
  3. 第3次复习: 学习后3天
  4. 第4次复习: 学习后1周
  5. 第5次复习: 学习后2周
  6. 第6次复习: 学习后1个月

📊 数据格式

单词数据结构

{
  "text_book": "七上",                    // 课本名称
  "text_book_subject": "Starter Unit 1", // 单元名称
  "word": "good",                         // 单词
  "chinese": "adj.好的",                  // 中文释义
  "phonetic": "[gʊd]",                   // 音标
  "review_20min": "2024-01-01T10:20:00Z", // 20分钟复习时间
  "review_1day": "2024-01-02T10:00:00Z",  // 1天复习时间
  "review_3day": "2024-01-04T10:00:00Z",  // 3天复习时间
  "review_1week": "2024-01-08T10:00:00Z", // 1周复习时间
  "review_2week": "2024-01-15T10:00:00Z", // 2周复习时间
  "review_1month": "2024-01-31T10:00:00Z", // 1个月复习时间
  "next_review_time": "2024-01-01T10:20:00Z" // 下次复习时间
}

🚨 错误处理

VocabCube提供完善的错误处理机制：

  • 参数验证错误: 输入参数不符合要求时的详细提示
  • 文件访问错误: Excel文件不存在或无法访问时的处理
  • 数据格式错误: Excel文件格式不正确时的验证
  • 业务逻辑错误: 如单词不存在、复习计划冲突等

所有错误信息都提供中文描述，便于理解和调试。

🔒 安全考虑

  • 文件访问安全: 验证Excel文件路径的合法性
  • 数据验证: 严格的输入参数验证
  • 并发控制: Excel文件访问的互斥锁机制
  • 数据备份: 自动创建备份文件防止数据损坏

让学习更科学，让记忆更持久！ 🚀