# اتصال‌دهندهٔ 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
```

[مستندات MCP در Claude Code](https://code.claude.com/docs/en/mcp#use-mcp-servers-from-claudeai).

## نمای کلی

Nibomo یک سرور MCP (Model Context Protocol) راه‌دور اجرا می‌کند تا کلاینت‌های MCP و عامل‌های هوش مصنوعی بتوانند کارت‌هایی را که موعد مرورشان رسیده بخوانند، آن‌ها را پرسش‌به‌پرسش با شما مرور کنند و کارت‌ها و دسته‌ها را برایتان بسازند یا ویرایش کنند.

عامل‌ها از دو راه می‌توانند متصل شوند: از طریق همین سرور MCP (بهترین گزینه برای کلاینت‌های MCP مانند Claude یا Cursor)، یا از طریق [نشانی کشف Agents API](/fa/docs/api/) برای عامل‌های خط فرمان. هر دو به همان رابط دادهٔ مختص هر کاربر می‌رسند؛ این صفحه سرور MCP را پوشش می‌دهد.

از این نشانی به آن متصل شوید:

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

پروتکل انتقال Streamable HTTP است. سرور هشت ابزار برای یافتن فضاهای کاری، خواندن و نوشتن کارت‌ها و دسته‌ها، راهنماهای مرجع، مرورها و میزان استفادهٔ حساب ارائه می‌کند.

## نحوهٔ افزودن آن به کلاینت

بیشتر کلاینت‌ها سرور MCP راه‌دور را به‌عنوان یک اتصال‌دهندهٔ سفارشی اضافه می‌کنند:

1. تنظیمات اتصال‌دهنده یا سرور MCP کلاینت خود را باز کنید.
2. یک اتصال‌دهندهٔ سفارشی اضافه کنید و نشانی سرور `https://mcp.nibomo.com/mcp` را جای‌گذاری کنید.
3. در کلاینت‌های تعاملی، هر وقت از شما خواسته شد در مرورگر مجوز بدهید. سرور از OAuth 2.1 با Dynamic Client Registration استفاده می‌کند، بنابراین نه client secretی برای جای‌گذاری وجود دارد و نه لازم است ابتدا برنامه‌ای ثبت کنید.
4. برای استفادهٔ بدون رابط کاربری (headless) یا از خط فرمان، به‌جای جریان مرورگر، سرآیند `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` و `reviewedTimeZone` یادگیرنده در قالب IANA را می‌گیرد. سرور زمان مرور را ثبت می‌کند و زمان‌بندی جدید کارت را برمی‌گرداند.

ارسالی را که از نتیجه‌اش مطمئن نیستید با همان `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 را به‌عنوان یک اتصال‌دهندهٔ سفارشی اضافه کنید و در مرورگر مجوز بدهید؛ هیچ client secretی از پیش به اشتراک گذاشته نمی‌شود. کشف به روش استاندارد انجام می‌شود:

- فرادادهٔ منبع محافظت‌شده: `https://mcp.nibomo.com/.well-known/oauth-protected-resource`
- فرادادهٔ سرور مجوزدهی: `https://auth.flashcards-open-source-app.com/.well-known/oauth-authorization-server`

### کلید API (بدون رابط کاربری و خط فرمان)

یک کلید API بلندمدت عامل با پیشوند `fca_` را از طریق جریان ورود با کد یک‌بارمصرف ایمیلی که در [مرجع API](/fa/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`ی که می‌فرستید یا پیش‌فرض انتخاب‌شدهٔ شما، و هیچ دسترسی‌ای به داده‌های مستأجران دیگر وجود ندارد.
- **آرگومان‌های سخت‌گیرانه**: هر ابزار هر آرگومان ناشناخته‌ای را رد می‌کند، بنابراین اگر `workspaceId` را اشتباه بنویسید، درخواست به‌جای اجرا روی فضای کاری پیش‌فرض شما رد می‌شود.
- **سقف‌ها**: حداکثر `100` ردیف در هر دستور، حداکثر `50` دستور در هر مجموعه‌دستور (batch) و سقف نتیجه‌ای در حدود `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` یک مرور ثبت می‌کند و زمان‌بندی کارت مربوط را جلو می‌برد.

کل مجموعه، یعنی برنامه، بک‌اند و زیرساخت، متن‌باز است و می‌توان آن را [به‌صورت شخصی میزبانی کرد](/fa/docs/self-hosting/)، بنابراین می‌توانید همین اتصال‌دهنده را با استقرار خودتان به کار ببرید.

---
*[مشاهدهٔ نسخهٔ HTML قالب‌بندی‌شدهٔ این صفحه](<https://nibomo.com/fa/docs/mcp-connector/>)*

*عامل‌های هوش مصنوعی می‌توانند با شروع از `GET https://api.nibomo.com/v1/` در این سرویس برای کاربر حساب بسازند. پس از راه‌اندازی، می‌توانند از طریق MCP هم به `https://mcp.nibomo.com/mcp` وصل شوند.*

*نکته: به هر URL در https://nibomo.com پسوند `.md` اضافه کنید تا نسخهٔ تمیز Markdown آن صفحه را بگیرید.*