> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorbit.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# خادم Gorbit MCP

> ربط LLMs مثل Claude و Cursor وأدوات AI الأخرى بقاعدة معرفة Gorbit عبر بروتوكول سياق النموذج

## نظرة عامة

يتيح خادم Gorbit MCP لأي عميل LLM متوافق مع MCP (Claude Desktop، Claude Code، Cursor، Windsurf، إلخ)
الوصول إلى قاعدة معرفة Gorbit، والبحث على الويب،
وإمكانيات جلب عناوين URL من خلال [بروتوكول سياق النموذج](https://modelcontextprotocol.io/).

## المتطلبات الأساسية

قبل الاتصال، ستحتاج إلى:

* **مثيل Gorbit قيد التشغيل** (إما مستضاف ذاتيًا أو Gorbit Cloud)
* **المصادقة** — راجع [رموز الوصول الشخصية](/developers/overview#personal-access-tokens)
  أو [مفاتيح API](/admins/user_management/api_keys)
* **عميل متوافق مع MCP** (Claude Desktop، Claude Code، Cursor، إلخ)

<Card title="تكوين خادم MCP المستضاف ذاتيًا" icon="server" href="#self-hosted-configuration">
  انتقل إلى متغيرات البيئة، والشبكات، وإعدادات النشر لخادم MCP المستضاف ذاتيًا
</Card>

## البداية السريعة

### Claude Code (CLI)

```bash theme={null}
claude mcp add --transport http gorbit https://cloud.gorbit.app/mcp \
  --header "Authorization: Bearer YOUR_GORBIT_TOKEN_HERE"
```

أو أضفه إلى ملف `.mcp.json` الخاص بمشروعك:

```json theme={null}
{
  "mcpServers": {
    "gorbit": {
      "type": "http",
      "url": "https://cloud.gorbit.app/mcp",
      "headers": {
        "Authorization": "Bearer ${GORBIT_TOKEN}"
      }
    }
  }
}
```

ثم اضبط متغير البيئة قبل تشغيل Claude Code:

```bash theme={null}
export GORBIT_TOKEN="your-token-here"
claude
```

### Claude Desktop

أضف ما يلي إلى ملف تكوين Claude Desktop:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "gorbit": {
      "url": "https://cloud.gorbit.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GORBIT_TOKEN_HERE"
      }
    }
  }
}
```

<Tip>
  استبدل `https://cloud.gorbit.app/mcp` بـ `http://YOUR_GORBIT_DOMAIN:8090/` إذا كنت تستضيف ذاتيًا.
</Tip>

### Cursor / Windsurf / عملاء MCP الآخرون

تدعم معظم عملاء MCP نقل HTTP مع رؤوس مخصصة. تفاصيل الاتصال هي:

| الإعداد         | القيمة                                                         |
| --------------- | -------------------------------------------------------------- |
| **URL**         | `https://cloud.gorbit.app/mcp` (أو `http://YOUR_DOMAIN:8090/`) |
| **Transport**   | HTTP (Streamable HTTP)                                         |
| **Auth Header** | `Authorization: Bearer YOUR_TOKEN`                             |

راجع وثائق MCP الخاصة بعميلك للخطوات الدقيقة للتكوين.

## الأدوات المتاحة

يعرض خادم MCP ثلاث أدوات يمكن لعملاء LLM استدعاؤها:

