نظرة عامة

يوفّر 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 فيخص تكامل 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

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

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

لا تنسخ الرموز إلى الأوامر النصية أو سجل المحادثة أو ملفات الشيفرة المصدرية أو السجلات. احفظها فقط في مخزن بيانات الاعتماد الخاص بعميل 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 والحد المفروض لها في قاعدة البيانات.

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

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

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

الحدود

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

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

يستطيع عميل MCP المصرّح له قراءة البيانات المالية، كما يستطيع تغييرها عند منحه expenses:write. راجع سياسة الخصوصية وسياسة معالجة البيانات الخاصة بالعميل قبل توصيله.

تنطبق العناوين المستضافة أعلاه على خدمة Expense Budget Tracker المُدارة فقط. لعملية النشر الخاصة بك، ابدأ من دليل الاستضافة الذاتية واضبط نقطة اتصال MCP وبيانات تعريف OAuth لنطاقاتك. يتوفر التنفيذ في مستودع الشيفرة المصدرية.