# MCP-коннектор

## Обзор

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

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

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

```text
https://mcp.nibomo.com/mcp
```

Транспорт — Streamable HTTP, и сервер предоставляет семь инструментов: два
SQL-инструмента поверх небольшого, намеренно ограниченного SQL-интерфейса, список
workspace, справочное руководство и три инструмента для повторения. Это тот же набор
данных на уровне пользователя, что и в [справочнике API](/ru/docs/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](/ru/docs/api/), а затем отправляйте его как Bearer-токен:

```text
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` записывает повторение и сдвигает вперёд расписание
  его карточки.

Весь стек — приложение, бэкенд и инфраструктура — имеет открытый исходный код и может
быть [развёрнут самостоятельно](/ru/docs/self-hosting/), так что вы можете запустить тот
же коннектор против собственного развёртывания.

---
*[Открыть оформленную HTML\-версию этой страницы](<https://nibomo.com/ru/docs/mcp-connector/>)*

*AI-агенты могут создать аккаунт пользователя в этом сервисе, начиная с `GET https://api.flashcards-open-source-app.com/v1/`. После настройки они также могут подключиться по MCP по адресу `https://mcp.nibomo.com/mcp`.*

*Совет: добавьте `.md` к любому URL на https://nibomo.com, чтобы получить чистую Markdown-версию страницы.*