Flash Cards MCP

🚀 FlashCardsMCP

A dockerized Python Model Context Protocol (MCP) server designed for managing flash card projects. It leverages OpenAI embeddings and SQLite for semantic search and data storage.

🚀 Quick Start

1. Install dependencies:

   pip install -r requirements.txt
   

2. Run the server:

   python main.py
   

3. Run with Docker:

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

✨ Features

• List all project names and ids
• Semantic search for project by name (using OpenAI embeddings)
• Get random flash card by project id
• Add flash card to project (with question, answer, optional hint, optional description)
• List all flash cards by project
• Semantic search for flash cards by query (using OpenAI embeddings)
• Global semantic search for cards across all projects
• Retrieve a card by its id
• All API/tool responses include a type field: project or card
• No binary embedding data is ever returned in API responses

📦 Installation

Environment Variables

• OPENAI_API_KEY: Required. Set this environment variable to your OpenAI API key to enable embedding generation. Example:

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

  You must set this variable before running the server or running the Docker container.

💻 Usage Examples

Basic Usage

This server exposes its API via the Model Context Protocol (MCP) using FastMCP. You can call the following tools:

# List all projects
get_all_projects()
# Create a new project (returns full project dict)
add_project(name)
# Semantic search for a project (returns full project dict)
search_project_by_name(name)
# Get a random card from a project
get_random_card_by_project(project_id)
# Add a card (returns full card dict)
add_card(project_id, question, answer, hint=None, description=None)
# List all cards in a project
get_all_cards_by_project(project_id)
# Semantic search for cards in a project
search_cards_by_embedding(project_id, query)
# Semantic search for cards across all projects
global_search_cards_by_embedding(query)
# Retrieve a card by its id
get_card_by_id(card_id)

All returned objects include a type field and never include binary embedding data.

📚 Documentation

API/Tool Design

• All tools raise ValueError for not found or empty results
• Project and card creation tools return the full object, not just the id
• See .github/copilot-instructions.md for code generation rules

Development

• All project and card data is stored in SQLite (database.db)
• Embeddings are generated using OpenAI's text-embedding-ada-002 model
• The server is implemented in main.py and db.py
• See .github/copilot-instructions.md for code and API rules

Inspector

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

For more details, see the code and docstrings in main.py and db.py.