الانتقال إلى المحتوى الرئيسي

نظرة عامة

بروتوكول سياق النموذج (MCP) هو معيار مفتوح يمكّن تطبيقات الذكاء الاصطناعي من الاتصال بشكل آمن بمصادر البيانات الخارجية وواجهات برمجة التطبيقات. يوفر خادم مدفوعات دودي للمساعدين الذكيين مثل كلود، وكورسر، وغيرهم من العملاء المتوافقين مع MCP وصولاً منظمًا إلى بنية الدفع الخاصة بك. خادم Dodo Payments MCP مبني باستخدام Stainless ويستخدم بنية وضع الكود، التي تمكن وكلاء الذكاء الاصطناعي من كتابة وتنفيذ كود TypeScript ضد Dodo Payments SDK في بيئة معزولة.

القدرات الرئيسية

  • عمليات الدفع: إنشاء واسترجاع وإدارة المدفوعات والمبالغ المستردة
  • إدارة الاشتراكات: التعامل مع الفوترة المتكررة، والترقيات، والإلغاءات
  • إدارة العملاء: إدارة بيانات العملاء والوصول إلى البوابة
  • كتالوج المنتجات: إنشاء وتحديث المنتجات والأسعار والخصومات
  • إدارة التراخيص: تفعيل والتحقق وإدارة تراخيص البرمجيات
  • الفوترة بناءً على الاستخدام: تتبع والفوترة للاستخدام المقاس

كيف يعمل وضع الكود

يستخدم خادم Dodo Payments MCP وضع الكود، مما يوفر لوكيل الذكاء الاصطناعي لديك أداتين قويتين:
  1. أداة بحث الوثائق: استعلام عن الوثائق المتعلقة بـ Dodo Payments API وSDK لفهم العمليات والمعلمات المتاحة
  2. أداة تنفيذ الكود: كتابة كود TypeScript ضد SDK الذي يتم تنفيذه في بيئة آمنة معزولة بدون الوصول إلى الويب أو نظام الملفات
تمكن هذه البنية وكلاء الذكاء الاصطناعي من تنفيذ عمليات دفع معقدة ومتعددة الخطوات بشكل حتمي وقابل للتكرار.
باستخدام وضع الكود، يمكن للوكلاء ربط عدة استدعاءات API، والتعامل مع المنطق الشرطي، وإجراء الحسابات - كل ذلك في استدعاء أداة واحدة.

التثبيت

اختر طريقة التثبيت التي تناسب سير عملك.

خادم MCP عن بُعد (موصى به)

الوصول إلى خادم MCP المستضاف دون أي إعداد أو تثبيت محلي. هذه هي أسرع طريقة للبدء.
1

الوصول إلى الخادم عن بُعد

انتقل إلى https://mcp.dodopayments.com في متصفحك.
2

تكوين عميل MCP الخاص بك

