توثيق API - MD-2-PDF v2.0

نظرة عامة

MD-2-PDF هي أداة سحابية لتحويل نصوص Markdown إلى ملفات PDF احترافية مع دعم كامل للغة العربية (RTL)، المعادلات الرياضية (LaTeX)، تلوين الأكواد، ومخططات PlantUML.

الرابط الأساسي: https://md-2-pdf.pages.dev

معلومات سريعة

الإصدار	2.0.0
المنصة	Cloudflare Pages + Workers
تنسيق الطلبات	JSON (`Content-Type: application/json`)
البروتوكول	HTTPS فقط
رمز المصدر	GitHub Repository

المميزات

🔤 دعم RTL

دعم كامل للغة العربية والاتجاه من اليمين لليسار

📐 LaTeX

معادلات رياضية سطرية ( $x^2$ ) وعرضية ($$...$$)

🎨 تلوين الأكواد

Syntax Highlighting لـ JavaScript, Python, CSS, SQL وأكثر

📊 PlantUML

مخططات تسلسلية، فئات، وتدفق مباشرة في المستند

🎭 ثيمات متعددة

5 ثيمات: أزرق، أحمر، أخضر، بنفسجي، ذهبي

📄 صفحة غلاف

صفحة غلاف تلقائية مع عنوان، مؤلف، وتاريخ

⚙️ Frontmatter

YAML Frontmatter لبيانات المستند الوصفية

🤖 MCP

أدوات MCP للتكامل مع Claude, Gemini, Codex وأكثر

المصادقة

معظم نقاط النهاية تعمل بدون مصادقة. لتسجيل السجلات واستخدام التاريخ:

الطريقة	التفاصيل
`JWT Token`	إرسال عبر `Authorization: Bearer <token>`
`Guest Session`	إرسال عبر `X-Guest-Session: <id>`

GET /api/health GET

فحص صحة الخادم — يتأكد إنو الخدمة شغالة.

مثال الطلب

curl https://md-2-pdf.pages.dev/api/health

الاستجابة

{
  "status": "ok",
  "service": "md-2-pdf",
  "version": "2.0.0",
  "platform": "cloudflare-pages",
  "timestamp": "2026-05-20T00:00:00.000Z"
}

POST /api/convert POST

تحويل نص Markdown إلى ملف PDF. يعيد الملف بصيغة base64 داخل JSON.

المعاملات

المعامل	النوع	مطلوب	الوصف
`markdown`	string	✅ نعم	نص Markdown للتحويل
`options.title`	string	❌ لا	عنوان المستند (يظهر بصفحة الغلاف)
`options.author`	string	❌ لا	اسم المؤلف
`options.pageSize`	string	❌ لا	A4 \| Letter \| Legal (افتراضي: A4)
`options.orientation`	string	❌ لا	portrait \| landscape
`options.fontSize`	number	❌ لا	حجم الخط بالبكسل (افتراضي: 10)
`options.fontFamily`	string	❌ لا	عائلة الخط
`options.css`	string	❌ لا	CSS مخصص يُحقن في PDF
`options.margin`	object	❌ لا	الهوامش: `{top, right, bottom, left}` (مثال: `"20mm"`)

مثال الطلب

curl -X POST https://md-2-pdf.pages.dev/api/convert \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# مرحباً بالعالم\n\nهذا **نص** تجريبي.\n\nمعادلة: $E = mc^2$\n\n```javascript\nconsole.log(\"Hello\");\n```",
    "options": {
      "title": "مستندي",
      "pageSize": "A4"
    }
  }'

الاستجابة (نجاح)

{
  "success": true,
  "pdf": "JVBERi0xLjQK...",
  "metadata": {
    "title": "مستندي",
    "createdAt": "2026-05-20T00:00:00.000Z"
  }
}

الاستجابة (خطأ - تجاوز الحد)

{
  "success": false,
  "error": "تم تجاوز حد التحويل اليومي...",
  "fallback": true,
  "html": "<html>...",
  "metadata": { ... }
}

⚠️ ملاحظة: حقل pdf يحتوي على ملف PDF كامل بصيغة base64. استخدم atob() في JavaScript أو base64 -d في الطرفية لاستخراج الملف.

POST /api/convert/base64 POST

مثل /api/convert لكن يعيد الـ base64 بحقل اسمه pdfBase64 بدل pdf.

الاستجابة

{
  "success": true,
  "pdfBase64": "JVBERi0xLjQK...",
  "metadata": { ... }
}

POST /api/parse POST

تحليل Markdown واستخراج البيانات الوصفية + معاينة HTML. لا ينشئ PDF.

المعاملات

المعامل	النوع	مطلوب	الوصف
`markdown`	string	✅ نعم	نص Markdown للتحليل
`options`	object	❌ لا	خيارات التحويل (نفس convert)

مثال الطلب

curl -X POST https://md-2-pdf.pages.dev/api/parse \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "---\ntitle: مستندي\nauthor: أحمد\n---\n\n# مرحباً\n\n**نص عريض** مع `كود`"
  }'

الاستجابة

{
  "success": true,
  "html": "<!DOCTYPE html><html lang=\"ar\" dir=\"rtl\">...",
  "metadata": {
    "title": "مستندي",
    "author": "أحمد",
    "createdAt": "2026-05-20T00:00:00.000Z"
  }
}

POST /api/auth/register POST

تسجيل حساب جديد لحفظ السجلات.

المعاملات

المعامل	النوع	مطلوب	الوصف
`username`	string	✅ نعم	اسم المستخدم
`email`	string	✅ نعم	البريد الإلكتروني
`password`	string	✅ نعم	كلمة المرور

