FormaTeX

\usepackage{mcp}

خادم MCP للـ LaTeX

اربط Claude وClaude Code وCursor وVS Code وغيرها من الوكلاء المتوافقين مع MCP بـ FormaTeX. يكتب مساعدك كود LaTeX ويجمّعه ويعيد إليك رابط ملف PDF في المحادثة نفسها.

احصل على مفتاح APIاقرأ التوثيق

\section{ما هو MCP}

ما هو Model Context Protocol؟

استخدام أدوات أصيل للذكاء الاصطناعي

MCP بروتوكول مفتوح قدّمته Anthropic، يتيح لعملاء الذكاء الاصطناعي اكتشاف الأدوات الخارجية واستدعاءها أثناء التشغيل، فيستطيع المساعد التنفيذ دون كود ربط مخصص.

واجهة خادم قياسية

يعرض خادم MCP أدوات مسماة بمدخلات JSON Schema. ويمكن لأي عميل متوافق، مثل Claude أو Claude Code أو Cursor أو VS Code أو Codex أو وكيلك الخاص، استدعاؤها.

FormaTeX كمجموعة أدوات

يوفّر خادم FormaTeX أدوات لتجميع LaTeX بمحرك من اختيارك أو بإصلاحات تلقائية، والتحقق من الصياغة، وتشغيل مهام غير متزامنة، وتجميع القوالب المحفوظة، إضافة إلى موارد وprompt باسم fix_latex.

من البداية إلى النهاية في دور واحد

اطلب تقريرًا. يكتب المساعد كود LaTeX، ويستدعي أداة تجميع، ويعيد رابط تنزيل ملف PDF النهائي.

\section{الإعداد}

دليل الإعداد

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

الخطوة 1. أنشئ مفتاح API

أنشئ مفتاحًا في صفحة مفاتيح API من لوحة التحكم. تبدأ مفاتيح FormaTeX بالبادئة fex_. احتفظ بالمفتاح في متغير بيئة مثل FORMATEX_API_KEYبدلًا من إيداعه في مستودع الكود.

الخطوة 2، الخيار 1. الخادم المستضاف (موصى به)

الخادم على العنوانhttps://mcp.formatex.io/mcpيعمل بـ Streamable HTTP. لا شيء يحتاج إلى تثبيت، وكل طلب يحمل مفتاح API الخاص بك.

Claude (claude.ai وClaude Desktop)

  1. افتح Customize، ثم Connectors، واختر Add custom connector.
  2. أدخل عنوان URL للخادم أدناه.
  3. سجّل الدخول عند الطلب. تطلب صفحة التفويض مفتاح FormaTeX API الخاص بك. وإذا كان العميل يتيح ترويسات الطلب، فاضبط Authorization: Bearer <your key>.
Server URL
https://mcp.formatex.io/mcp

claude_desktop_config.jsonمخصص فقط للخوادم المحلية التي يشغّلها Claude Desktop بنفسه. أضف الخادم المستضاف عبر Connectors وليس عبر هذا الملف.

Claude Code

سجّل الخادم من سطر الأوامر، أو أضف الملف .mcp.jsonفي جذر المشروع.${VAR} يعمل التوسيع في هذا الملف، لذا يبقى المفتاح في بيئتك.

terminal
export FORMATEX_API_KEY="fex_your_api_key"

claude mcp add --transport http formatex https://mcp.formatex.io/mcp \
  --header "Authorization: Bearer $FORMATEX_API_KEY"
.mcp.json
{
  "mcpServers": {
    "formatex": {
      "type": "http",
      "url": "https://mcp.formatex.io/mcp",
      "headers": {
        "Authorization": "Bearer ${FORMATEX_API_KEY}"
      }
    }
  }
}

Cursor

أضف الخادم إلى.cursor/mcp.jsonفي مشروعك، أو إلى~/.cursor/mcp.jsonلجميع المشاريع.

.cursor/mcp.json
{
  "mcpServers": {
    "formatex": {
      "url": "https://mcp.formatex.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FORMATEX_API_KEY}"
      }
    }
  }
}

VS Code

يقرأ VS Code الملف.vscode/mcp.json. مفتاحه الرئيسي هو serversوليسmcpServers، وتحتاج الإدخالات البعيدة إلى "type": "http".

.vscode/mcp.json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "formatex-api-key",
      "description": "FormaTeX API key",
      "password": true
    }
  ],
  "servers": {
    "formatex": {
      "type": "http",
      "url": "https://mcp.formatex.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:formatex-api-key}"
      }
    }
  }
}

Codex

أضف جدول خادم إلى~/.codex/config.toml. bearer_token_env_varيحدد اسم متغير البيئة الذي يحتفظ بالمفتاح.

