闪卡管理协议服务器

闪卡MCP

这是一个用于管理闪存卡项目的码头化Python模型上下文协议（MCP）服务器。它使用OpenAI嵌入和SQLite进行语义搜索和存储。

特性

• 列出所有项目名称和ID
• 按名称对项目进行语义搜索（使用OpenAI嵌入）
• 按项目id获取随机闪存卡
• 在项目中添加闪存卡（带问题、答案、可选提示、可选描述）
• 按项目列出所有闪存卡
• 通过查询进行闪存卡的语义搜索（使用OpenAI嵌入）
• 对所有项目中的卡片进行全局语义搜索
• 按id检索卡
• 所有API/工具响应包括 type 字段： project 或 card
• API响应中不返回二进制嵌入数据

API/工具设计

• 所有工具升高 ValueError 未找到或为空结果
• 项目和卡片创建工具返回完整的对象，而不仅仅是id
• 看 .github/copilot-instructions.md 用于代码生成规则

入门指南

1. 安装依赖项：
   复制

   pip install -r requirements.txt
   

2. 运行服务器：
   复制

   python main.py
   

3. 使用Docker运行：
   复制

   docker build -t flash-card-mcp .
   # Run with database persistence (recommended):
   docker run -v $(pwd)/storage:/app/storage/database.db flash-card-mcp
   

环境变量

• OPENAI_API密钥：必填。将此环境变量设置为OpenAI API键以启用嵌入生成。例子：
  复制

  export OPENAI_API_KEY=sk-...your-key...
  

  您必须在运行服务器或Docker容器之前设置此变量。

用法

该服务器通过使用FastMCP的模型上下文协议（MCP）公开其API。您可以调用以下工具：

• get_all_projects() → 列出所有项目
• add_project(name) → 创建新项目（返回完整的项目字典）
• search_project_by_name(name) → 项目的语义搜索（返回完整的项目字典）
• get_random_card_by_project(project_id) → 从项目中随机获取一张卡片
• add_card(project_id, question, answer, hint=None, description=None) → 添加一张卡（返回完整的卡字典）
• get_all_cards_by_project(project_id) → 列出项目中的所有卡片
• search_cards_by_embedding(project_id, query) → 项目中卡片的语义搜索
• global_search_cards_by_embedding(query) → 在所有项目中对卡片进行语义搜索
• get_card_by_id(card_id) → 按id检索卡

所有返回的对象都包括 type 字段，并且从不包含二进制嵌入数据。

发展

• 所有项目和卡片数据都存储在SQLite中(database.db)
• 嵌入是使用OpenAI生成的 text-embedding-ada-002 模型
• 服务器在中实现 main.py 和 db.py
• 看 .github/copilot-instructions.md 用于代码和API规则

检查员

npx @modelcontextprotocol/inspector docker 'run -e OPENAI_API_KEY=sk-...your-key... -v /<path>/storage:/app/storage --rm -i flash-card-mcp

有关更多详细信息，请参阅 main.py 和 db.py.