Covate

Covate

English | 简体中文 | 繁體中文

A context-aware Model Context Protocol (MCP) server that acts as a learning sidecar for AI coding assistants. It helps developers learn from AI-generated code changes through interactive quizzes and provides agents with a persistent project-specific debugging memory.

🌐 Resources

🚀 Why Use This?

☁️ Covate learning ledger (free)

The MCP server in this repo is free and open-source (MIT) — run it locally, no account required. The optional hosted learning ledger is free too: sign in with GitHub, then run COVATE_SYNC_URL=https://covate.org COVATE_SYNC_TOKEN=<your token> python -m covate.platform_sync from a project to push your local sessions up and review them in a browser:

• ☁️ Sync your learning sessions from any machine
• 📖 Every synced session, newest first, with its score
• 📊 Totals — sessions, questions, correct answers, running accuracy
• 🎯 The topics you answer worst, ranked
• 🔑 Your sync token — reveal or rotate it whenever you want

Not built yet, so not promised: progress-over-time charts, spaced-repetition study plans, team accounts. There is no paid tier and nothing to buy — the MCP works fully without the ledger, and the ledger costs nothing.

🔁 Spaced review (local, offline)

covate review keeps a small local ledger of concepts and when to ask about them again. It never talks to the network or to a model; your own agent writes the questions and publishes the page (for example with the FoldRender command line).

covate review page questions.json -o page.html   # questions -> a quiz page (answers marked)
foldrender publish page.html                      # your agent publishes it
foldrender answers <page> --json | covate review record   # score the first answers
covate review due                                 # what to ask about again today
covate review status                              # every concept + first-answer accuracy

Only the first pick on each question counts, so changing an answer after seeing the explanation cannot raise the score. (FoldRender shows the explanation during its few-second undo window, so an answer you take back inside that window does not count; one you leave alone does.) A new concept comes back after 1 day, then 7, then 30 days; a wrong answer sends it back to the 1-day step; passing all three means mastered. The ledger lives in the global Covate storage (override with COVATE_REVIEW_LEDGER). questions.json is {"title": ..., "questions": [{"concept", "question", "options": [...], "correct": <0-based index>, "explanation"?}]}.

In Claude Code, install the plugin to get the MCP server plus /covate:review and /covate:review-record, which walk your agent through the steps above (no hooks, nothing runs unless you call it):

/plugin marketplace add SunflowersLwtech/covate
/plugin install covate@covate

📦 Available Tools

Tool Details

🛠️ Installation

One-Line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/SunflowersLwtech/covate/main/scripts/install.sh | bash

irm https://raw.githubusercontent.com/SunflowersLwtech/covate/main/scripts/install.ps1 | iex

The installer will:

1. Auto-detect your Python environment (uv → conda → venv)
2. Clone the repository to ~/covate
3. Create virtual environment and install dependencies
4. Print the exact command to configure your IDE

Manual Installation

# 1. Clone the repository
git clone https://github.com/SunflowersLwtech/covate.git
cd covate

# 2. Create virtual environment and install
# Using uv (recommended)
uv venv --python 3.11 covate
source covate/bin/activate          # macOS/Linux
# covate\Scripts\activate           # Windows
uv pip install -e '.[dev]'

# Or using standard venv
python -m venv covate
source covate/bin/activate           # macOS/Linux
# covate\Scripts\activate            # Windows
pip install -e '.[dev]'

Docker Installation

# 1. Pull from Docker Hub
docker pull sunflowerslwtech/covate:latest

# Or build locally
git clone https://github.com/SunflowersLwtech/covate.git
cd covate
docker build -t covate .

# 2. Run with Docker
docker run -i covate

# 3. Or use Docker Compose
docker-compose up -d

⚙️ IDE Configuration

Claude Code (CLI) — One Command Setup

After installation, configure your AI coding IDE to use this MCP server.

Claude Code

Option 1: CLI (Recommended)

# macOS / Linux
claude mcp add covate -- ~/covate/covate/bin/covate

# Windows
claude mcp add covate -- %USERPROFILE%\covate\covate\Scripts\covate.exe

Option 2: Config File

Add to ~/.claude.json:

{
  "mcpServers": {
    "covate": {
      "command": "~/covate/covate/bin/covate"
    }
  }
}

For Windows:

{
  "mcpServers": {
    "covate": {
      "command": "C:\\Users\\YourName\\covate\\covate\\Scripts\\covate.exe"
    }
  }
}

Example paths:

• Unix (uv): ~/covate/covate/bin/covate
• Windows (uv): C:\\Users\\YourName\\covate\\covate\\Scripts\\covate.exe
• Windows (conda): C:\\Users\\YourName\\anaconda3\\envs\\covate\\Scripts\\covate.exe

Path breakdown (Unix example):

• ~/covate → repository directory
• covate → virtual environment directory created by uv/venv
• bin/covate → executable

Cursor

Add to Cursor MCP settings (Settings → MCP → Add Server):

{
  "covate": {
    "command": "~/covate/covate/bin/covate"
  }
}

For Windows:

{
  "covate": {
    "command": "C:\\Users\\YourName\\covate\\covate\\Scripts\\covate.exe"
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "covate": {
      "command": "~/covate/covate/bin/covate"
    }
  }
}

Docker Configuration

To use Docker with any MCP-compatible IDE:

{
  "mcpServers": {
    "covate": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/workspace",
        "-w",
        "/workspace",
        "covate"
      ]
    }
  }
}

See DOCKER.md for detailed Docker configuration examples for Claude Desktop, Cursor, and other IDEs.

Other IDEs

For any MCP-compatible IDE, use these settings:

• Command: <install-path>/covate/bin/covate (or covate\Scripts\covate.exe on Windows)
• Transport: stdio

After configuration, restart your IDE.

Usage

Available Tools

For Users: Learning Session

Say to your AI assistant:

• "Quiz me on this change"
• "Test my understanding"
• "Help me learn about what you did"

The agent will create an interactive learning card and wait until you complete it.

Note: Quiz scores are saved locally for your self-tracking but are NOT returned to the agent - this keeps the context clean.

For Agents: Debug Tools

The debug tools work silently in the background:

• Search first: When encountering errors, agent searches past solutions
• Record after: When fixing errors, agent records the solution
• Progressive disclosure: Returns compact summaries, not full records
• Fast lookups: Uses inverted index for keyword-based searches

Updating

One-Line Update (Recommended)

The remote update script automatically detects your installation and works with any path format (including Chinese/non-ASCII paths):

curl -fsSL https://raw.githubusercontent.com/SunflowersLwtech/covate/main/scripts/update.sh | bash

irm https://raw.githubusercontent.com/SunflowersLwtech/covate/main/scripts/update.ps1 | iex

The update script will:

1. Auto-detect your installation location (supports multiple installations)
2. Pull the latest changes from the repository
3. Force-reinstall dependencies to ensure version synchronization
4. Verify installation integrity and report any issues
5. Detect if MCP server is in use and provide clear instructions

Why remote update?

• ✅ Works with Chinese/non-ASCII paths without cd navigation
• ✅ Always uses the latest update logic from the repository
• ✅ Auto-detects installation location even if you forgot where it is
• ✅ Handles multiple installations gracefully

Local Update (Alternative)

macOS / Linux:

~/covate/scripts/update.sh

Windows (PowerShell):

~\covate\scripts\update.ps1

Manual Update

# Navigate to installation directory
cd ~/covate  # or your custom installation path

# Pull latest changes
git pull origin main

# Update dependencies
# Using uv
source covate/bin/activate          # macOS/Linux
# covate\Scripts\activate           # Windows
uv pip install -e '.[dev]' --upgrade

# Or using standard venv
source covate/bin/activate           # macOS/Linux
# covate\Scripts\activate            # Windows
pip install -e '.[dev]' --upgrade

🖼️ Screenshots

Learning Session WebUI

🔒 Security & Privacy

🔮 Roadmap

We're building toward a Personalized Learning Center that grows with you. Here's what's coming:

🔍 Advanced Search & Indexing (v1.3)

📱 Mobile App (v2.0)

🎯 Personalized Learning Center (v2.5)

🤖 AI Enhancements (v3.0)

Want to influence the roadmap? Open an issue or join the discussion!

🔧 Environment Variables

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Install dev dependencies: uv pip install -e '.[dev]'
4. Make changes and run tests: pytest
5. Submit a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📬 Contact

📄 License

This project is licensed under the MIT License.

Built with FastMCP • MCP Standard • Glama MCP