نشر خادم بروتوكول Didit MCP ذاتيًا

النقاط الرئيسية

• خادم بروتوكول سياق نموذج Didit (MCP) مفتوح المصدر بموجب ترخيص MIT. يمكنك بناؤه من مستودع GitHub العام وتشغيله باستخدام Docker أو Node.js أو نقل stdio بدون رأس.
• تغير الاستضافة الذاتية مكان تشغيل عملية MCP، وليس كيفية وصولها إلى Didit. تقوم كل وضعية بالمصادقة كمستخدم Didit باستخدام رمز وصول Bearer. لا يوجد وضع مفتاح API للتطبيق لأدوات MCP.
• يحتوي الكتالوج المستضاف ذاتيًا الكامل على 121 أداة. يتعمد نقطة نهاية Open Authorization (OAuth) المستضافة عرض 115 أداة. تتضمن الأمثلة في المصدر الحالي didit_context_get، didit_session_create، و didit_transaction_screen_wallet.
• نقطة الدخول HTTP عديمة الحالة وتقبل حركة مرور MCP عبر طلبات POST. يتم إنشاء خادم ونقل جديدين لكل طلب، لذلك لا يحتاج موازن التحميل إلى تقارب الجلسة.
• استخدم /healthz لفحوصات الحاوية وموازن التحميل. قم بتكوين URI المورد العام، وأصل التخويل، ووضع التحقق من الرمز المميز، والأسرار بشكل صريح قبل عرض الخدمة.

نقطة النهاية المستضافة مريحة، ولكنها ليست الخيار التشغيلي الصحيح لكل فريق. قد تحتاج المؤسسة إلى الاحتفاظ بالتكامل داخل حدود شبكتها الخاصة، أو التحكم في صورة وقت التشغيل، أو توجيه حركة المرور عبر طبقة خروج خاصة، أو تطبيق سياسات المراقبة وإدارة التغيير الخاصة بها. يدعم مستودع Didit MCP نموذج النشر هذا دون إنشاء سطح منتج منفصل.

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

اختر نقطة الدخول HTTP أو stdio

يبني المستودع كتالوج أدوات مشتركًا واحدًا مع نقطتي دخول. يشغل dist/http.js خادم موارد Express عبر HTTP قابل للبث وعديم الحالة. إنه الخيار الصحيح لخدمة مشتركة تصل إليها عدة عملاء MCP أو حاويات أو مستخدمين. يشغل dist/index.js عبر stdio وهو مخصص لعملية محلية بدون رأس يتم تشغيلها بواسطة عميل واحد.

تستدعي نقطتا الدخول نفس منطق الإرسال، ويعرض الإصدار 5 أدوات MCP فقط — وليس موارد MCP أو مطالبات. تقوم كلتا النقطتين بالمصادقة على طلبات الخادم كمستخدم Didit. الفرق هو كيفية وصول بيانات اعتماد المستخدم هذه إلى العملية: تتلقى نقطة الدخول HTTP وتتحقق من صحة رمز Bearer OAuth الخاص بالمتصل؛ تقرأ نقطة الدخول stdio رمز Bearer للمستخدم من DIDIT_ACCESS_TOKEN.

الاستضافة الذاتية لا تعني عدم وجود بيانات اعتماد: لا يزال MCP يعمل كمستخدم Didit، وتطبق Didit دور مؤسسة هذا المستخدم وأذوناته على كل استدعاء أداة.

البناء والتشغيل باستخدام Docker

يتضمن المستودع Dockerfile متعدد المراحل يعتمد على Node 20. تقوم مرحلة البناء بتثبيت تبعيات التطوير، وتجميع TypeScript، وتقليم حزم التطوير. تعمل مرحلة الإنتاج كمستخدم node غير جذري وتتضمن فحص سلامة الحاوية.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env

docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp

قبل بدء الحاوية، استبدل الإعدادات الافتراضية المستضافة التي تحدد نشرك. على الأقل، قم بتعيين MCP_RESOURCE_URI إلى الأصل العام الذي يصل من خلاله العملاء إلى خادم الموارد هذا، ثم قم بتوفير بيانات اعتماد عميل OAuth اللازمة لفحص الرمز المميز. احتفظ بالأسرار في مدير أسرار منصة الحاوية الخاصة بك بدلاً من الالتزام بملف .env المعبأ.

MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=replace-with-client-id
MCP_OAUTH_CLIENT_SECRET=replace-with-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

