Flash Cards MCP

🚀 FlashCardsMCP

このプロジェクトは、フラッシュカードプロジェクトを管理するためのDocker化されたPythonのModel Context Protocol (MCP)サーバーです。OpenAIの埋め込み技術とSQLiteを使用して、意味検索とデータの保存を行います。

🚀 クイックスタート

依存関係のインストール

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

✨ 主な機能

• すべてのプロジェクト名と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コンテナを実行する前に、この変数を設定する必要があります。

使用方法

このサーバーは、FastMCPを使用してModel Context Protocol (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 のコードとドキュメント文字列を参照してください。