انسخ تكوين JSON المقدم لعميلك المحدد. بالنسبة لـ Cursor أو Claude Desktop، أضف هذا إلى إعدادات MCP الخاصة بك:
{
  "mcpServers": {
    "dodopayments_api": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
3

المصادقة والتكوين

ستطلب منك عملية OAuth:
  • إدخال مفتاح API الخاص بـ Dodo Payments
  • اختيار بيئتك (اختبار أو مباشر)
  • اختيار نوع عميل MCP الخاص بك
احتفظ بمفتاح API الخاص بك بشكل آمن. استخدم مفاتيح وضع الاختبار أثناء التطوير.
4

إكمال الإعداد

انقر على تسجيل الدخول والموافقة لتفويض الاتصال.
بمجرد الاتصال، يمكن لمساعدك الذكي التفاعل مع Dodo Payments API نيابة عنك.

حزمة NPM

قم بتثبيت وتشغيل خادم MCP محليًا باستخدام NPM.
# Set your environment variables
export DODO_PAYMENTS_API_KEY="dodo_test_..."
export DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key"
export DODO_PAYMENTS_ENVIRONMENT="live_mode"

# Run the latest version
npx -y dodopayments-mcp@latest
استخدم @latest لسحب أحدث إصدار دائمًا، أو قم بتثبيت إصدار محدد مثل @1.0.0 من أجل الاستقرار.

Docker

قم بتشغيل خادم MCP في بيئة حاوية لنشر متسق.
# Pull the latest image
docker pull ghcr.io/dodopayments/mcp:latest

# Run the container
docker run -e DODO_PAYMENTS_API_KEY="dodo_test_..." \
  -e DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key" \
  -e DODO_PAYMENTS_ENVIRONMENT="live_mode" \
  ghcr.io/dodopayments/mcp:latest
صور Docker متاحة على GitHub Container Registry.

تكوين العميل

قم بتكوين خادم Dodo Payments MCP في عميل الذكاء الاصطناعي المفضل لديك.
قم بإعداد خادم Dodo Payments MCP في Cursor لتمكين الوصول التفاعلي إلى بيانات المدفوعات الخاصة بك.تثبيت بنقرة واحدةاستخدم الزر أدناه لتثبيت خادم MCP مباشرة في Cursor:[إضافة إلى Cursor](https://cursor.com/en-US/install-mcp?name=dodopayments-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRvZG9wYXltZW50cy1tY3AiXSwiZW52Ijp7IkRPRE9fUEFZTUVOVFNfQVBJX0tFWSI6IlNldCB5b3VyIERPRE9fUEFZTUVOVFNfQVBJX0tFWSBoZXJlLiIsIkRPRE9fUEFZTUVOVFNfV0VCSE9PS19LRVkiOiJTZXQgeW91ciBET0RPX1BBWU1FTlRTX1dFQkhPT0tfS0VZIGhlcmUuIn19)بعد النقر، قم بتعيين متغيرات البيئة الخاصة بك في إعدادات Cursor mcp.json عبر إعدادات Cursor > الأدوات وMCP > خادم MCP جديد.التكوين اليدوي
1

فتح إعدادات Cursor

انتقل إلى إعدادات Cursor > الميزات > بروتوكول سياق النموذج أو اضغط على Cmd/Ctrl + Shift + P وابحث عن “إعدادات MCP”.
2

تحرير التكوين

انقر على تحرير التكوين لفتح ملف mcp_config.json.
3

إضافة تكوين Dodo Payments

اختر أحد التكوينات التالية:الخادم عن بُعد (موصى به)
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
NPX المحلي
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "dodopayments-mcp@latest"],
      "env": {
        "DODO_PAYMENTS_API_KEY": "dodo_test_...",
        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
      }
    }
  }
}
4

حفظ وإعادة التشغيل

احفظ ملف التكوين وأعد تشغيل Cursor.
تحقق من الاتصال من خلال سؤال المساعد الذكي عن بيانات Dodo Payments الخاصة بك.

متغيرات البيئة

قم بتكوين سلوك خادم MCP باستخدام متغيرات البيئة.
المتغيرالوصفمطلوب
DODO_PAYMENTS_API_KEYمفتاح API الخاص بـ Dodo Paymentsنعم
DODO_PAYMENTS_WEBHOOK_KEYمفتاح توقيع webhook الخاص بكلا
DODO_PAYMENTS_ENVIRONMENTتعيين إلى live_mode للإنتاجلا

التشغيل عن بُعد

قم بنشر خادم MCP كخادم HTTP عن بُعد للعملاء المستندين إلى الويب أو سير العمل الوكيلة.
# Start as remote server
npx -y dodopayments-mcp --transport=http

# Specify a custom port
npx -y dodopayments-mcp --transport=http --port=3000

تكوين الخادم عن بُعد