قم بإنهاء أمان طبقة النقل (TLS) عند مدخلك أو موازن التحميل، وقم بإعادة توجيه طلبات MCP POST إلى المنفذ 3000، واحتفظ برأس Authorization. يجب أن يتطابق MCP_RESOURCE_URI المرئي خارجيًا مع هوية المورد المعلن عنها للعملاء؛ لا تترك URI Didit المدار في مكانه لأصل عام مختلف.

البناء والتشغيل مباشرة باستخدام Node.js

إذا كانت منصتك تدير بالفعل وقت تشغيل Node، فاستخدم نفس نقطة الدخول HTTP بدون حاوية. الحزمة خاصة ولا يتم توزيعها عبر npm، لذا استنسخ المستودع بدلاً من محاولة تنفيذ حزمة منشورة.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js

تقرأ العملية نفس متغيرات البيئة مثل الحاوية. قم بتشغيلها تحت مشرف العمليات الخاص بك، وقم بحقن الأسرار من خلال بيئة النشر، وقم بتوجيه نقاط النهاية المطلوبة فقط. تذهب طلبات MCP إلى POST /mcp. ترفض الخدمة عمدًا GET و DELETE على هذا المسار لأنها لا تحتفظ بجلسات MCP أو تدفقات تبدأها الخادم.

لا يقوم Node.js بتحميل ملف .env الخاص بالمستودع تلقائيًا. قم بتصدير القيم في shell، أو حقنها من خلال مدير الخدمة، أو استخدم دعم ملفات البيئة في منصتك قبل بدء dist/http.js. لاحظ أيضًا أن npm start يشغل نقطة الدخول stdio؛ استخدم node dist/http.js أو npm run start:http لـ HTTP.

التشغيل بدون رأس عبر stdio

بالنسبة لوكيل محلي، أو مشغل بناء، أو عملية معزولة لعميل واحد، استخدم نقطة الدخول stdio. قم بتوفير رمز وصول للمستخدم عبر البيئة ودع عميل MCP يمتلك دورة حياة العملية.

DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js

هذا الرمز المميز هو بيانات اعتماد Bearer للمستخدم، وليس بيانات اعتماد تطبيق. قم بتخزينه كسر، واحتفظ به بعيدًا عن سجلات shell والسجلات، وقم بتدويره وفقًا لسياسة الوصول الخاصة بك. إذا كان أحد النشرات يعمل دائمًا في مؤسسة أو تطبيق واحد، يمكن لـ MCP_DEFAULT_ORG و MCP_DEFAULT_APP توفير هذا النطاق الافتراضي. بخلاف ذلك، يمكن للأدوات حل النطاق من الوسائط الصريحة أو سياق الطلب المصادق عليه.

لا يزال لا يوجد وضع مفتاح API للتطبيق في stdio. تستدعي كل من HTTP المستضافة ذاتيًا و stdio المستضافة ذاتيًا نقاط نهاية وحدة تحكم Didit ذات النطاق الخاص بالمستخدم، لذلك لا يمكن لمفتاح التطبيق أن يحل محل رمز Bearer للمستخدم.

تكوين سطح البيئة الكامل

يدعم src/config.ts الحالي المتغيرات التالية. يجب أن تحتفظ معظم عمليات النشر بإعدادات Didit API الافتراضية والترخيص الافتراضية للإنتاج وتجاوز فقط هوية المورد وتكوين التحقق والأسرار اللازمة لتخطيطها.

متغيرات مشتركة و stdio

• DIDIT_ACCESS_TOKEN: رمز Bearer للمستخدم لوضع stdio بدون رأس؛ لا يوجد افتراضي.
• DIDIT_API_BASE_URL: قاعدة API للتحقق؛ الافتراضي هو https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: قاعدة API للمصادقة؛ الافتراضي هو https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG و MCP_DEFAULT_APP: افتراضات المؤسسة والتطبيق الاختيارية لعمليات النشر أحادية المستأجر.

متغيرات خادم موارد HTTP

• MCP_PORT: منفذ الاستماع؛ الافتراضي هو 3000.
• MCP_RESOURCE_URI: URI لخادم الموارد العام؛ الافتراضي هو https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: أصل خادم التخويل؛ الافتراضي هو https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: introspection افتراضيًا، أو jwks عندما تصدر خدمة التخويل رموز ويب JSON (JWTs) مناسبة للتحقق من التوقيع المحلي.
• MCP_OAUTH_CLIENT_ID و MCP_OAUTH_CLIENT_SECRET: لا توجد افتراضات؛ تُستخدم كبيانات اعتماد HTTP Basic لفحص Request for Comments (RFC) 7662.
• MCP_OAUTH_INTROSPECT_URL: الافتراضي هو https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: نطاقات اكتشاف مفصولة بمسافات؛ الافتراضي هو didit:management didit:verification.

