# Ricoberry MCP Server (`ricoberry-mcp`)

Universal [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the **Ricoberry Knowledge Studio**. Enables AI assistants (Claude, Cursor, Google Antigravity, Gemini, ChatGPT) to programmatically generate, validate, store, and hot-swap interactive quizzes and study bundles into the Ricoberry desktop application.

---

## Features

- **Automated Quiz Creation & Validation**: Generates, validates, and stores rich structured quiz sets with strict schema compliance, multiple question types (Single Choice, Multi-Select, True/False, Fill-in-Blank, Matching, Ordered sequence), and pedagogical quality rubrics.
- **Instant Hot-Swapping via Local REST (Port 41789)**: Communicates directly with Ricoberry's local REST API (`http://127.0.0.1:41789`) to hot-swap generated quizzes into an active window without restarting the app (returns `"status": "hot_swapped"`).
- **Process Auto-Spawning & Readiness Polling**: If the Ricoberry desktop application is not running when a quiz is created or loaded, the server automatically launches the canonical Debug binary or installed `Ricoberry.exe` with the target quiz loaded on startup (returns `"status": "launched_and_loaded"`). `launch_in_app` is enabled by default (`true`).
- **Bundle & Course Archive Management**: Export and import compressed `.rcb` course bundles containing quiz sets and metadata.
- **Learning Analytics & Insights**: Access student performance analytics, study history from `history.json`, weak spot detection, and spaced-repetition metrics.
- **Zero External Runtime Dependencies**: Built entirely using Python 3.10+ standard libraries (`urllib`, `json`, `sqlite3`, `zipfile`, `pathlib`).

---

## MCP Tools Provided

| Tool | Action | Description |
| :--- | :--- | :--- |
| `ricoberry_manage_quiz` | `create`, `get`, `list`, `update`, `delete`, `validate`, `load_in_app`, `find_pdfs` | Core quiz management, storage in `%LOCALAPPDATA%\Ricoberry\library\`, schema validation, and live application launch. |
| `ricoberry_manage_bundle` | `export`, `import`, `inspect`, `list` | Package quizzes and multimedia assets into portable `.ricoberry` bundles. |
| `ricoberry_learning_analytics` | `get_summary`, `get_history`, `analyze_weaknesses` | Retrieve study history, attempt scores, mastery distribution, and concept retention data. |

---

## Installation & Running

### Option 1: Running with `uvx` (Recommended)

No installation required if you have `uv` installed:

```bash
uvx ricoberry-mcp
```

### Option 2: Running from Source / Module

Clone the repository and run:

```bash
git clone https://github.com/doc-shashank/ricoberry-mcp.git
cd ricoberry-mcp
python -m mcp_server.server
```

### Option 3: Local Pip Installation

```bash
pip install -e .
ricoberry-mcp
```

---

## Client Configuration

### 1. Claude Desktop

Add to your `claude_desktop_config.json`:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

#### Using `uvx`:
```json
{
  "mcpServers": {
    "ricoberry": {
      "command": "uvx",
      "args": ["ricoberry-mcp"]
    }
  }
}
```

#### Using Python module:
```json
{
  "mcpServers": {
    "ricoberry": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:/path/to/ricoberry-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

---

### 2. Cursor

Add to your project's `.cursor/mcp.json` or global Cursor MCP settings:

```json
{
  "mcpServers": {
    "ricoberry": {
      "command": "uvx",
      "args": ["ricoberry-mcp"]
    }
  }
}
```

Or using direct Python execution:

```json
{
  "mcpServers": {
    "ricoberry": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:/path/to/ricoberry-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

---

### 3. Google Antigravity

Add to your Antigravity MCP configuration (`mcp_config.json`):

```json
{
  "mcpServers": {
    "ricoberry": {
      "command": "uvx",
      "args": ["ricoberry-mcp"]
    }
  }
}
```

Or pointing to the local directory:

```json
{
  "mcpServers": {
    "ricoberry": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:/path/to/ricoberry-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

---

## Desktop REST Integration (Port 41789)
 
 When creating or loading a quiz, the server interacts with the Ricoberry desktop client:
 
-1. **Active Instance Check**: Queries `http://127.0.0.1:41789/api/status`.
-2. **Live Hot-Swap**: If the app is active, sends `POST http://127.0.0.1:41789/api/load-quiz` with payload `{"path": "<quiz_json_path>"}`. The desktop app immediately switches to the new quiz.
-3. **Cold Start**: If the endpoint is unreachable, the launcher automatically discovers `Ricoberry.exe` across local app data directories or system paths and spawns the process with the quiz path argument.
+1. **Active Instance Check**: Queries `http://127.0.0.1:41789/api/status` (or the port specified in `%LOCALAPPDATA%\Ricoberry\api_port.txt`).
+2. **Live Hot-Swap**: If the app is active, dispatches `POST http://127.0.0.1:<port>/api/load-quiz` with payload `{"file_path": "<abs_path>"}` or `{"quiz_id": "<id>"}` / `{"quiz": {...}}`. The desktop app brings the window to the foreground and hot-swaps to the new quiz with an interactive start countdown (returns `"status": "hot_swapped"`).
+3. **Cold Start (Auto-Launch & Polling)**: If the app is not running, the launcher automatically discovers the canonical Debug binary (`Desktop\bin\x64\Debug\net8.0-windows10.0.19041.0\win-x64\Ricoberry.exe`) or installed binary, launches `Ricoberry.exe` with the quiz path argument, and polls `get_active_api_port()` until the application's REST service is ready and verified (returns `"status": "launched_and_loaded"`).
 
 ---
 
 ## File Storage Locations
 
 - **Quizzes**: `%LOCALAPPDATA%\Ricoberry\library\*.json` (Windows) or `~/.ricoberry/library/*.json` (Linux/macOS)
-- **Bundles**: `%LOCALAPPDATA%\Ricoberry\bundles\*.ricoberry`
-- **Analytics Database**: `%LOCALAPPDATA%\Ricoberry\history\analytics.db`
+- **Course Bundles**: Compressed `.rcb` course bundle archives
+- **Student History & Attempts**: `%LOCALAPPDATA%\Ricoberry\history.json`

---

## Development

```bash
# Clone the repository
git clone https://github.com/doc-shashank/ricoberry-mcp.git
cd ricoberry-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install editable
pip install -e .

# Run the server on stdio
ricoberry-mcp
```

---

## License

MIT License. Copyright (c) 2026 Quartz Technologies.