# موصّل MCP

## نظرة عامة

يوفّر Expense Budget Tracker موصّلًا مستضافًا لبروتوكول Model Context Protocol ‏(MCP) على العنوان:

`https://mcp.expense-budget-tracker.com/mcp`

تستخدم نقطة الاتصال Streamable HTTP وOAuth. قدّم هذا العنوان إلى عميل MCP يدعم خوادم Streamable HTTP البعيدة واكتشاف OAuth. يفتح مسار التفويض المتصفح لتسجيل الدخول والموافقة على الوصول.

لا يستخدم الموصّل مفتاح API. رموز الوصول والتحديث الخاصة بـ OAuth هي بيانات اعتماد MCP. أما `ApiKey` طويل الأمد الموضّح في [مرجع Agent API](/ar/docs/api/) فيخص تكامل HTTP مباشرًا ومنفصلًا، ولا تقبله نقطة اتصال MCP.

## اكتشاف OAuth والاتصال

ينشر الموصّل المستضاف بيانات تعريف المورد المحمي على العنوان:

`https://mcp.expense-budget-tracker.com/.well-known/oauth-protected-resource/mcp`

توجّه هذه البيانات العميل إلى خادم التفويض. تتوفر بيانات تعريف ذلك الخادم على العنوان:

`https://auth.expense-budget-tracker.com/.well-known/oauth-authorization-server`

يتبع العميل المتوافق المسار التالي:

1. يتصل بـ `https://mcp.expense-budget-tracker.com/mcp` ويكتشف بيانات تعريف المورد المحمي.
2. يسجّل نفسه ديناميكيًا كعميل OAuth عام. لا يُستخدم سر للعميل.
3. يبدأ مسار Authorization Code ويفتح عنوان التفويض في متصفح المستخدم.
4. يستخدم PKCE في كل طلب تفويض. طريقة تحدي الرمز الوحيدة المدعومة هي `S256`.
5. يطلب `expenses:read`. ولا يضيف `expenses:write` إلا عند الحاجة إلى استدعاء `sql_execute`.
6. يستبدل رمز التفويض برمزي الوصول والتحديث، ثم يجدّد الوصول عند الحاجة.

لا تنسخ الرموز إلى الأوامر النصية أو سجل المحادثة أو ملفات الشيفرة المصدرية أو السجلات. احفظها فقط في مخزن بيانات الاعتماد الخاص بعميل MCP.

## نطاقات الوصول

- `expenses:read` إلزامي. يتيح اكتشاف مساحات العمل وفحص المخطط وتنفيذ استعلامات للقراءة فقط.
- `expenses:write` اختياري. يتيح بشكل منفصل أداة `sql_execute` التخريبية.

اطلب أصغر مجموعة نطاقات تكفي للمهمة. على العميل الذي يحلل البيانات أو ينشئ التقارير فقط أن يطلب `expenses:read` من دون `expenses:write`.

## الأدوات

### `list_workspaces`

تسرد مساحات العمل المتاحة للمستخدم الذي سجّل الدخول. استخدم معرّف مساحة العمل المُعاد لتحديد الهدف صراحةً قبل قراءة البيانات أو تغييرها.

### `get_schema`

تعيد العلاقات والأعمدة التي يتيحها MCP في مساحة العمل المحددة. استدعها قبل كتابة SQL بدلًا من افتراض أسماء الجداول أو الأعمدة.

### `sql_query`

تنفّذ استعلام SQL واحدًا مقيّدًا ومخصصًا للقراءة فقط في مساحة العمل المحددة. يُفرض على مسار الاستعلام أيضًا حد للقراءة فقط على مستوى قاعدة البيانات. تقتصر النتائج على 100 صف، والمهلة النهائية للتنفيذ 20 ثانية.

### `sql_execute`

تنفّذ SQL مقيّدًا يغيّر البيانات في مساحة العمل المحددة. هذه الأداة تخريبية وتتطلب النطاق المنفصل `expenses:write`. أكّد مساحة العمل وراجع العبارة كاملةً قبل الموافقة على الاستدعاء.

خادم MCP كاملًا ليس مخصصًا للقراءة فقط لأنه يوفّر `sql_execute`. تنطبق ضمانات القراءة فقط تحديدًا على `sql_query` والحد المفروض لها في قاعدة البيانات.

## الاستخدام الآمن

1. استدعِ `list_workspaces` وأكّد مساحة العمل المطلوبة مع المستخدم.
2. استدعِ `get_schema` قبل إنشاء SQL.
3. استخدم `sql_query` للفحص وحساب الإجماليات والمطابقة والتقارير.
4. اطلب `expenses:write` فقط للمهمة التي يجب أن تغيّر البيانات.
5. قبل `sql_execute`، اعرض العبارة كاملةً وأثرها المتوقع، ثم أكّد مساحة العمل مرة أخرى.
6. بعد الكتابة، استخدم `sql_query` للتحقق من النتيجة.

يقيّد الخادم نطاق SQL والعلاقات المتاحة. تكمل هذه الضوابط المراجعة الدقيقة لعبارات SQL المنشأة ولا تحل محلها.

## الحدود

- 100 صف كحد أقصى في نتائج SQL
- مهلة تنفيذ نهائية قدرها 20 ثانية
- يقتصر الوصول على مساحات العمل المتاحة للمستخدم الذي سجّل الدخول
- تستخدم `sql_query` نطاق SQL مقيّدًا وحدًا للقراءة فقط في قاعدة البيانات
- تتطلب `sql_execute` النطاق `expenses:write` بالإضافة إلى نطاق القراءة الإلزامي

## الخصوصية والاستضافة الذاتية

يستطيع عميل MCP المصرّح له قراءة البيانات المالية، كما يستطيع تغييرها عند منحه `expenses:write`. راجع [سياسة الخصوصية](/ar/privacy/) وسياسة معالجة البيانات الخاصة بالعميل قبل توصيله.

تنطبق العناوين المستضافة أعلاه على خدمة Expense Budget Tracker المُدارة فقط. لعملية النشر الخاصة بك، ابدأ من [دليل الاستضافة الذاتية](/ar/docs/self-hosting/) واضبط نقطة اتصال MCP وبيانات تعريف OAuth لنطاقاتك. يتوفر التنفيذ في [مستودع الشيفرة المصدرية](https://github.com/kirill-markin/expense-budget-tracker).

---
*[عرض نسخة HTML المنسقة من هذه الصفحة](https://expense-budget-tracker.com/ar/docs/mcp-connector/)*

*يمكن لعملاء MCP البعيدين الذين يدعمون OAuth الاتصال بـ `https://mcp.expense-budget-tracker.com/mcp` باستخدام وصول OAuth Bearer. النطاق الإلزامي هو `expenses:read`. ويمكن للعميل أيضًا طلب النطاق الاختياري `expenses:write`؛ ويظهر في شاشة موافقة OAuth ويلزم لإجراء التعديلات.*

*يمكن للوكلاء عبر سطر الأوامر وHTTP المباشر استخدام Agent API المنفصل بدءًا من `GET https://api.expense-budget-tracker.com/v1/` واتباع استجابة الاكتشاف للحصول على ApiKey.*

*تلميح: أضف `.md` إلى أي رابط في هذا الموقع للحصول على نسخة Markdown نظيفة من الصفحة.*