# MCP कनेक्टर

## परिचय

Nibomo एक रिमोट MCP (Model Context Protocol) सर्वर चलाता है ताकि MCP क्लाइंट और
AI एजेंट आपके बकाया कार्ड पढ़ सकें, एक समय में एक प्रश्न करके आपके साथ उनकी समीक्षा कर सकें,
और आपके लिए कार्ड व डेक बना या संपादित कर सकें।

एजेंट दो तरीकों से कनेक्ट कर सकते हैं: इस MCP सर्वर के जरिए (Claude या Cursor जैसे
MCP क्लाइंट के लिए सबसे अच्छा), या CLI एजेंटों के लिए [Agents API discovery URL](/hi/docs/api/)
के जरिए। दोनों एक ही प्रति-उपयोगकर्ता डेटा सतह तक पहुँचते हैं; यह पेज MCP सर्वर को कवर करता है।

इससे यहाँ कनेक्ट करें:

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

ट्रांसपोर्ट Streamable HTTP है, और सर्वर सात टूल उपलब्ध कराता है: एक छोटी, जानबूझकर
सीमित रखी गई SQL सतह पर दो SQL टूल, एक workspace सूची, एक संदर्भ गाइड, और तीन
समीक्षा टूल। यह वही प्रति-उपयोगकर्ता डेटा सतह है जो [API संदर्भ](/hi/docs/api/)
में है; MCP सर्वर इसे MCP बोलने वाले क्लाइंट से पहुँचने का कनेक्टर-अनुकूल तरीका है।

## इसे अपने क्लाइंट में कैसे जोड़ें

ज्यादातर क्लाइंट रिमोट MCP सर्वर को एक कस्टम कनेक्टर के रूप में जोड़ते हैं:

1. अपने क्लाइंट की कनेक्टर या MCP सर्वर सेटिंग्स खोलें।
2. एक कस्टम कनेक्टर जोड़ें और सर्वर URL `https://mcp.nibomo.com/mcp` पेस्ट करें।
3. इंटरैक्टिव क्लाइंट के लिए, संकेत मिलने पर ब्राउज़र में अधिकृत करें। सर्वर
   Dynamic Client Registration के साथ OAuth 2.1 का उपयोग करता है, इसलिए पेस्ट करने के लिए
   कोई client secret नहीं है और न ही पहले कोई ऐप रजिस्टर करना पड़ता है।
4. हेडलेस या CLI उपयोग के लिए, ब्राउज़र प्रवाह के बजाय अपनी एजेंट API key के साथ एक
   `Authorization: Bearer fca_…` header सेट करें।

अधिकृत करने के बाद, एक workspace चुनने के लिए एक बार `list_workspaces` कॉल करें, फिर
पढ़ने के लिए `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` — उन workspaces की सख्ती से केवल पढ़ने वाली सूची जिन तक आपकी
  पहुँच है, प्रत्येक के साथ उसका `workspaceId`, नाम, सक्रिय कार्ड संख्या, अंतिम
  गतिविधि, और क्या वह आपका वर्तमान में चुना हुआ डिफ़ॉल्ट है। SQL और समीक्षा टूल के
  वैकल्पिक `workspaceId` आर्गुमेंट के लिए वापस मिले `workspaceId` का उपयोग करें।
- `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 schedule को आगे बढ़ाता है।

SQL सतह एक जानबूझकर सीमित रखी गई बोली है और यह पूरा PostgreSQL नहीं है।
ये दस्तावेज़ केवल समर्थित बोली को कवर करते हैं, PostgreSQL compatibility
reference नहीं हैं। स्टेटमेंट केवल `workspace`, `cards`, `decks`, और
`review_events` संसाधनों को ही संबोधित कर सकते हैं, हर स्टेटमेंट आपके अपने
workspace तक सीमित है, और पढ़ने व लिखने की प्रति स्टेटमेंट `100` पंक्तियों की
सीमा है।

## समीक्षाएँ

समीक्षा टूल किसी एजेंट को एक समय में एक कार्ड पर शिक्षार्थी से प्रश्न पूछने और हर
रेटिंग को कार्ड के FSRS schedule में सहेजने देते हैं:

1. `next_review_card` एक `cardId` और `frontText` लौटाता है, या कुछ भी बकाया न होने
   पर `card: null`।
2. शिक्षार्थी के उत्तर देने के बाद, `reveal_answer` उस कार्ड का `backText` लौटाता है।
3. `submit_review` `cardId`, क्लाइंट द्वारा बनाया गया एक `reviewId` UUID, एक
   `rating`, और शिक्षार्थी का IANA `reviewedTimeZone` लेता है। सर्वर समीक्षा का समय
   दर्ज करता है और कार्ड का नया schedule लौटाता है।

किसी अनिश्चित सबमिशन को उसी `reviewId` के साथ दोबारा आज़माएँ; यह कभी दूसरी समीक्षा
दर्ज नहीं करता। कोई सबमिशन ये उत्तर भी दे सकता है:

- `409 REVIEW_EVENT_CONFLICT` — समीक्षा पहले ही दर्ज हो चुकी है, और error details में
  कार्ड का वर्तमान schedule होता है।
- `409 REVIEW_ID_CARD_MISMATCH` — `reviewId` पहले से किसी दूसरे कार्ड की समीक्षा की
  पहचान करता है, इसलिए कुछ भी संग्रहीत नहीं हुआ; नए `reviewId` के साथ फिर से सबमिट करें।
- `409 REVIEW_STALE` — कार्ड का संग्रहीत समीक्षा समय वर्तमान सर्वर समय के बराबर या
  उसके बाद का है; किसी दूसरे कार्ड की समीक्षा करें।

समीक्षाएँ केवल `submit_review` के जरिए दर्ज होती हैं: SQL `review_events` या FSRS
scheduling state नहीं लिख सकता। पूरी समीक्षा और रेटिंग नियमों के लिए `review_flow`
विषय के साथ `get_guide` कॉल करें।

## कार्ड अनुबंध

हर कार्ड एक अनुबंध का पालन करता है, और टूल इसी पर निर्भर करते हैं:

- `front_text` केवल एक प्रश्न या समीक्षा संकेत है और कभी भी उत्तर नहीं रखता।
- `back_text` उत्तर रखता है, वैकल्पिक रूप से एक ठोस उदाहरण के साथ।

`sql_execute` के जरिए कार्ड बनाने वाले एजेंट इस अनुबंध का पालन करते हैं, इसलिए उनके
बनाए कार्ड spaced repetition के साथ तुरंत समीक्षा योग्य होते हैं।

## प्रमाणीकरण

दो प्राधिकरण पथ एक ही प्रति-उपयोगकर्ता डेटा सतह तक पहुँचते हैं।

### OAuth 2.1 (इंटरैक्टिव कनेक्टर क्लाइंट)

सर्वर PKCE और Dynamic Client Registration के साथ authorization-code flow लागू करता है।
MCP URL को एक कस्टम कनेक्टर के रूप में जोड़ें और ब्राउज़र में अधिकृत करें;
कोई client secret पहले से साझा नहीं किया जाता। Discovery मानक है:

- Protected-resource metadata:
  `https://mcp.nibomo.com/.well-known/oauth-protected-resource`
