Readeck MCP

MCP-сервер, который превращает библиотеку Readeck в базу знаний для чтения и записи для ИИ-агентов: агенты могут отправлять сгенерированный ими HTML прямо в Readeck (автоматически тегируемый LLM) и позже извлекать и читать эти документы обратно. Создан на базе FastMCP — один и тот же код работает как локальный stdio-сервер или удалённый HTTP-сервер за обратным прокси.

В отличие от существующих Readeck MCP (которые являются ассистентами только для чтения), этот принимает сгенерированный агентом HTML и автоматически размечает его с помощью LLM по фиксированной таксономии.

Инструменты

readeck_save использует JSON create API Readeck с полем html для сырого HTML (base64/data-URI не работают). Он отправляет браузерный User-Agent, чтобы WAF (например, ошибка Cloudflare 1010) не блокировал его, и кратко опрашивает сервер, чтобы вернуть новый id закладки, word_count и reading_url.

Related MCP server: Doc Monitor MCP

Автоматическая разметка

Когда вы вызываете readeck_save без labels, LLM классифицирует документ. Он изначально устойчив к инъекциям: модель может выбирать только из фиксированной таксономии (LABEL_TAXONOMY), и результат пересекается с этим списком на стороне сервера, поэтому метки вне словаря невозможны. Метка происхождения (ORIGIN_LABEL, по умолчанию propio) всегда добавляется кодом, а не LLM.

Не зависит от провайдера (совместим с OpenAI или Anthropic). Работает с бесплатными тарифами, такими как Groq — для моделей рассуждений, таких как gpt-oss, установите щедрый LLM_MAX_TOKENS, и сервер автоматически отправит reasoning_effort: low.

Защитные механизмы

• Fail-closed HTTP-аутентификация: при HTTP-транспорте каждый вызов инструмента требует Authorization: Bearer $MCP_AUTH_TOKEN (сравнение за постоянное время).

• Проверка входных данных: ограничение размера HTML, отклонение не-HTML, белый список схем URL, санитизация меток + ограничение.

• Ограничение скорости по алгоритму token-bucket на процесс.

• Вызовы LLM повторяются при 429/5xx с экспоненциальной задержкой и корректно деградируют (разметка — best-effort; сбой никогда не блокирует сохранение).

Конфигурация (переменные окружения)

Локально (stdio)

READECK_TOKEN=... uv run --script server.py --selftest   # smoke test

Зарегистрируйте в MCP-клиенте (mcpServers), например:

{
  "mcpServers": {
    "readeck": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/readeck-mcp/server.py"],
      "env": { "READECK_URL": "https://readeck.example.com", "READECK_TOKEN": "..." }
    }
  }
}

Удалённо (HTTP / Docker)

Запустите с READECK_MCP_TRANSPORT=http (см. Dockerfile). Поместите его за вашим обратным прокси / туннелем, например, на https://mcp-readeck.example.com. При совместном размещении с Readeck установите READECK_URL=http://readeck:8000, чтобы пропустить публичный обход. Укажите клиентам конечную точку:

{
  "mcpServers": {
    "readeck": {
      "type": "http",
      "url": "https://mcp-readeck.example.com/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Примечание: используйте путь конечной точки без завершающего слэша (/mcp, а не /mcp/) — некоторые прокси превращают редирект с завершающим слэшем в 307, что ломает streamable-HTTP клиентов.

Всегда устанавливайте надёжный MCP_AUTH_TOKEN перед открытием конечной точки — токен даёт доступ на запись к вашей библиотеке.

Лицензия

MIT