POST /api/auth/login POST

تسجيل الدخول والحصول على JWT token.

المعاملات

المعامل	النوع	مطلوب	الوصف
`email`	string	✅ نعم	البريد الإلكتروني
`password`	string	✅ نعم	كلمة المرور

POST /api/auth/guest POST

إنشاء جلسة ضيف بدون تسجيل — يكفي لإرسال معرف الجلسة لاحقاً.

GET /api/history GET

جلب سجلات المستندات المحفوظة. يتطلب مصادقة (JWT أو Guest Session).

المعاملات (Query String)

المعامل	النوع	الوصف
`limit`	number	عدد النتائج (افتراضي: 50)
`offset`	number	بداية النتائج
`search`	string	بحث في العناوين

مثال الطلب

curl https://md-2-pdf.pages.dev/api/history?limit=10 \
  -H "Authorization: Bearer <token>"

🤖 أدوات MCP المتاحة

خادم MCP يوفر 3 أدوات للذكاء الاصطناعي لتحويل Markdown إلى PDF مباشرة:

convert-markdown-to-pdf تحويل مباشر

تحويل نص Markdown إلى ملف PDF.

المعامل	النوع	الوصف
`markdown`	string	نص Markdown (مطلوب)
`title`	string	عنوان المستند
`pageSize`	string	A4 \| Letter \| Legal
`filename`	string	اسم الملف الناتج

convert-markdown-file-to-pdf ملف

قراءة ملف Markdown من القرص وتحويله إلى PDF.

المعامل	النوع	الوصف
`filePath`	string	مسار الملف (مطلوب)
`title`	string	عنوان المستند
`pageSize`	string	A4 \| Letter \| Legal

parse-markdown-metadata تحليل

استخراج البيانات الوصفية (Frontmatter) من Markdown بدون تحويل.

المعامل	النوع	الوصف
`markdown`	string	نص Markdown (مطلوب)

⚙️ إعداد MCP

انسخ الإعداد المناسب لأداتك وأضفه لملف الإعدادات:

قبل البدء: ثبّت المشروع محلياً:

git clone https://github.com/shakfehabdullah-ship-it/md-2-pdf-cloudflare.git
cd md-2-pdf-cloudflare
npm install
npm run build

A Antigravity (Gemini CLI)

~/.gemini/settings.json

{
  "mcpServers": {
    "md-2-pdf": {
      "command": "node",
      "args": ["<md-2-pdf-path>/dist/mcp/server.js"]
    }
  }
}

C Claude Code

سطر الأوامر أو ~/.config/claude/mcp.json

# عبر الأمر
claude mcp add md-2-pdf -- node <md-2-pdf-path>/dist/mcp/server.js

# أو يدوياً في ~/.config/claude/mcp.json
{
  "mcpServers": {
    "md-2-pdf": {
      "command": "node",
      "args": ["<md-2-pdf-path>/dist/mcp/server.js"]
    }
  }
}

G Gemini CLI

~/.gemini/settings.json

{
  "mcpServers": {
    "md-2-pdf": {
      "command": "node",
      "args": ["<md-2-pdf-path>/dist/mcp/server.js"]
    }
  }
}

K Kilo Code

~/.config/kilo/kilo.jsonc

{
  "mcp": {
    "md-2-pdf": {
      "type": "stdio",
      "command": "node",
      "args": ["<md-2-pdf-path>/dist/mcp/server.js"]
    }
  }
}

O OpenClaw / OpenCode

~/.config/opencode/opencode.jsonc

{
  "mcp": {
    "md-2-pdf": {
      "type": "stdio",
      "command": "node",
      "args": ["<md-2-pdf-path>/dist/mcp/server.js"]
    }
  }
}

X Codex (OpenAI)

~/.codex/config.toml

[mcp_servers.md-2-pdf]
command = "node"
args = ["<md-2-pdf-path>/dist/mcp/server.js"]

Q Qwen CLI

~/.qwen/mcp_config.json

{
  "mcpServers": {
    "md-2-pdf": {
      "command": "node",
      "args": ["<md-2-pdf-path>/dist/mcp/server.js"]
    }
  }
}

* أي أداة MCP أخرى

{
  "command": "node",
  "args": ["<md-2-pdf-path>/dist/mcp/server.js"],
  "transport": "stdio"
}

⚠️ ملاحظة: استبدل <md-2-pdf-path> بالمسار الفعلي على جهازك. خادم MCP يحوّل الطلبات تلقائياً إلى https://md-2-pdf.pages.dev/api — لا حاجة لتشغيل خادم محلي.

🧪 اختبار MCP

بعد إعداد MCP، يمكنك اختباره بإرسال طلب JSON-RPC مباشرة:

اختبار عبر stdin

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node <md-2-pdf-path>/dist/mcp/server.js

النتيجة المتوقعة

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "convert-markdown-to-pdf",
        "description": "تحويل نص Markdown إلى PDF",
        "inputSchema": { ... }
      },
      {
        "name": "convert-markdown-file-to-pdf",
        "description": "تحويل ملف Markdown إلى PDF",
        "inputSchema": { ... }
      },
      {
        "name": "parse-markdown-metadata",
        "description": "استخراج البيانات الوصفية من Markdown",
        "inputSchema": { ... }
      }
    ]
  }
}

اختبار تحويل مباشر

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"convert-markdown-to-pdf","arguments":{"markdown":"# Test\nHello **world**!","title":"Test Document"}}}' | node <md-2-pdf-path>/dist/mcp/server.js