~/.codex/config.toml
[mcp_servers.formatex]
url = "https://mcp.formatex.io/mcp"
bearer_token_env_var = "FORMATEX_API_KEY"

الخطوة 2، الخيار 2. الملف التنفيذي المحلي (stdio)

شغّلformatex-mcpعلى جهازك. يشغّله العميل كعملية فرعية، ويقرأ الملف التنفيذي مفتاحك من FORMATEX_API_KEYمتغير البيئة. اختر هذا المسار إذا كان العميل لديك يدعم stdio فقط.

ثبّت الملف التنفيذي

terminal
# Requires Go 1.23 or newer
go install github.com/formatexio/mcp/cmd/formatex-mcp@latest

# The binary lands in $(go env GOPATH)/bin as formatex-mcp.
# Prebuilt binaries: https://github.com/formatexio/mcp/releases

Claude Desktop

عدّل ~/Library/Application Support/Claude/claude_desktop_config.json على macOS أو%APPDATA%\Claude\claude_desktop_config.json على Windows، ثم أعد تشغيل Claude Desktop.

claude_desktop_config.json
{
  "mcpServers": {
    "formatex": {
      "command": "/full/path/to/formatex-mcp",
      "env": {
        "FORMATEX_API_KEY": "fex_your_api_key"
      }
    }
  }
}

Claude Code

terminal
claude mcp add --env FORMATEX_API_KEY=fex_your_api_key \
  --transport stdio formatex -- /full/path/to/formatex-mcp

Codex

~/.codex/config.toml
[mcp_servers.formatex]
command = "formatex-mcp"

[mcp_servers.formatex.env]
FORMATEX_API_KEY = "fex_your_api_key"

المصادقة والتحقق

  • الخادم المستضاف: أرسل المفتاح بالصيغة Authorization: Bearer <key>أو X-API-Key: <key>. الطلب الذي لا يحمل مفتاحًا يحصل على الرمز 401.
  • تسجّل موصّلات Claude المخصصة الدخول عبر OAuth. تطلب صفحة التفويض مفتاح API الخاص بك.
  • الخادم المستضاف يدعم Streamable HTTP فقط. وليس له نقطة نهاية /sse، لذا ينبغي للعميل الذي يدعم نقل SSE الأقدم فقط أن يستخدم الملف التنفيذي المحلي.
  • تجمّع الخطط المجانية باستخدام pdflatex وxelatex. أما lualatex وlatexmk والقوالب المحفوظة فتتطلب خطة Pro أو أعلى.

للتأكد من أن الخادم المستضاف يعمل، استدعِ نقطة نهاية الصحة الخاصة به. ثم اطلب من مساعدك أن “List the available LaTeX engines”؛ ينبغي أن يستدعيlist_engines.

terminal
curl https://mcp.formatex.io/health
# {"status":"ok","service":"formatex-mcp","version":"1.0.0"}

\section{الأدوات}

الأدوات والموارد والـ prompt

الأداةما تفعله
compile_smartيجمّع مع اكتشاف تلقائي للمحرك وإصلاح للأخطاء، ويعيد المحاولة بمحركات بديلة. وهو الخيار الافتراضي الموصى به. يعيد رابط تنزيل PDF.
compile_latexيجمّع بالمحرك الذي تحدده: pdflatex أو xelatex أو lualatex أو latexmk. يعيد رابط تنزيل PDF.
check_syntaxيتحقق من المصدر بحثًا عن أخطاء الصياغة والأوامر المحظورة والمشكلات البنيوية دون تجميع. ولا يُحتسب ضمن حصة التجميع الشهرية.
compile_asyncيرسل مهمة تجميع ويعيد معرّف المهمة فورًا. مناسب للمستندات الكبيرة وسير عمل الدفعات.
get_jobيعيد حالة مهمة غير متزامنة: رابط تنزيل PDF عند اكتمالها، أو سجل الأخطاء عند فشلها.
fetch_pdf_bytesيعيد ملف PDF المجمّع بصيغة base64، لحالات الحاجة إلى الملف نفسه بدلًا من الرابط.
list_enginesيعرض محركات LaTeX المتاحة ومتى يُستخدم كل منها.
get_usageيعرض إحصاءات التجميع لهذا الشهر وحدود الخطة لمفتاح API.
list_templatesيعرض قوالبك المحفوظة مع المعرّفات والأسماء والأوصاف والمتغيرات. خطة Pro فأعلى.
get_templateيعيد قالبًا محفوظًا واحدًا مع كود LaTeX المصدري الكامل وتعريفات المتغيرات. خطة Pro فأعلى.
create_templateيحفظ قالبًا جديدًا مع عناصر نائبة للمتغيرات، بعد فحص مخطط المتغيرات. خطة Pro فأعلى، حتى حد القوالب في الخطة.
update_templateيغيّر فقط الحقول المُعطاة في قالب محفوظ. يُستبدل الإصدار السابق. خطة Pro فأعلى.
compile_templateيجمّع قالبًا محفوظًا بمعرّفه مع إمكانية تمرير قيم للمتغيرات. خطة Pro فأعلى.

