واجهات MCP API

نظرة عامة

تتيح واجهات MCP API الخاصة بـ Sprucely.io الوصول إلى منصة لوحات المعلومات لمساعدي الذكاء الاصطناعي وبرمجيات الجهات الخارجية عبر بروتوكول Model Context Protocol (MCP)، وهو معيار مفتوح لربط نماذج الذكاء الاصطناعي بالأدوات عبر HTTP. يمكن لأي عميل متوافق مع MCP إنشاء لوحات معلومات مُستضافة، وسردها والاطلاع على تفاصيلها، وإلحاق بيانات بها برمجياً. تنتمي لوحات المعلومات المُنشأة عبر الواجهات إلى حسابك، ويمكن مشاركتها أو تضمينها أو مواصلة تحريرها في الخدمة. للاطلاع على تعليمات تضمين لوحات المعلومات الناتجة في موقعك الخاص، راجع ملاحظات التكامل البسيط للوحة المعلومات. إذا كنت تستخدم Claude، فإن أسرع طريقة للبدء هي موصّل Sprucely.io.

الاتصال

يُقدَّم خادم MCP عبر Streamable HTTP على العنوان التالي:

https://www.sprucely.io/mcp

يمكن لأي عميل MCP الاتصال بنقطة النهاية هذه. على سبيل المثال، يسجّل أمر واحد الخادم في Claude Code:

claude mcp add --transport http sprucely https://www.sprucely.io/mcp

يمكنك أيضاً استدعاء الخادم مباشرة عبر JSON-RPC 2.0 فوق HTTP. تُنفّذ معظم عملاء MCP مصافحة البروتوكول تلقائياً؛ ويسرد الطلب أدناه الأدوات المتاحة باستخدام مفتاح API:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

المصادقة

تُخوَّل الطلبات باستخدام ترويسة Authorization Bearer قياسية. ويُدعَم نوعان من بيانات الاعتماد.

مفاتيح API - أنشئ مفاتيح API من قسم MCP في ملفك الشخصي. تبدأ المفاتيح بـ spr_mcp_، وتُعرض مرة واحدة فقط عند إنشائها، ويمكن إلغاؤها في أي وقت. استخدمها للبرامج النصية، والخوادم، وعملاء MCP التي تعمل دون واجهة مستخدم (headless).

OAuth 2.1 - يمكن لعملاء MCP التفاعليين، بدلاً من ذلك، السماح للمستخدمين بتسجيل الدخول بحساب Sprucely.io الخاص بهم عبر OAuth 2.1. يدعم خادم التفويض تدفق رمز التفويض (authorization code flow) مع PKCE (إلزامي)، ورموز التحديث (refresh tokens)، والتسجيل الديناميكي للعملاء، بحيث تُهيّئ العملاء المتوافقة نفسها تلقائياً استناداً إلى البيانات الوصفية للمورد:

https://www.sprucely.io/.well-known/oauth-protected-resource

النطاقات (scopes) المتاحة: openid وoffline_access وdashboards:read وdashboards:write. يُفرض النطاق لكل أداة على حدة: تتطلب create_dashboard وadd_data وset_sharing النطاق dashboards:write وتُرجع خطأً بدونه. أما بقية الأدوات فتحتاج إلى dashboards:read فقط.

بالنسبة للعملاء التي تتطلّب إعداداً يدوياً، فإن نقاط نهاية خادم التفويض هي:

https://www.sprucely.io/oauth/.well-known/openid-configuration - بيانات وصفية لخادم التفويض
https://www.sprucely.io/oauth/auth - نقطة نهاية التفويض (PKCE إلزامي)
https://www.sprucely.io/oauth/token - نقطة نهاية الرمز المميز
https://www.sprucely.io/oauth/reg - التسجيل الديناميكي للعملاء
https://www.sprucely.io/oauth/jwks - مفاتيح التوقيع (JWKS)
https://www.sprucely.io/oauth/token/revocation - إلغاء الرمز المميز
https://www.sprucely.io/oauth/token/introspection - فحص الرمز المميز

