للمطوّرين
البروتوكول، ونقاط الاتصال، ووثائق الاكتشاف، وتسجيل العملاء، وصيغة الأخطاء في خادم MCP الخاص بـ Docshark.
لا يحتاج معظم الناس إلى هذه الصفحة، فالتطبيقات تجد كل ما فيها بنفسها. وهي هنا لمن يبني عميل MCP أو يتتبع مشكلة فيه.
الخادم
| نقطة الاتصال | https://dashboard.doc-shark.com/mcp |
| النقل | Streamable HTTP. طلبات POST بصيغة JSON-RPC 2.0؛ أرسل Accept: application/json, text/event-stream. |
| البروتوكول | 2025-11-25، مع قبول 2025-06-18 و2025-03-26 و2024-11-05، ويُتفق عليه عند initialize |
| الجلسات | بلا حالة، والردود بصيغة JSON. لا يوجد Mcp-Session-Id؛ كل طلب يحمل رمز الوصول الخاص به. |
| القدرات | tools (tools/list وtools/call) |
| وسوم الأدوات | لكل أداة title وreadOnlyHint: true أو destructiveHint: true |
| جسم الطلب | 1 ميغابايت على الأكثر |
الاكتشاف
الطلب دون رمز صالح يحصل على 401 مع:
WWW-Authenticate: Bearer resource_metadata="https://dashboard.doc-shark.com/.well-known/oauth-protected-resource/mcp", scope="docshark"| الوثيقة | العنوان |
|---|---|
| بيانات المورد المحمي (RFC 9728) | https://dashboard.doc-shark.com/.well-known/oauth-protected-resource/mcp |
| بيانات خادم التفويض (RFC 8414) | https://dashboard.doc-shark.com/.well-known/oauth-authorization-server |
خادم التفويض هو Docshark نفسه، والجهة المُصدِرة https://dashboard.doc-shark.com.
نقاط الاتصال
| النقطة | العنوان |
|---|---|
| التفويض | https://dashboard.doc-shark.com/oauth/authorize |
| الرموز | https://dashboard.doc-shark.com/oauth/token |
| التسجيل (RFC 7591) | https://dashboard.doc-shark.com/oauth/register |
| الإلغاء (RFC 7009) | https://dashboard.doc-shark.com/oauth/revoke |
العملاء
يقبل Docshark نوعين من العملاء. كلاهما عميل عام (token_endpoint_auth_method: none) ويجب أن يستخدم PKCE.
- وثائق بيانات العميل. استخدم عنوان
httpsلوثيقة بيانات عميلك قيمةً لـclient_id. يجلبها Docshark (5 كيلوبايت على الأكثر، ومهلة 3 ثوانٍ) ويقرأclient_nameوredirect_uris. هكذا يسجّل Claude وClaude Code الدخول. - التسجيل الديناميكي. أرسل
POSTإلى نقطة التسجيل معclient_name(حتى 120 حرفًا) وredirect_uris(حتى 10، كلٌّ منها حتى 2,048 حرفًا). تحصل علىclient_idيبدأ بـdsapp_.
يجب أن تكون عناوين العودة https، أو http على عنوان محلي (127.0.0.1 أو [::1] أو localhost) بأي منفذ، أو رابط التطبيق الخاص به مثل cursor:// أو vscode://. وتُرفض الروابط التي ينفّذها المتصفح (javascript: وdata: وfile: ونحوها)، والأجزاء بعد #، وبيانات الدخول داخل العنوان.
التفويض
| المعامل | القيمة |
|---|---|
response_type | code |
code_challenge_method | S256 فقط |
scope | docshark، ويمكن إضافة offline_access. يُصدر رمز تجديد دائمًا. |
resource | https://dashboard.doc-shark.com/mcp تمامًا (RFC 8707) |
state | حتى 1,024 حرفًا، ويعود دون تغيير |
يحمل الرد code وstate وiss (RFC 9207). تحقّق من أن iss يساوي الجهة المُصدِرة.
الرموز
| المنحة | ملاحظات |
|---|---|
authorization_code | يعيش الرمز 60 ثانية ويعمل مرة واحدة. أرسل redirect_uri نفسه وcode_verifier. |
refresh_token | يتبدّل مع كل استخدام. الرمز المستخدم إن عاد خلال 30 ثانية يحصل على الرد نفسه؛ وبعدها ينتهي تسجيل الدخول كله. |
تعيش رموز الوصول 3,600 ثانية (expires_in). وينتهي تسجيل الدخول بعد 90 يومًا من الموافقة مهما تجدد. أرسل رمز الوصول بصيغة Authorization: Bearer … مع كل طلب إلى /mcp.
أخطاء الرموز تتبع RFC 6749: invalid_grant وinvalid_client وinvalid_request وunsupported_grant_type، وinvalid_target عند resource خاطئ.
الأخطاء من /mcp
| الحالة | الجسم | المعنى |
|---|---|---|
401 | {"error":"invalid_token"} مع WWW-Authenticate | لا يوجد رمز، أو رمز منتهٍ، أو ربط منتهٍ. جدّد الرمز أو سجّل الدخول من جديد. |
403 | {"error":"mako_off"} | Mako متوقف في مساحة العمل. |
413 | {"error":"payload_too_large"} | جسم الطلب أكبر من 1 ميغابايت. |
429 | {"error":"rate_limited"} مع Retry-After: 60 | أكثر من 120 طلبًا في الدقيقة على هذا الربط. |
أخطاء الأدوات ليست أخطاء HTTP. تعود نتيجةً عادية مع isError: true وجملة واحدة واضحة في content.
حدود الطلبات
| النطاق | الحد |
|---|---|
| الطلبات، لكل ربط | 120 في الدقيقة |
| التغييرات، لكل ربط | 20 في الدقيقة |
| التسجيل، لكل عنوان | 120 كل 10 دقائق |
| الرموز، لكل عنوان | 1,200 في الدقيقة |
| الإلغاء، لكل عنوان | 300 في الدقيقة |
| وثائق الاكتشاف، لكل عنوان | 1,200 في الدقيقة |
| الطلبات دون رمز، لكل عنوان | 1,200 في الدقيقة |
جرّبه
npx @modelcontextprotocol/inspectorاختر Streamable HTTP، وأدخل عنوان الخادم، واضغط Connect. يسجّل الأداة الدخول عبر متصفحك ويعرض الأدوات التي يفتحها دورك.