بمجرد نشره، يمكن للعملاء الاتصال باستخدام عنوان URL للخادم:
{
  "mcpServers": {
    "dodopayments_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

رؤوس التفويض

يقبل الخادم عن بُعد المصادقة عبر الرؤوس التالية:
الرأسالوصف
Authorizationمصادقة رمز Bearer
x-dodo-payments-api-keyرأس مفتاح API مباشر

قدرات العميل

تتمتع عملاء MCP المختلفة بمستويات متفاوتة من الدعم لمواصفات MCP. يمكن للخادم ضبط مخططات الأدوات تلقائيًا للتغلب على هذه القيود.
# Auto-detect client (default)
npx dodopayments-mcp --client=infer

# Configure for specific clients
npx dodopayments-mcp --client=cursor
npx dodopayments-mcp --client=claude
npx dodopayments-mcp --client=claude-code
npx dodopayments-mcp --client=openai-agents

إعدادات العميل المتاحة

العميلالوصف
inferاكتشاف العميل تلقائيًا (افتراضي)
cursorمحرر Cursor
claudeClaude AI على الويب أو سطح المكتب
claude-codeواجهة سطر أوامر Claude Code
openai-agentsمنصة وكلاء OpenAI

تكوين القدرات اليدوية

بالنسبة للعملاء غير المدرجين أعلاه، قم بتكوين القدرات يدويًا:
# Disable $ref pointer support and set max tool name length
npx dodopayments-mcp --no-capability=refs --capability=tool-name-length=40
القدرات المتاحة:
  • top-level-unions - دعم لأنواع الاتحاد على المستوى الأعلى
  • valid-json - تحليل صحيح لوسائط سلسلة JSON
  • refs - دعم لمؤشرات $ref في المخططات
  • unions - دعم لأنواع الاتحاد (anyOf)
  • formats - دعم للتحقق من التنسيقات
  • tool-name-length=N - الحد الأقصى لطول اسم الأداة
قم بتشغيل npx dodopayments-mcp --describe-capabilities للحصول على معلومات تفصيلية حول القدرات.

تصفية الأدوات

تحكم في العمليات التي يتم عرضها لوكيل الذكاء الاصطناعي الخاص بك لتحسين الأداء والحفاظ على الأمان.

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

تقييد الوصول إلى عمليات القراءة فقط أو الكتابة.
# Only expose read operations (GET requests)
npx dodopayments-mcp --operation=read

# Only expose write operations (POST, PUT, DELETE)
npx dodopayments-mcp --operation=write
استخدم --operation=read أثناء التطوير لمنع التعديلات غير المقصودة على بياناتك.

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

تحديد الأدوات لموارد API معينة.
# Only expose payment-related tools
npx dodopayments-mcp --resource=payments

# Expose multiple resources
npx dodopayments-mcp --resource=payments --resource=customers

# Use wildcards for resource groups
npx dodopayments-mcp --resource=subscription*

تضمين أو استبعاد أدوات معينة

تعديل الأدوات الفردية المتاحة.
# Include only specific tools
npx dodopayments-mcp --tool=create_payments --tool=list_payments

# Exclude specific tools
npx dodopayments-mcp --no-tool=delete_products

# Disable the docs search tool
npx dodopayments-mcp --no-tools=docs

# List all available tools
npx dodopayments-mcp --list

دمج الفلاتر

تطبيق فلاتر متعددة في وقت واحد للتحكم الدقيق.
# Only payment and subscription read operations
npx dodopayments-mcp --operation=read --resource=payments --resource=subscriptions

تصفية معلمات استعلام URL (الخادم عن بُعد)

عند استخدام الخادم عن بُعد، قم بتطبيق الفلاتر عبر معلمات استعلام URL:
https://mcp.dodopayments.com/?operation=read
https://mcp.dodopayments.com/?resource=payments

وضع الأدوات الديناميكية

بالنسبة لـ APIs الكبيرة، يمكن أن يؤدي تحميل جميع الأدوات دفعة واحدة إلى إرباك نافذة سياق الذكاء الاصطناعي. يوفر وضع الأدوات الديناميكية بديلاً أكثر كفاءة.
npx dodopayments-mcp --tools=dynamic
في الوضع الديناميكي، تحل ثلاث أدوات ميتا محل أدوات API الفردية:
  1. list_api_endpoints - يكتشف الطرق المتاحة مع تصفية اختيارية
  2. get_api_endpoint_schema - يحصل على مخطط مفصل لطريقة معينة
  3. invoke_api_endpoint - ينفذ أي طريقة مع المعلمات المناسبة
تكون الأدوات الديناميكية مفعلة تلقائيًا لـ APIs التي تحتوي على أكثر من 50 طريقة. يمكنك تجاوز ذلك باستخدام --tools=all لتضمين جميع الأدوات.
# Use both dynamic tools and specific resources
npx dodopayments-mcp --tools=dynamic --resource=payments

الاستخدام المتقدم

التكامل البرمجي

قم ببناء خوادم MCP مخصصة أو قم بتمديد الخادم الحالي برمجيًا.
import { server, endpoints, init } from "dodopayments-mcp/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Initialize with all default endpoints
init({ server, endpoints });

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

تطوير أدوات مخصصة

قم بتمديد خادم MCP بأدواتك ومنطق الأعمال الخاص بك.
import { server, init } from "dodopayments-mcp/server";
import createPayments from "dodopayments-mcp/tools/payments/create-payments";
import { zodToJsonSchema } from "zod-to-json-schema";
import { z } from "zod";

// Define a custom tool
const customTool = {
  tool: {
    name: 'calculate_payment_total',
    description: 'Calculate payment total with tax and fees',
    inputSchema: zodToJsonSchema(
      z.object({
        amount: z.number().describe('Base amount in cents'),
        tax_rate: z.number().describe('Tax rate as decimal'),
      })
    ),
  },
  handler: async (client, args) => {
    const total = args.amount * (1 + args.tax_rate);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ total, currency: 'usd' }),
      }],
    };
  },
};

