flash-cards-mcp

🚀 FlashCardsMCP

FlashCardsMCP 是一个采用 Docker 容器化的 Python 模型上下文协议（MCP）服务器，用于管理抽认卡项目。它借助 OpenAI 嵌入技术和 SQLite 实现语义搜索与数据存储。

✨ 主要特性

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

📚 详细文档

API/工具设计

• 所有工具在未找到结果或结果为空时会抛出 ValueError。
• 项目和抽认卡创建工具返回完整对象，而非仅返回 ID。
• 有关代码生成规则，请参阅 .github/copilot-instructions.md。

环境变量

• OPENAI_API_KEY：必需。将此环境变量设置为你的 OpenAI API 密钥，以启用嵌入生成。示例如下：

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

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

🚀 快速开始

安装依赖

pip install -r requirements.txt

运行服务器

python main.py

使用 Docker 运行

docker build -t flash-card-mcp .
# 使用数据库持久化运行（推荐）：
docker run -v $(pwd)/storage:/app/storage/database.db flash-card-mcp

💻 使用示例

此服务器通过 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 中实现。
• 有关代码和 API 规则，请参阅 .github/copilot-instructions.md。

检查器

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 中的代码和文档字符串。