ВойтиНачать бесплатно

MCP-коннектор

Обзор

Flashcards предоставляет удалённый MCP-сервер (Model Context Protocol), чтобы MCP-клиенты и агенты ИИ могли читать ваши карточки к повторению, а также создавать и редактировать карточки и колоды за вас.

Агенты могут подключаться двумя способами: через этот MCP-сервер (лучший вариант для MCP-клиентов вроде Claude или Cursor) или через URL discovery для Agents API для CLI-агентов. Оба способа дают доступ к одному и тому же набору данных на уровне пользователя; эта страница посвящена MCP-серверу.

Подключайтесь по адресу:

https://mcp.flashcards-open-source-app.com/mcp

Транспорт — Streamable HTTP, и сервер предоставляет три инструмента поверх небольшого, намеренно ограниченного SQL-интерфейса. Это тот же набор данных на уровне пользователя, что и в справочнике API; MCP-сервер — это удобный для коннекторов способ получить к нему доступ из клиентов, которые поддерживают MCP.

Как добавить его в вашем клиенте

Большинство клиентов добавляют удалённый MCP-сервер как пользовательский коннектор:

  1. Откройте в вашем клиенте настройки коннекторов или MCP-серверов.
  2. Добавьте пользовательский коннектор и вставьте URL сервера https://mcp.flashcards-open-source-app.com/mcp.
  3. Для интерактивных клиентов авторизуйтесь в браузере, когда появится запрос. Сервер использует OAuth 2.1 с Dynamic Client Registration, поэтому нет client secret, который нужно было бы вставлять, и нет приложения, которое нужно регистрировать заранее.
  4. Для headless- или CLI-использования вместо браузерного потока задайте заголовок Authorization: Bearer fca_… с вашим API-ключом агента.

После авторизации один раз вызовите list_workspaces, чтобы выбрать workspace, а затем используйте sql_query для чтения и sql_execute для записи.

Инструменты

Сервер предоставляет три инструмента. Чтение и запись разделены намеренно, чтобы один инструмент никогда не смешивал безопасные и разрушительные операции.

  • sql_query — доступ только для чтения к вашим карточкам и колодам (SHOW TABLES, DESCRIBE, SHOW COLUMNS, SELECT).
  • sql_execute — доступ на запись к вашим карточкам и колодам (INSERT, UPDATE, DELETE) в виде атомарного пакета.
  • list_workspaces — список доступных вам workspace, для каждого с его workspaceId, именем, числом активных карточек, временем последней активности и признаком того, является ли он вашим текущим выбранным workspace по умолчанию. Используйте возвращённый workspaceId в качестве аргумента workspaceId для sql_query и sql_execute.

SQL-интерфейс — это намеренно ограниченный диалект, а не полноценный PostgreSQL. Выражения могут обращаться только к ресурсам workspace, cards, decks и review_events, каждое выражение ограничено вашим собственным workspace, а чтение и запись ограничены 100 строками на выражение.

Контракт карточки

Каждая карточка следует одному контракту, и инструменты опираются на него:

  • front_text — это только вопрос или подсказка к повторению и никогда не содержит ответа.
  • back_text содержит ответ, при необходимости с конкретным примером.

Агенты, которые генерируют карточки через sql_execute, следуют этому контракту, поэтому создаваемые ими карточки сразу готовы к повторению с интервальными повторениями.

Аутентификация

Два пути авторизации ведут к одному и тому же набору данных на уровне пользователя.

OAuth 2.1 (интерактивные клиенты-коннекторы)

Сервер реализует поток authorization-code с PKCE и Dynamic Client Registration. Добавьте URL MCP как пользовательский коннектор и авторизуйтесь в браузере; client secret заранее не передаётся. Discovery выполняется стандартно:

  • Метаданные защищённого ресурса (protected-resource): https://mcp.flashcards-open-source-app.com/.well-known/oauth-protected-resource
  • Метаданные сервера авторизации (authorization-server): https://auth.flashcards-open-source-app.com/.well-known/oauth-authorization-server

API-ключ (headless и CLI)

Получите долгоживущий API-ключ агента fca_ через поток входа по одноразовому коду из письма, описанный в справочнике API, а затем отправляйте его как Bearer-токен:

Authorization: Bearer fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS

Это тот же ключ, который принимает REST-интерфейс для агентов, и ему не нужны ни браузер, ни round-trip через OAuth.

Каноническое машиночитаемое описание обоих путей — это полезная нагрузка discovery по адресу https://api.flashcards-open-source-app.com/v1/ (с зеркалом на /v1/agent).

Безопасность и область действия

SQL-инструменты безопасно одобрять, потому что этот интерфейс — изолированный диалект с проверкой на уровне парсера, а не произвольный доступ к базе данных:

  • Закрытый список разрешённых выражений: sql_query принимает только SHOW TABLES, DESCRIBE, SHOW COLUMNS и SELECT; sql_execute принимает только INSERT, UPDATE и DELETE. Всё остальное отклоняется на этапе разбора.
  • Ограниченные ресурсы: выражения могут обращаться только к workspace, cards, decks и review_events.
  • Ограничение по workspace: каждое выражение ограничено выбранным вами workspace, без доступа к данным других арендаторов.
  • Лимиты: до 100 строк на выражение, до 50 выражений в пакете и ограничение результата примерно в 12k токенов. Пакеты изменений применяются атомарно.
  • Разделение чтения и записи: sql_query и list_workspaces работают только на чтение (readOnlyHint), а sql_execute выполняет запись (destructiveHint).

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