// Initialize with custom tools
init({ 
  server, 
  endpoints: [createPayments, customTool] 
});

أفضل ممارسات الأمان

احمِ بيانات اعتماد API الخاصة بك وحافظ على تكاملات آمنة.
لا تقم أبدًا بالتزام بيانات الاعتماد في التحكم في الإصدارقم بتخزين مفاتيح API في متغيرات البيئة أو أنظمة إدارة الأسرار الآمنة.
# Use environment variables
export DODO_PAYMENTS_API_KEY="dodo_test_..."

# Use a .env file (add to .gitignore)
echo "DODO_PAYMENTS_API_KEY=dodo_test_..." > .env
قم بتدوير المفاتيح بانتظامقم بإنشاء مفاتيح API جديدة بشكل دوري وألغِ صلاحية القديمة من خلال لوحة معلومات Dodo Payments الخاصة بك.استخدم مفاتيح الاختبار للتطويراستخدم دائمًا مفاتيح API في وضع الاختبار أثناء التطوير لتجنب التأثير على بيانات الإنتاج.
تطبيق تصفية الأدوات في الإنتاجقم بتقييد العمليات المعرضة فقط لما يحتاجه مساعد الذكاء الاصطناعي الخاص بك.
# Production: read-only access
npx dodopayments-mcp --operation=read

# Development: full access
npx dodopayments-mcp
تنفيذ المصادقة للخوادم عن بُعدعند النشر عن بُعد، تطلب دائمًا المصادقة عبر رأس Authorization أو رأس x-dodo-payments-api-key.مراقبة استخدام APIتتبع نشاط خادم MCP من خلال لوحة معلومات Dodo Payments الخاصة بك وقم بإعداد تنبيهات للأنماط غير العادية.
استخدم HTTPS للخوادم عن بُعدقم دائمًا بنشر خوادم MCP عن بُعد خلف نقاط نهاية HTTPS.تنفيذ تحديد المعدلاحمِ من إساءة الاستخدام من خلال تنفيذ حدود المعدل على كل من خادم MCP ومستويات API.تقييد الوصول إلى الشبكةقم بتكوين قواعد جدار الحماية لتقييد العملاء الذين يمكنهم الاتصال بخادم MCP الخاص بك.

استكشاف الأخطاء وإصلاحها

تحقق من مفتاح API الخاص بكتأكد من تعيين مفتاح API الخاص بك بشكل صحيح وأن لديه الأذونات اللازمة.
# Test your API key
curl -H "Authorization: Bearer dodo_test_..." \
  https://api.dodopayments.com/payments
تحقق من اتصال الشبكة الخاص بكتحقق من أنك تستطيع الوصول إلى نقاط نهاية Dodo Payments API.راجع سجلات العميلقم بتمكين تسجيل مفصل في عميل MCP الخاص بك لتشخيص مشكلات الاتصال.
تأكيد بيئة مفتاح APIتأكد من أنك تستخدم مفاتيح الاختبار مع نقاط نهاية الاختبار ومفاتيح مباشرة مع نقاط نهاية الإنتاج.تحقق من متغير البيئةتحقق من أن DODO_PAYMENTS_ENVIRONMENT تم تعيينه بشكل صحيح (live_mode للإنتاج).إعادة إنشاء بيانات الاعتمادإذا استمرت المشكلات، قم بإنشاء مفتاح API جديد من خلال لوحة المعلومات الخاصة بك.
تحقق من معلمات الإدخالتأكد من أن المساعد الذكي يقدم معلمات بتنسيق صحيح لكل أداة.راجع رسائل الخطأتحقق من استجابة الخطأ من API للحصول على إرشادات محددة حول ما حدث خطأ.اختبر مع API مباشرةتحقق من أن العملية تعمل عند استدعاء Dodo Payments API مباشرة عبر curl أو Postman.
جرّب إعداد عميل مختلفإذا لم تعمل الأدوات بشكل صحيح، حاول تحديد عميلك بشكل صريح:
npx dodopayments-mcp --client=cursor
تحقق من دعم القدراتبعض العملاء لا يدعمون جميع ميزات مخطط JSON. استخدم --describe-capabilities لفهم ما هو مدعوم.

الموارد