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

MCP-коннектор

Обзор

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

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

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

https://mcp.nibomo.com/mcp

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

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

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

  1. Откройте в вашем клиенте настройки коннекторов или MCP-серверов.
  2. Добавьте пользовательский коннектор и вставьте URL сервера https://mcp.nibomo.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 для записи карточек и колод. Для повторения вызовите next_review_card, затем reveal_answer, затем submit_review.

Инструменты

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

  • sql_query — доступ строго только для чтения к вашим карточкам и колодам (SHOW TABLES, DESCRIBE, SHOW COLUMNS, SELECT).
  • sql_execute — доступ на запись к вашим карточкам и колодам (INSERT, UPDATE, DELETE) в виде атомарного пакета.
  • list_workspaces — строго доступный только для чтения список workspace, к которым у вас есть доступ, для каждого с его workspaceId, именем, числом активных карточек, временем последней активности и признаком того, является ли он вашим текущим выбранным workspace по умолчанию. Используйте возвращённый workspaceId в качестве необязательного аргумента workspaceId для SQL-инструментов и инструментов повторения.
  • get_guide — справочное руководство по одной теме, строго только для чтения: sql_dialect, card_authoring, bulk_authoring или review_flow. Этот инструмент не читает данные workspace.
  • next_review_card — строго только для чтения: возвращает следующую карточку к повторению, только её лицевую сторону, в том же порядке очереди, что и в приложениях. Необязательный аргумент tags или deckId сужает очередь.
  • reveal_answer — строго только для чтения: возвращает обратную сторону одной карточки после того, как учащийся попробовал ответить на её лицевую сторону.
  • submit_review — записывает одну оценку Again, Hard, Good или Easy и сдвигает вперёд FSRS-расписание карточки.

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

Повторения

Инструменты повторения позволяют агенту проверять знания учащегося по одной карточке за раз и сохранять каждую оценку в FSRS-расписание карточки:

  1. next_review_card возвращает cardId и frontText или card: null, если повторять пока нечего.
  2. После ответа учащегося reveal_answer возвращает backText этой карточки.
  3. submit_review принимает cardId, сгенерированный клиентом UUID reviewId, rating и часовой пояс учащегося в формате IANA reviewedTimeZone. Сервер проставляет время повторения и возвращает новое расписание карточки.

Если вы не уверены, что отправка прошла, повторите её с тем же reviewId; второе повторение при этом никогда не записывается. Отправка также может вернуть:

  • 409 REVIEW_EVENT_CONFLICT — повторение уже записано, а детали ошибки содержат текущее расписание карточки.
  • 409 REVIEW_ID_CARD_MISMATCH — reviewId уже обозначает повторение другой карточки, поэтому ничего не сохранено; отправьте повторение заново с новым reviewId.
  • 409 REVIEW_STALE — сохранённое время повторения карточки совпадает с текущим временем сервера или позже него; повторите другую карточку.

Повторения записываются только через submit_review: SQL не может записывать review_events или состояние FSRS-расписания. Полные правила повторения и оценки возвращает get_guide с темой review_flow.

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

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

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

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

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

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

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

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

  • Метаданные защищённого ресурса (protected-resource): https://mcp.nibomo.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: каждое SQL-выражение и каждое повторение ограничены одним доступным вам workspace — либо переданным вами workspaceId, либо выбранным вами workspace по умолчанию, без доступа к данным других арендаторов.
  • Строгие аргументы: каждый инструмент отклоняет неизвестный аргумент, поэтому workspaceId с опечаткой приводит к ошибке, а не к выполнению в вашем workspace по умолчанию.
  • Лимиты: до 100 строк на выражение, до 50 выражений в пакете и ограничение результата примерно в 12k токенов. Пакеты изменений применяются атомарно.
  • Разделение чтения и записи: sql_query, list_workspaces, get_guide, next_review_card и reveal_answer работают строго только на чтение (readOnlyHint) и не исправляют данные, не пересчитывают расписание и не изменяют состояние карточек. sql_execute и submit_review — единственные инструменты записи (destructiveHint): sql_execute записывает карточки и колоды, а submit_review записывает повторение и сдвигает вперёд расписание его карточки.

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