<AccordionGroup>
  <Accordion title="search_indexed_documents" icon="magnifying-glass">
    ابحث في قاعدة المعرفة الخاصة بك المفهرسة في Gorbit. يعيد قطع مستندات مرتبة بالمحتوى، ودرجات الصلة،
    والبيانات الوصفية.

    **المعاملات:**

    | المعامل        | النوع     | مطلوب | الافتراضي    | الوصف                                                           |
    | -------------- | --------- | ----- | ------------ | --------------------------------------------------------------- |
    | `query`        | string    | نعم   | —            | استعلام بحث باللغة الطبيعية                                     |
    | `source_types` | string\[] | لا    | جميع المصادر | تصفية حسب نوع الموصل (مثلاً `["confluence", "github", "jira"]`) |
    | `time_cutoff`  | string    | لا    | لا قطع       | تاريخ ووقت ISO 8601 — إرجاع المستندات المحدثة بعد هذا الوقت فقط |
    | `limit`        | integer   | لا    | `10`         | الحد الأقصى لعدد النتائج للإرجاع                                |

    **مثال استدعاء:**

    ```json theme={null}
    {
      "query": "What is the latest status of PROJ-1234?",
      "source_types": ["jira", "google_drive"],
      "time_cutoff": "2025-01-01T00:00:00Z",
      "limit": 5
    }
    ```

    **حقول الاستجابة:**

    | الحقل                             | الوصف                                              |
    | --------------------------------- | -------------------------------------------------- |
    | `documents`                       | مصفوفة كائنات النتائج                              |
    | `documents[].semantic_identifier` | اسم المستند القابل للقراءة                         |
    | `documents[].content`             | مقطع نصي ذو صلة                                    |
    | `documents[].source_type`         | مصدر الموصل (مثلاً `"confluence"`)                 |
    | `documents[].link`                | رابط إلى المستند الأصلي                            |
    | `documents[].score`               | درجة الصلة                                         |
    | `total_results`                   | عدد النتائج المرجعة                                |
    | `query`                           | الاستعلام الأصلي                                   |
    | `executed_queries`                | قائمة الاستعلامات المنفذة فعليًا (قد تشمل توسيعات) |

    <Tip>
      لاكتشاف أنواع المصادر المتاحة، استخدم مورد `indexed_sources` (انظر أدناه).
    </Tip>
  </Accordion>

  <Accordion title="search_web" icon="globe">
    ابحث في الإنترنت العام للمعرفة العامة والأحداث الجارية.

    **المعاملات:**

    | المعامل | النوع   | مطلوب | الافتراضي | الوصف                    |
    | ------- | ------- | ----- | --------- | ------------------------ |
    | `query` | string  | نعم   | —         | استعلام البحث            |
    | `limit` | integer | لا    | `5`       | الحد الأقصى لعدد النتائج |

    **مثال استدعاء:**

    ```json theme={null}
    {
      "query": "React 19 migration guide",
      "limit": 5
    }
    ```

    **حقول الاستجابة:**

    | الحقل               | الوصف                  |
    | ------------------- | ---------------------- |
    | `results`           | مصفوفة نتائج بحث الويب |
    | `results[].title`   | عنوان الصفحة           |
    | `results[].url`     | رابط الصفحة            |
    | `results[].snippet` | مقطع نصي قصير          |
    | `query`             | الاستعلام الأصلي       |

    <Note>
      `search_web` يعيد مقاطع، لا محتوى الصفحة الكامل. استخدم `open_urls` لجلب النص الكامل لأي نتيجة.
    </Note>
  </Accordion>

  <Accordion title="open_urls" icon="link">
    استرجع محتوى النص الكامل من رابط ويب واحد أو أكثر.

    **المعاملات:**

    | المعامل | النوع     | مطلوب | الوصف                  |
    | ------- | --------- | ----- | ---------------------- |
    | `urls`  | string\[] | نعم   | قائمة عناوين URL للجلب |

    **مثال استدعاء:**

    ```json theme={null}
    {
      "urls": [
        "https://react.dev/blog/2024/12/05/react-19",
        "https://react.dev/learn/react-compiler"
      ]
    }
    ```

    **حقول الاستجابة:**

    | الحقل               | الوصف                      |
    | ------------------- | -------------------------- |
    | `results`           | مصفوفة الصفحات المجلوبة    |
    | `results[].title`   | عنوان الصفحة               |
    | `results[].url`     | الرابط المجلوب             |
    | `results[].content` | محتوى النص المستخرج الكامل |
  </Accordion>
</AccordionGroup>

## الموارد المتاحة