الأدوات

يوفّر خادم MCP ثماني أدوات: create_dashboard، get_dashboard، list_dashboards، add_data، get_dataset_schema، set_sharing، get_embed_code وstorage_status.

معاملا مجموعة البيانات ولوحة المعلومات أدناه ليسا تنسيقاً خاصاً بـ MCP - بل هما بالضبط تنسيق JSON نفسه الخاص بمجموعة البيانات/لوحة المعلومات الموثّق في صفحة تنسيق البيانات، والمستخدَم في كل مكان آخر في الخدمة (واجهة الاستيراد الخاصة ببيئة التشغيل المستقلة القابلة للتضمين، والتخطيطات المُنشأة بالذكاء الاصطناعي، ومحرر لوحة المعلومات)، لذا فإن كل ما هو موثّق في ذلك المرجع ينطبق هنا أيضاً.

create_dashboard - ينشئ لوحة معلومات مُستضافة من مجموعة بيانات مضمّنة وشجرة عناصر واجهة، ويُعيد روابط للعرض والتضمين. المعاملات:

name - عنوان لوحة المعلومات (إلزامي)
dataset - مجموعة البيانات المطلوب تمثيلها بيانياً: name، وheaders (أسماء الأعمدة)، وtypes (نوع قاعدة بيانات واحد لكل عنوان - VARCHAR أو BOOLEAN أو INTEGER أو BIGINT أو FLOAT أو DOUBLE أو DATE أو TIMESTAMP) وentries (الصفوف، كل صف مصفوفة من القيم بترتيب العناوين)، حتى 100 عمود و50,000 إدخال خام على مستوى الصف لكل استدعاء (إلزامي). يجب ألا تكون الإدخالات مُجمَّعة مسبقاً: أرسل صفاً واحداً لكل سجل أساسي، ودع dataFunction الخاصة بكل مخطط تحسب الأعداد والمجاميع والمتوسطات وما شابه عند العرض.
dashboard - من 1 إلى 40 عنصر واجهة على المستوى الأعلى، من الأعلى إلى الأسفل (إلزامي). كل عنصر واجهة هو dash_chart (نوع مخطط - area أو bar أو cell أو dot أو hexbin أو line - مع تخصيص أعمدة لـ x وy وd وr، ودالة dataFunction اختيارية، وعنوان اختياري)، أو dash_table، أو كتلة dash_text، أو dash_spacer، أو حاوية dash_stacker_hor/dash_stacker_ver. تتداخل المكدسات (stackers) بشكل متكرر - إذ يمكن أن تضم العناصر الفرعية لأي مكدس مكدسات أخرى - لترتيب عناصر الواجهة في صفوف وأعمدة بأي عمق. أما أنواع الأعمدة (تصنيفية أو مستمرة أو زمنية) التي تقبلها أبعاد x/y/d/r في كل نوع مخطط، وكيف يحوّل تجميع عمود زمني ضمن فترة متكرّرة باستخدام seasonX/seasonY ذلك العمود إلى عمود تصنيفي، فموثّق عند كل حقل عبر tools/list وفي صفحة تنسيق البيانات.
theme - ألوان اختيارية على مستوى لوحة المعلومات بأكملها (الخلفية والنص وألوان التمييز الأساسية/الخفيفة/الثانوية)؛ ويمكن لأي عنصر واجهة أن يتجاوز لونه أو خلفيته الخاصة رغم ذلك
shared - ما إذا كانت لوحة المعلومات قابلة للعرض لأي شخص يملك الرابط (اختياري، وfalse افتراضياً). تكون لوحات المعلومات الجديدة خاصة إلى أن تضبط هذا الحقل على true أو تستدعي set_sharing لاحقاً.

