# FlashCardsMCP

This is a dockerized Python Model Context Protocol (MCP) server for managing flash card projects. It uses OpenAI embeddings and SQLite for semantic search and storage.

## 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

## 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

## Getting Started

1. **Install dependencies:**
   ```sh
   pip install -r requirements.txt
   ```
2. **Run the server:**
   ```sh
   python main.py
   ```
3. **Run with Docker:**
   ```sh
   docker build -t flash-card-mcp .
   # Run with database persistence (recommended):
   docker run -v $(pwd)/storage:/app/storage/database.db flash-card-mcp
   ```

## Environment Variables

- **OPENAI_API_KEY**: Required. Set this environment variable to your OpenAI API key to enable embedding generation. Example:
  ```sh
  export OPENAI_API_KEY=sk-...your-key...
  ```
  You must set this variable before running the server or running the Docker container.

## Usage

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

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

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

## 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`.