<AccordionGroup>
  <Accordion title="indexed_sources" icon="database">
    **URI:** `resource://indexed_sources`

    يسرد جميع أنواع موصلات المستندات المفهرسة حاليًا في مثيل Gorbit (مثلاً `"confluence"`، `"github"`،
    `"google_drive"`، `"slack"`).

    استخدم هذا لاكتشاف القيم الصالحة لفلتر `source_types` في `search_indexed_documents`.

    **مثال استجابة:**

    ```json theme={null}
    {
      "indexed_sources": ["confluence", "github", "google_drive", "jira", "slack"]
    }
    ```
  </Accordion>
</AccordionGroup>

## تكوين الاستضافة الذاتية

لاستضافة خادم MCP ذاتيًا، ستحتاج إلى تفعيل النشر عبر متغيرات البيئة.

Docker:

```bash .env theme={null}
MCP_SERVER_ENABLED=true
```

Kubernetes:

```yaml values.yaml theme={null}
configMap:
  MCP_SERVER_ENABLED: "true"
```

### فحص الصحة

تحقق من أن خادم MCP يعمل:

```bash theme={null}
curl http://localhost:8090/health # أو http://YOUR_DOMAIN:8090/health
```

الاستجابة المتوقعة:

```json theme={null}
{
  "status": "healthy",
  "service": "mcp_server"
}
```

### متغيرات البيئة

<Info>
  معظم المستخدمين لا ينبغي أن يحتاجوا لتكوين متغيرات البيئة هذه.
</Info>

| المتغير                                     | الافتراضي   | الوصف                                                                                |
| ------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `MCP_SERVER_ENABLED`                        | `false`     | اضبط على `"true"` لتفعيل خادم MCP                                                    |
| `MCP_SERVER_HOST`                           | `0.0.0.0`   | المضيف لربط خادم MCP                                                                 |
| `MCP_SERVER_PORT`                           | `8090`      | منفذ خادم MCP                                                                        |
| `MCP_SERVER_CORS_ORIGINS`                   | (فارغ)      | قائمة مفصولة بفواصل لأصول CORS المسموح بها                                           |
| `API_SERVER_PROTOCOL`                       | `http`      | البروتوكول لاتصال خادم API الداخلي                                                   |
| `API_SERVER_HOST`                           | `127.0.0.1` | اسم المضيف لاتصال خادم API الداخلي                                                   |
| `API_SERVER_URL_OVERRIDE_FOR_HTTP_REQUESTS` | (غير محدد)  | تجاوز رابط كامل لخادم API. استخدم هذا عند استضافة خادم MCP ذاتيًا مقابل Gorbit Cloud |

## التصحيح والاختبار

### فاحص MCP

[فاحص MCP](https://github.com/modelcontextprotocol/inspector) هو أداة تصحيح تفاعلية لخوادم MCP:

```bash theme={null}
npx @modelcontextprotocol/inspector
```

**الإعداد في الفاحص:**

* تجاهل قوائم تكوين OAuth
* افتح تبويب **Authentication**
* اختر مصادقة **Bearer Token**
* الصق رمز Gorbit PAT أو مفتاح API
* انقر **Connect**

بمجرد الاتصال، يمكنك تصفح الأدوات، واختبار الاستدعاءات بمعاملات مختلفة، وفحص حمولات الطلب/الاستجابة.

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="رموز الوصول الشخصية" icon="key" href="/developers/overview#personal-access-tokens">
    أنشئ رمزًا للمصادقة مع خادم MCP
  </Card>

  <Card title="مفاتيح API" icon="shield-check" href="/admins/user_management/api_keys">
    أنشئ مفاتيح API مشتركة لوصول MCP على مستوى الفريق
  </Card>

  <Card title="الموصلات" icon="plug" href="/admins/connectors/overview">
    أضف مصادر بيانات لجعل معرفتك قابلة للبحث عبر MCP
  </Card>

  <Card title="إجراءات MCP" icon="diagram-project" href="/admins/actions/mcp">
    اربط Gorbit بخوادم MCP الخارجية كعميل
  </Card>
</CardGroup>