تحمل النتيجة قيمتي dashboardId وdatasetId الخاصتين بلوحة المعلومات الجديدة (وهما مطلوبتان لاحقاً في add_data وget_dataset_schema وset_sharing وget_embed_code)، إضافة إلى url وviewUrl ومقتطف تضمين iframe. مثال - إنشاء لوحة معلومات بمخطط أعمدة ولون تمييز على مستوى لوحة المعلومات بأكملها:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_dashboard",
      "arguments": {
        "name": "Regional Sales",
        "dataset": {
          "name": "Sales",
          "headers": ["region", "revenue"],
          "types": ["VARCHAR", "DOUBLE"],
          "entries": [
            ["North", 1250.5],
            ["South", 980.25],
            ["East", 1420.0]
          ]
        },
        "dashboard": {
          "type": "dash",
          "children": [
            { "type": "dash_chart", "chartType": "bar", "x": "region", "d": "revenue", "dataFunction": "sum", "title": "Revenue by region" }
          ]
        },
        "theme": { "themePrimary": "#6E2BDC" }
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "datasetId": "data_e5f6g7h8",
  "name": "Regional Sales",
  "shared": false,
  "rows": 3,
  "columns": 2,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

get_dashboard - يُعيد اسم لوحة المعلومات، وحالة المشاركة، ومعرّفات مجموعات البيانات، والروابط. المعامل: dashboardId (إلزامي). مثال:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_dashboard",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "name": "Regional Sales",
  "shared": false,
  "archived": false,
  "datasetIds": ["data_e5f6g7h8"],
  "source": "mcp",
  "updatedAt": "2026-07-29T10:15:00.000Z",
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

list_dashboards - يسرد لوحات المعلومات في حسابك، مرتّبة حسب آخر تحديث، ولكل منها datasetIds الخاصة بها بحيث يمكن تمرير مجموعة بيانات مباشرة إلى get_dataset_schema أو add_data دون الحاجة إلى استدعاء get_dashboard منفصل. المعاملات: limit وoffset لتقسيم النتائج إلى صفحات، وquery لتصفية الأسماء بغض النظر عن حالة الأحرف (جميعها اختيارية). مثال:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "list_dashboards",
      "arguments": {
        "limit": 10,
        "query": "sales"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "total": 1,
  "limit": 10,
  "offset": 0,
  "hasMore": false,
  "dashboards": [
    {
      "dashboardId": "dash_a1b2c3d4",
      "name": "Regional Sales",
      "shared": false,
      "datasetIds": ["data_e5f6g7h8"],
      "source": "mcp",
      "updatedAt": "2026-07-29T10:15:00.000Z",
      "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
      "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
      "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
    }
  ]
}

add_data - يُلحق إدخالات بمجموعة بيانات تابعة للوحة معلومات موجودة؛ وتتحدّث تلقائياً كل لوحة معلومات تستخدم مجموعة البيانات هذه. المعاملات:

dashboardId - لوحة المعلومات المراد الإلحاق بها (إلزامي)
entries - صفوف مطابقة من حيث الترتيب لعناوين مجموعة البيانات، حتى 50,000 لكل استدعاء (إلزامي) - وتنطبق عليها القاعدة نفسها الخاصة بالإدخالات الخام على مستوى الصف المذكورة في create_dashboard. استدعِ get_dataset_schema أولاً إذا لم تكن تعرف بالفعل أسماء أعمدة لوحة المعلومات وترتيبها الدقيق. استخدمها لتحميل مجموعات بيانات كبيرة على دفعات أو لإبقاء لوحات المعلومات محدَّثة.
run_id - مفتاح تكافؤ (idempotency key) اختياري لهذه الدفعة تحديداً (اختياري). إذا كان استدعاء سابق لـadd_data بنفس قيمتي dashboardId وrun_id قد نجح بالفعل، فإن استدعاءه مرة أخرى يُعيد تلك النتيجة السابقة بدلاً من إلحاق الصفوف مرة ثانية، بحيث يمكن إعادة محاولة إرسال الدفعة بأمان بعد انتهاء المهلة أو انقطاع الاتصال - استخدم run_id جديداً لكل دفعة مختلفة (على سبيل المثال، UUID أو قيمة تجزئة (hash) لمحتواها).

مثال:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "add_data",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4",
        "entries": [
          ["West", 875.0]
        ],
        "run_id": "batch-2026-07-29T10:20:00Z"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "datasetId": "data_e5f6g7h8",
  "addedRows": 1,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}
