Quiz App MCP server

Python MCP-сервер (Model Context Protocol), построенный на FastMCP. Предоставляет инструменты:

• Claude Desktop — локально, через stdio

• claude.ai — удалённо, по HTTP (развёрнут на Render)

Опционально использует базу данных MySQL через SQLAlchemy.

Структура проекта

.
├── server.py           # entry point — branches on RENDER env var (stdio vs HTTP)
├── config.py            # loads .env, exposes shared SQLAlchemy engine
├── tools/
│   ├── __init__.py
│   └── quiz.py           # tool definitions — register(mcp) adds them to a FastMCP instance
├── .env                  # secrets — never commit
├── .env.example
└── requirements.txt

Related MCP server: leafeep-mcp

Настройка

git clone https://github.com/sathvik1607/Quiz_mcp_server.git
cd Quiz_mcp_server
python -m venv venv
.\venv\Scripts\pip install -r requirements.txt
copy .env.example .env
# fill in .env with real DB credentials (or remove the DB_* lines if unused)

Проверьте работоспособность подключения к БД, прежде чем подключать это к Claude Desktop:

.\venv\Scripts\python.exe -c "from config import engine; from sqlalchemy import text; print(engine.connect().execute(text('SELECT 1')).scalar())"

Это должно вывести 1. Если команда зависает или завершается с ошибкой, сначала исправьте .env/подключение к БД — не пытайтесь отлаживать это через Claude Desktop.

Локальный запуск (stdio)

.\venv\Scripts\python.exe server.py

Или используйте MCP inspector для ручного вызова инструментов (браузерный интерфейс, Claude Desktop не нужен — удобно для проверки запроса/ответа каждого инструмента по отдельности). Требуется Node/npm, так как запуск происходит через npx:

.\venv\Scripts\mcp.exe dev server.py

Используйте точку входа mcp.exe в venv\Scripts, а не python -m mcp — в пакете mcp нет __main__, и такой вызов не сработает.

Подключение к Claude Desktop

Добавьте в %APPDATA%\Claude\claude_desktop_config.json (объедините с уже имеющимся содержимым — не перезаписывайте файл):

{
  "mcpServers": {
    "quizapp": {
      "command": "C:\\path\\to\\project\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\project\\server.py"]
    }
  }
}

Используйте абсолютные пути, соответствующие месту, куда вы клонировали репозиторий.

Полностью завершите работу Claude Desktop и перезапустите его — закройте его из системного трея, а не просто окно. Конфигурация MCP перезагружается только при полном перезапуске.

Затем убедитесь, что он загрузился: Settings → Connectors → quizapp должен быть указан в разделе "Other tools" с 5 инструментами (Register user, Get question, Validate answer, Generate leaderboard, Review answers).

Прохождение викторины

Начните новый чат и формулируйте запрос явно — расплывчатый запрос вроде «давайте начнём викторину» может быть ошибочно направлен в несвязанный встроенный сценарий «создать викторину» вместо вызова инструментов этого сервера. Вместо этого скажите, например:

«Используйте инструмент register_user, чтобы зарегистрировать меня как <name> с unique_id <id>, затем начните викторину.»

Дальше ход сценария определяют собственные инструкции сервера (в server.py) — по одному вопросу за раз, ожидая вашего ответа перед переходом дальше.

Деплой на Render (HTTP, для claude.ai)

1. Запушьте в GitHub (.env игнорируется git — никогда не коммитьте его).

2. Создайте в Render Web Service, подключённый к репозиторию.

3. Задайте переменные окружения в панели управления Render:

   Переменная	Значение
   RENDER	true
   DB_HOST	хост вашей БД
   DB_USER	пользователь вашей БД
   DB_PASSWORD	пароль вашей БД
   DB_NAME	имя вашей БД

4. Команда запуска: python server.py

5. В server.py обновите BASE_URL в ветке RENDER, указав фактический URL вашего приложения на Render.

6. В claude.ai → Settings → Connectors добавьте: https://your-app.onrender.com/mcp

На HTTP-эндпоинте сейчас не настроена аутентификация — любой, у кого есть URL, может вызывать все инструменты, включая те, что работают с БД. Это было осознанным решением, чтобы пока упростить настройку; вернитесь к этому вопросу, прежде чем открывать доступ к чему-либо чувствительному (см. «Безопасность» ниже).

Примечание

OAuth пока убран с HTTP-эндпоинта — мы ещё не используем claude.ai с БД/инструментами этого сервера, поэтому дополнительная сложность не стоила того. Верните его позже, если понадобится.

Keep-alive

Бесплатный тариф Render переходит в спящий режим после 15 минут простоя, из-за чего первый запрос после сна выполняется медленно (30–60 с) или завершается по тайм-ауту. Уже принятые меры:

• Фоновый поток в server.py пингует /health каждые 10 минут.

• Добавьте внешний монитор (например, UptimeRobot) на https://your-app.onrender.com/health каждые 5 минут — не на /mcp.

Добавление нового инструмента

Откройте tools/quiz.py и добавьте функцию внутри register(mcp):

@mcp.tool()
def my_new_tool(param1: str, param2: int) -> dict:
    """
    One-sentence description of what this tool does.
    The agent reads this docstring to decide when to call the tool.

    Args:
        param1: What this string parameter means.
        param2: What this integer parameter means.
    """
    result = do_something(param1, param2)
    return {"result": result}

Отдельный этап регистрации не нужен — register(mcp) вызывается и для stdio-, и для HTTP-инстансов.

Безопасность

• .env игнорируется git — никогда не коммитьте его.

• Инструменты никогда не возвращают сырой SQL и не раскрывают схему БД.

• Все запросы используют параметризованный SQL (text("... WHERE id = :id"), а не интерполяцию строк).

• Любое имя таблицы/колонки, переданное пользователем, должно проверяться по разрешённому списку перед использованием в SQL.

• HTTP-эндпоинт Render не имеет аутентификации — считайте его публичным. Не добавляйте инструменты, которые раскрывают чувствительные данные или выполняют деструктивные операции с БД, пока снова не будет добавлена аутентификация.

• Тот, у кого есть общие учётные данные DB_*, получает доступ к той же рабочей базе данных — отдельного dev/staging-инстанса нет. register_user и validate_answer пишут напрямую в неё, поэтому локальное тестирование добавляет реальные строки рядом с реальными данными викторины. При тестировании используйте отличительный unique_id и не используйте эти учётные данные сверх необходимого.