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