# Calling again later with the same dashboardId + run_id (e.g. after a dropped
# connection) is safe: the rows are not appended twice, and the response also
# carries "duplicate": true instead of appending again.

get_dataset_schema - يُعيد أسماء أعمدة مجموعة البيانات وأنواعها. استخدمها قبل استدعاء add_data (أو بناء مخطط جديد على مجموعة البيانات نفسها) كلما لم تكن أسماء الأعمدة أو ترتيبها أو أنواعها معروفة بالفعل، مثلاً في جلسة جديدة أو عندما يكون وكيل آخر قد أنشأ لوحة المعلومات. المعامل: datasetId (إلزامي). مثال:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "get_dataset_schema",
      "arguments": {
        "datasetId": "data_e5f6g7h8"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "datasetId": "data_e5f6g7h8",
  "headers": ["region", "revenue"],
  "types": ["VARCHAR", "DOUBLE"]
}

set_sharing - يُفعّل الرابط العام للوحة المعلومات أو يُعطّله. تعطيله يُلغي الوصول أيضاً عن كل مراجعة سابقة للوحة المعلومات، بحيث يتوقف عن العمل أي رابط سبقت مشاركته. المعاملان: dashboardId وshared (كلاهما إلزامي). مثال:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "set_sharing",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4",
        "shared": true
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "shared": true,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

get_embed_code - يُعيد رابط العرض القابل للمشاركة ومقتطف تضمين iframe للوحة معلومات - وهما نفس الرابط/كود التضمين اللذين تُعيدهما بالفعل create_dashboard وset_sharing، لاستخدامهما عند الحاجة إليهما مجدداً بمفردهما. لا يعمل الرابط للآخرين إلا ما دامت لوحة المعلومات مُشارَكة. المعامل: dashboardId (إلزامي). مثال:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "get_embed_code",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "shared": true,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

storage_status - يُبلغ عن مقدار مساحة التخزين التي استخدمها الحساب والمقدار المتبقي منها، وهو مفيد قبل استدعاء create_dashboard أو add_data كبير بما يكفي لأن يقترب من حد التخزين في خطتك. لا توجد معاملات. مثال:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "storage_status",
      "arguments": {}
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "used": 5242880,
  "limit": 104857600,
  "percent": 5,
  "plan": "Regular",
  "over": 0,
  "blocked": false
}

الحدود والأخطاء

تقبل نقطة نهاية MCP 25 طلباً في الدقيقة لكل عميل، وأجساد طلبات (request bodies) حتى 25 ميغابايت - حمّل مجموعات البيانات الأكبر على دفعات عبر add_data.
تقبل مجموعات البيانات حتى 100 عمود و50,000 صف لكل استدعاء، وتقبل لوحة المعلومات حتى 40 عنصر واجهة في كل مستوى من مستويات التداخل. تُحتسب لوحات المعلومات المخزَّنة ضمن حصة التخزين في خطتك - استدعِ storage_status للتحقق من المساحة المتبقية قبل استدعاء create_dashboard أو add_data كبير.
تُستخدَم رموز حالة HTTP القياسية: 401 عند غياب بيانات الاعتماد أو عدم صلاحيتها (مع تحدٍّ WWW-Authenticate يشير إلى البيانات الوصفية للمورد)، و403 عند إلغاء بيانات الاعتماد أو عدم كفايتها، و413 عند تجاوز حجم الطلب الحد المسموح، و429 عند تجاوز حد معدل الطلبات.