- Authorization-server metadata:
  `https://auth.flashcards-open-source-app.com/.well-known/oauth-authorization-server`

### API key (हेडलेस और CLI)

[API संदर्भ](/hi/docs/api/) में प्रलेखित email OTP login प्रवाह के जरिए एक लंबे समय तक
मान्य रहने वाली `fca_` एजेंट API key प्राप्त करें, फिर उसे एक Bearer token के रूप में भेजें:

```text
Authorization: Bearer fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS
```

यह वही key है जिसे REST एजेंट सतह स्वीकार करती है, और इसके लिए किसी ब्राउज़र या
OAuth राउंड-ट्रिप की जरूरत नहीं होती।

दोनों पथों का प्रामाणिक मशीन-पठनीय विवरण
`https://api.flashcards-open-source-app.com/v1/` पर discovery payload है (`/v1/agent` पर भी मिरर किया गया)।

## सुरक्षा और दायरा

SQL टूल को अनुमोदित करना सुरक्षित है क्योंकि यह सतह मनमानी डेटाबेस पहुँच के बजाय एक
सीमित, पार्सर-लागू बोली है:

- **बंद स्टेटमेंट अनुमति-सूची**: `sql_query` केवल `SHOW TABLES`,
  `DESCRIBE`, `SHOW COLUMNS`, और `SELECT` स्वीकार करता है; `sql_execute` केवल `INSERT`,
  `UPDATE`, और `DELETE` स्वीकार करता है। बाकी सब कुछ पार्स के समय अस्वीकार कर दिया जाता है।
- **सीमित संसाधन**: स्टेटमेंट केवल `workspace`, `cards`, `decks`,
  और `review_events` को ही छू सकते हैं।
- **प्रति-वर्कस्पेस दायरा**: हर SQL स्टेटमेंट और समीक्षा आपकी पहुँच वाले एक
  workspace तक सीमित है, या तो आपके द्वारा दिया गया `workspaceId` या आपका चुना हुआ
  डिफ़ॉल्ट, किसी अन्य टेनेंट तक पहुँच नहीं।
- **सख्त आर्गुमेंट**: हर टूल किसी अज्ञात आर्गुमेंट को अस्वीकार करता है, इसलिए गलत वर्तनी
  वाला `workspaceId` आपके डिफ़ॉल्ट workspace पर चलने के बजाय विफल हो जाता है।
- **सीमाएँ**: प्रति स्टेटमेंट अधिकतम `100` पंक्तियाँ, प्रति बैच अधिकतम `50` स्टेटमेंट, और
  परिणाम की सीमा लगभग `12k` टोकन। म्यूटेशन बैच परमाणु रूप से लागू होते हैं।
- **पढ़ने/लिखने का विभाजन**: `sql_query`, `list_workspaces`, `get_guide`,
  `next_review_card`, और `reveal_answer` सख्ती से केवल पढ़ने के लिए हैं (`readOnlyHint`)
  और डेटा की मरम्मत, scheduling की पुनर्गणना, या कार्ड state में बदलाव कभी नहीं करते।
  `sql_execute` और `submit_review` ही एकमात्र write tools हैं (`destructiveHint`):
  `sql_execute` कार्ड और डेक लिखता है, और `submit_review` एक समीक्षा दर्ज करता है और
  उसके कार्ड का schedule आगे बढ़ाता है।

पूरा स्टैक — ऐप, बैकएंड, और इंफ्रास्ट्रक्चर — ओपन सोर्स है और इसे
[सेल्फ-होस्ट](/hi/docs/self-hosting/) किया जा सकता है, इसलिए आप वही कनेक्टर अपनी
खुद की तैनाती के विरुद्ध चला सकते हैं।

---
*[इस पेज का styled HTML संस्करण देखें](<https://nibomo.com/hi/docs/mcp-connector/>)*

*AI agent इस सेवा में उपयोगकर्ता का अकाउंट `GET https://api.flashcards-open-source-app.com/v1/` से शुरू करके बना सकते हैं। सेटअप के बाद, वे MCP के जरिए `https://mcp.nibomo.com/mcp` पर भी कनेक्ट कर सकते हैं।*

*टिप: https://nibomo.com पर किसी भी URL के अंत में `.md` जोड़ें ताकि उसका साफ़ Markdown संस्करण मिले।*