يوفّر موردان،formatex://enginesو formatex://usageقائمة المحركات واستخدامك الحالي. ويأخذ الـ prompt المسمىfix_latexكود LaTeX المصدري وسجل الأخطاء ويعيد تعليمات منظمة لإصلاح الأخطاء.

\section{تعريف الأداة}

تعريف الأداة

هذا هو الإدخالcompile_latexكما يعيده الخادم المستضاف منtools/list. تشغيلاتو timeoutأعداد صحيحة؛ أرسل0 لتترك القرار لـ API، الذي يختار حينئذ عدد المرات ويطبّق المهلة الافتراضية لخطتك. compile_smartتأخذ latex, تشغيلاتوtimeoutوتختار المحرك بنفسها، وcompile_asyncتتطلب فقطlatex.

tools/list entry: compile_latex
{
  "name": "compile_latex",
  "description": "Compile LaTeX source code to a PDF using the FormaTeX API. Returns a download URL for the PDF. Specify the engine explicitly (pdflatex for standard documents, xelatex/lualatex for Unicode/modern fonts, latexmk for complex documents).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "latex": { "type": "string" },
      "engine": { "type": "string" },
      "runs": { "type": "integer" },
      "timeout": { "type": "integer" }
    },
    "required": ["latex", "engine", "runs", "timeout"],
    "additionalProperties": false
  }
}

يعيد التجميع الناجح نصًا عاديًا: بيانات وصفية للمهمة ورابط Download PDFلا يُضمَّن ملف PDF نفسه في الرد، مما يُبقي المحادثة صغيرة.fetch_pdf_bytesهي الأداة الوحيدة التي تعيد الملف بصيغة base64؛ استدعِها بمعرّف المهمة عندما تحتاج إلى البايتات.

tool result text
Compilation successful. Engine: pdflatex, Duration: <ms> ms, Job ID: <job id>, PDF size: <bytes> bytes
Download PDF: <url>

\section{مثال بلغة Python}

استخدام الخادم من Messages API

يتيح موصّل MCP في Messages API لـ Claude استدعاء الخادم المستضاف دون تشغيل عميل MCP بنفسك. وهو ميزة تجريبية: أرسل ترويسة beta mcp-client-2025-11-20، وأدرج الخادم ضمن mcp_servers، وفعّل أدواته بإدخال mcp_toolsetداخلtoolsيطلب المثال من Claude كتابة ملاحظة من صفحة واحدة وتجميعها في طلب واحد.

mcp_example.py
import os

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

response = client.beta.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.formatex.io/mcp",
            "name": "formatex",
            # Your FormaTeX API key, sent to the server as a bearer token.
            "authorization_token": os.environ["FORMATEX_API_KEY"],
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "formatex"}],
    messages=[
        {
            "role": "user",
            "content": (
                "Write a one-page LaTeX note on gradient descent with the "
                "update rule as a display equation, compile it, and give me "
                "the PDF link."
            ),
        }
    ],
)

for block in response.content:
    if block.type == "mcp_tool_use":
        print("Tool call:", block.name)
    elif block.type == "text":
        print(block.text)

يدعم الموصّل استدعاءات الأدوات فقط، لذا تتوفر الموارد والـ fix_latexprompt في عملاء MCP وليس عبر API.

\section{حالات الاستخدام}

حالات الاستخدام

تقارير بحثية

اطلب من مساعدك تلخيص بحث وتجميع ملف PDF منسّق يتضمن معادلات وأشكالًا وقائمة مراجع من طلب واحد.

توثيق آلي

دع وكيلًا في خط المعالجة (pipeline) لديك يولّد ملاحظات الإصدار أو مستندات مرجعية بصيغة LaTeX ويجمّعها إلى PDF.

شهادات عند الطلب

أنشئ شهادات أو فواتير مخصصة. يملأ الوكيل متغيرات قالب محفوظ (خطة Pro فأعلى) ويُخرج FormaTeX ملف PDF.

\section{Related}

أدلة ذات صلة

\end{mcp}

دع Claude يجمّع كود LaTeX الخاص بك

أنشئ مفتاح FormaTeX API، وأضف الخادم المستضاف إلى عميلك، وابدأ بإنشاء ملفات PDF من محادثة الذكاء الاصطناعي.

احصل على مفتاح APIعرض الأسعار