تجاوزات بيانات تعريف التخويل

• DIDIT_AUTH_ISSUER: الافتراضي هو MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: مستند اكتشاف OpenID Connect (OIDC)؛ الافتراضي هو أصل التخويل بالإضافة إلى /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: نقطة نهاية JSON Web Key Set (JWKS)؛ الافتراضي هو https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: الافتراضي هو أصل التخويل بالإضافة إلى /authorize.
• DIDIT_OIDC_TOKEN_URL: الافتراضي هو أصل التخويل بالإضافة إلى /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: الافتراضي هو أصل التخويل بالإضافة إلى /api/auth/oauth-register.

استخدم introspection لرموز الوصول المعتمة. يرسلها الخادم إلى نقطة نهاية الفحص المكونة باستخدام MCP_OAUTH_CLIENT_ID و MCP_OAUTH_CLIENT_SECRET. استخدم jwks فقط عندما يتم تكوين خدمة التخويل الخاصة بك لإصدار رموز وصول JWT موقعة لهذا العميل؛ ثم يتحقق الخادم من التوقيعات مقابل DIDIT_JWKS_URL. لا يؤدي تغيير وضع التحقق إلى إنشاء نموذج هوية مختلف: يظل المدير المتحقق منه مستخدم Didit.

يمكن لعملاء MCP استخدام تسجيل العميل الديناميكي (DCR) مع Didit Business Console أثناء تدفق التخويل الخاص بهم. يختلف تسجيل العميل هذا عن MCP_OAUTH_CLIENT_ID و MCP_OAUTH_CLIENT_SECRET الخاصين بخادم الموارد، واللذين يصادقان طلبات الفحص. قم بتوفير بيانات الاعتماد من جانب الخادم هذه من خلال قناة نشر Didit المناسبة بدلاً من افتراض أن تسجيل العميل يمكن أن يحل محلها.

فحوصات السلامة والتوسع عديم الحالة

تعرض عملية HTTP GET /healthz وتُرجع JSON يحتوي على status و service و version. تتحقق صورة Docker بالفعل منها كل 30 ثانية بعد فترة بدء تشغيل مدتها 15 ثانية. يمكنك استخدام نفس نقطة النهاية لاستعداد Kubernetes، أو مجموعة هدف لموازن تحميل التطبيق، أو فحص خارجي لوقت التشغيل.

curl -fsS http://localhost:3000/healthz

مسار MCP عديم الحالة حسب التصميم. لكل POST مصادق عليه، تنشئ العملية خادمًا جديدًا ونقل HTTP قابل للبث مع تعطيل إنشاء الجلسة، وتمرر بيانات اعتماد المتصل التي تم التحقق من صحتها عبر سياق كل طلب، وتكمل الإرسال، وتغلق النقل. لا توجد جلسة في الذاكرة يجب أن يجدها طلب لاحق على نفس النسخة المتماثلة.

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

نتيجة لذلك، لا تحتاج النسخ المتماثلة الأفقية إلى جلسات لاصقة. يمكن لأي مثيل سليم التعامل مع POST التالي، ولا تتطلب عمليات النشر المتتالية استنزاف الجلسة بما يتجاوز معالجة الطلبات العادية قيد التنفيذ. يجب أن يركز تخطيط السعة على توازي الطلبات، وزمن الوصول إلى Didit API، وسياسة المهلة وإعادة المحاولة العادية الخاصة بك.

التحقق قبل عرض الخدمة

• تأكد من نجاح /healthz من نفس مسار الشبكة مثل موازن التحميل.
• تأكد من أن طلبات MCP غير المصادق عليها تتلقى تحدي تخويل بدلاً من إخراج الأداة.
• أكمل تدفق OAuth 2.1 باستخدام مفتاح إثبات لتبادل الكود (PKCE)، ثم استدع didit_context_get للتحقق من أن المؤسسات والتطبيقات المتوقعة مرئية.
• راجع وثائق MCP المتقدمة قبل تغيير نقاط نهاية الاكتشاف أو التحقق من الرمز المميز.
• استخدم صفحة مطور Didit MCP للسطح المدار المدعوم والروابط الحالية.

إذا لم تعد الاستضافة الذاتية مطلبًا، فإن نقطة النهاية المدارة تزيل عمليات خادم موارد وقت التشغيل و OAuth الموصوفة أعلاه. يمكن لمستخدمي Claude إضافتها باستخدام رابط Didit connector العميق. سواء قمت بتشغيل العملية أو قامت Didit بذلك، فإن القاعدة الأساسية متطابقة: عمليات MCP تصادق كمستخدم Didit، وليس كمفتاح API للتطبيق أبدًا.