# MCP конектор

## Свързване през директорията на Claude

Отворете [Nibomo в директорията на Claude](https://claude.ai/directory/nibomo), свържете го, влезте в акаунта си в Nibomo и разрешете достъпа. Nibomo е публикуван като конектор от категорията Community.

За Claude Code използвайте същия акаунт с абонамент за Claude и проверете `/mcp` след свързването. Влизането с API ключ или чрез външен доставчик не зарежда автоматично конекторите ви от claude.ai.

Можете също да настроите Claude Code директно. Изпълнете командата по-долу, след това отворете `/mcp` в Claude Code и завършете разрешаването в браузъра:

```bash
claude mcp add --transport http nibomo https://mcp.nibomo.com/mcp
```

[Документация на Claude Code за MCP](https://code.claude.com/docs/en/mcp#use-mcp-servers-from-claudeai).

## Общ преглед

Nibomo предоставя отдалечен MCP (Model Context Protocol) сървър, чрез който MCP клиенти и
ИИ агенти могат да четат картите ви за преговор, да ги преговарят с вас въпрос по въпрос
и да създават или редактират карти и тестета вместо вас.

Агентите могат да се свързват по два начина: през този MCP сървър (най-подходящо за MCP клиенти като
Claude или Cursor) или през [URL адреса за откриване на Agents API](/bg/docs/api/) за CLI
агенти. И двата начина достигат до едни и същи данни на потребителя; тази страница описва MCP сървъра.

Адрес за свързване:

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

Транспортът е Streamable HTTP. Сървърът предоставя осем инструмента за откриване на работни пространства, четене и запис на карти и тестета, справочни ръководства, преговори и използването на акаунта.

## Как да го добавите в клиента си

Повечето клиенти добавят отдалечен MCP сървър като персонализиран конектор:

1. Отворете настройките за конектори или MCP сървъри в клиента си.
2. Добавете персонализиран конектор и поставете URL адреса на сървъра `https://mcp.nibomo.com/mcp`.
3. При интерактивните клиенти разрешете достъпа в браузъра, когато бъдете подканени. Сървърът
   използва OAuth 2.1 с Dynamic Client Registration, затова няма клиентски секрет за
   поставяне и не е нужно първо да регистрирате приложение.
4. При работа без графичен интерфейс или от CLI задайте заглавка `Authorization: Bearer fca_…` с
   API ключа на агента си вместо потока през браузъра.

След разрешаването извикайте веднъж `list_workspaces`, за да изберете работно пространство, след това
използвайте `sql_query` за четене и `sql_execute` за запис на карти и тестета. За преговор извикайте
`next_review_card`, след това `reveal_answer` и накрая `submit_review`.

## Инструменти

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

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

SQL интерфейсът е умишлено ограничен диалект и не е пълен PostgreSQL.
Тази документация описва само поддържания диалект и не е справочник за съвместимост
с PostgreSQL. Заявките могат да се отнасят само до ресурсите `workspace`, `cards`, `decks` и
`review_events`, всяка заявка е ограничена до вашето работно пространство, а
четенето и записът са ограничени до `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. Добавете MCP URL адреса като персонализиран конектор и разрешете достъпа в браузъра;
не е нужен предварително споделен клиентски секрет. Откриването е стандартно:

- Метаданни на защитения ресурс:
  `https://mcp.nibomo.com/.well-known/oauth-protected-resource`
- Метаданни на сървъра за оторизация:
  `https://auth.flashcards-open-source-app.com/.well-known/oauth-authorization-server`

### API ключ (без графичен интерфейс и CLI)

Получете дългосрочен API ключ на агента с префикс `fca_` чрез потока за вход по имейл с OTP,
описан в [справочника на API](/bg/docs/api/), и го изпращайте като Bearer токен:

```text
Authorization: Bearer fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS
```

Това е същият ключ, който приема REST интерфейсът за агенти, и не изисква браузър или
преминаване през OAuth.

Основното машинночетимо описание на двата начина е отговорът за откриване
на `https://api.nibomo.com/v1/` (достъпен и на `/v1/agent`).

## Безопасност и обхват

SQL инструментите могат да се одобряват безопасно, защото интерфейсът е затворен диалект,
чиито правила се налагат от парсера, а не произволен достъп до базата данни:

- **Затворен списък с разрешени заявки**: `sql_query` приема само `SHOW TABLES`,
  `DESCRIBE`, `SHOW COLUMNS` и `SELECT`; `sql_execute` приема само `INSERT`,
  `UPDATE` и `DELETE`. Всичко друго се отхвърля още при синтактичния анализ.
- **Ограничени ресурси**: заявките могат да засягат само `workspace`, `cards`, `decks`
  и `review_events`.
- **Ограничение до работно пространство**: всяка SQL заявка и всеки преговор са ограничени до едно
  работно пространство, до което имате достъп — `workspaceId`, който подавате, или избраното от вас
  пространство по подразбиране, без достъп до данни на други наематели (tenants).
- **Строги аргументи**: всеки инструмент отхвърля непознат аргумент, така че сгрешен
  `workspaceId` води до грешка, вместо заявката да се изпълни върху работното ви пространство по подразбиране.
- **Лимити**: до `100` реда на заявка, до `50` заявки в пакет и
  резултат до около `12k` токена. Пакетите с промени се прилагат атомарно.
- **Разделение на четене и запис**: `get_usage_limits`, `sql_query`, `list_workspaces`, `get_guide`,
  `next_review_card` и `reveal_answer` са строго само за четене (`readOnlyHint`)
  и никога не поправят данни, не преизчисляват планирането и не променят състоянието на картите.
  `sql_execute` и `submit_review` са единствените инструменти за запис (`destructiveHint`):
  `sql_execute` записва карти и тестета, а `submit_review` записва преговор и
  премества напред графика на картата.

Целият стек — приложение, бекенд и инфраструктура — е с отворен код и може да се
[хоства самостоятелно](/bg/docs/self-hosting/), така че можете да използвате същия конектор със
собствено разгръщане.

---
*[Вижте оформената HTML версия на тази страница](<https://nibomo.com/bg/docs/mcp-connector/>)*

*ИИ агентите могат да създадат акаунт за потребителя в тази услуга, като започнат с `GET https://api.nibomo.com/v1/`. След настройката могат и да се свържат през MCP на адрес `https://mcp.nibomo.com/mcp`.*

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