TON MCP — ربط Claude وCursor بشبكة TON خطوة بخطوة

كل من حاول أن يجعل وكيلًا ذكيًا ينجز شيئًا حقيقيًا على TON يعرف هذا الجدار جيدًا. تطلب من Claude أن يتحقق من رصيد محفظة، فيجيبك بصراحة أنه لا يملك وصولًا إلى الشبكة، أو الأسوأ: يخترع عنوان jetton من عنده، ويخلط بين النانوتون والتون، ويأتي بالأرقام من خياله. تعطيه أمر curl يستدعي واجهة برمجية عامة، فما إن يرتفع الحِمل حتى يصلك ردّ HTTP 429 Too Many Requests، وبدون مفتاح يكون الحد نحو طلب واحد في الثانية. أما اللايت-سيرفرات العامة الموجودة في الإعداد العالمي فتردّ تارةً بـ not ready وتنقطع تارةً أخرى بمهلة ADNL. المشكلة ليست في النموذج — الوكيل ببساطة لا يملك يدين يلمس بهما البلوكشين. وMCP هو ما يمنحه هاتين اليدين.

في ما يلي كيف تربط Claude بشبكة TON خلال دقائق، وكيف تُعِدّ كذلك Cursor TON MCP وClaude Code وCodex: إعدادات دقيقة، تشغيل مجاني عبر npx، ثم الانتقال إلى مفتاح مُستضاف حين تصطدم بالحدود.

ما هو MCP ولماذا يحتاجه الوكيل للعمل مع TON

إن MCP (Model Context Protocol) معيار مفتوح يستدعي عبره الوكلاء الأذكياء أدوات خارجية. تخيّل منفذ USB: كان لكل جهاز سابقًا وصلته الخاصة، واليوم منفذ واحد يكفي للجميع. وMCP هو «المنفذ الموحّد» ذاته بين الوكيل والعالم الخارجي. فـ Claude Desktop وClaude Code وCursor وChatGPT/Codex وأي عميل MCP آخر — جميعها تتحدث لغة واحدة: يتصل العميل بخادم MCP، ويستقبل قائمة الأدوات، ثم يستدعيها بناءً على طلب النموذج.

ولكي يتمكّن الوكيل من الدخول إلى شبكة TON، تحتاج إلى خادم MCP يجيد ذلك. سنأخذ TONNode — خادم MCP مُستضاف لشبكة TON. وهو يمنح الوكيل 16 أداة بالضبط: قراءة الشبكة (الرصيد، وحالة الحساب، والمعاملات، وget-methods الخاصة بالعقود، وأرصدة الجيتونات وبياناتها الوصفية)، والمبادلة عبر بروتوكول DEX المسمّى Omniston، ومبادلات cross-chain عبر ضمان HTLC الذرّي، وتوليد المحافظ. أدوات المبادلة وcross-chain والمحفظة غير احتجازية تمامًا: فالخادم لا يوقّع المعاملات أبدًا ولا يحتفظ بالمفاتيح — بل يعيد رسائل TonConnect غير موقّعة، تتولى محفظة المستخدم توقيعها.

ولأغراض هذا الدليل تكفينا أربع أدوات قراءة للتحقق من الاتصال:

• get_masterchain_info — رأس الـ masterchain (أسرع طريقة للتأكد من أن الخادم حيّ)؛
• get_balance — رصيد GRAM لعنوان معيّن؛
• get_jetton_balance — رصيد الجيتون (USDT وغيره)، مع حساب محفظة الجيتون على السلسلة؛
• parse_address — تحويل عناوين EQ/UQ/raw والتحقق منها، بلا اتصال بالشبكة تمامًا.

كيف تربط Claude بشبكة TON — بداية سريعة عبر npx (أمر واحد)

لا حاجة إلى تثبيت أي شيء. يُشغَّل الخادم المحلي بأمر واحد:

npx -y @tonnode/mcp

حزمة @tonnode/mcp مفتوحة المصدر (MIT)، وموجودة على npm وGitHub (tonnode/mcp)، وتعمل عبر بروتوكول ADNL الأصلي في TON دون طبقات HTTP وسيطة. ويمنحك الإعداد العام مجموعة أدوات القراءة كاملةً مجانًا — وهذا يكفي كي يقرأ الوكيل الأرصدة والمعاملات وحالات الحسابات ويستدعي get-methods.

أما الإعداد الأساسي الذي ستلصقه في العملاء فيبدو هكذا:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

احفظ بنية mcpServers جيدًا — فهي تتكرر حرفيًا في جميع العملاء تقريبًا. وفي ما يلي سأكتفي بتوضيح المكان الذي تضعها فيه. وللتعمّق في الوضع المجاني هناك دليل منفصل: MCP لشبكة TON مجانًا.

لا ترغب في التثبيت محليًا؟ يُمنح مفتاح Hobby المجاني لنقطة النهاية المُستضافة فور تسجيل الدخول، وبلا بطاقة بنكية — احصل عليه من tonnode.io/dashboard وضعه مباشرة في الإعداد أدناه.

Claude Desktop — أين يوجد claude_desktop_config.json وماذا تكتب فيه

يقرأ Claude Desktop إعداد MCP من ملف claude_desktop_config.json. ويختلف المسار باختلاف النظام:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

افتح الملف (أو أنشئه إن لم يكن موجودًا) واكتب فيه كائن mcpServers نفسه:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

بعد التعديل أعد تشغيل التطبيق — فـ Claude Desktop لا يلتقط الإعداد إلا عند الإقلاع. عندها سيظهر الخادم ton في قائمة الأدوات. والآن اكتب في المحادثة:

استدعِ get_masterchain_info وأظهر لي seqno الخاص برأس الـ masterchain.

إذا أعاد الوكيل رقم الكتلة، فقد اكتمل ربط MCP. ويمكنك بالمثل أن تطلب «تحقّق من رصيد المحفظة UQ…» — وسيعمل تحت الغطاء get_balance ويعيد رقمًا حقيقيًا بعملة GRAM (وGRAM هو اسم Toncoin بعد إعادة تسميته في يونيو 2026؛ أما الشبكة نفسها فما زالت تُسمّى TON).

Claude Code — الأمر claude mcp add وملف .mcp.json

في Claude Code يُضاف الخادم بأمر واحد من الطرفية، وهو يكتب كل شيء في الملف الصحيح بنفسه. النسخة المحلية:

claude mcp add ton -- npx -y @tonnode/mcp

الشرطتان -- تفصلان أمر تشغيل الخادم عن خيارات claude نفسها. بعد ذلك ينشئ Claude Code ملف .mcp.json الخاص بالمشروع (أو يضيف إليه). وإن شئت، يمكنك كتابة كائن mcpServers ذاته في الملف يدويًا — والنتيجة متطابقة:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

تحقّق من الاتصال مباشرةً في الـ CLI:

عبر parse_address حوّل 0:83df... إلى صيغة EQ/UQ سهلة القراءة.

تعمل parse_address دون اتصال بالشبكة، ولهذا فهي الاختبار الأوثق: فهي لا تعتمد على حالة الشبكة وتُظهر فورًا أن الأدوات مرئية للوكيل.

Cursor — ملف .cursor/mcp.json (على مستوى المشروع وعالميًا)

خبر سارّ لمن أعدّ Claude Desktop مسبقًا: يستخدم Cursor صيغة mcpServers نفسها تمامًا. يُنسخ الإعداد حرفيًا ولا حاجة إلى إعادة كتابة أي شيء. الفارق الوحيد هو موضع الملف:

• .cursor/mcp.json في جذر المشروع — الخادم مرئي في هذا المشروع فقط؛
• ~/.cursor/mcp.json — عالميًا، في جميع المشاريع.

وعند التعارض يفوز ملف المشروع. نضع فيه:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

وهذا هو كامل إعداد Cursor TON MCP: ملف واحد وأربعة أسطر من الحمولة المفيدة. بعد الحفظ تأكّد في Settings ← MCP من أن حالة ton هي Enabled، ثم اطلب من الوكيل داخل المحرّر مباشرةً:

كم USDT في المحفظة EQ...؟ استدعِ get_jetton_balance.

ستحسب get_jetton_balance عنوان محفظة الجيتون على السلسلة بنفسها — لا داعي لحسابه يدويًا. وهناك مقال منفصل عن كيفية الحصول على رصيد USDT باستدعاء واحد.

Codex CLI — ملف config.toml والأمر codex mcp add

يقف Codex في خانة خاصة: فإعداده بصيغة TOML لا JSON، ويوجد في ~/.codex/config.toml. البنية مختلفة لكن المعنى واحد. وأسهل طريقة لإضافة الخادم محليًا هي بالأمر:

codex mcp add ton -- npx -y @tonnode/mcp

وفي الملف يبدو الأمر هكذا:

[mcp_servers.ton]
command = "npx"
args = ["-y", "@tonnode/mcp"]

أما نقطة النهاية المُستضافة فتُضبط في Codex عبر config.toml حصرًا — والكتلة الجاهزة التي تحوي url وترويسة Authorization معروضة في قسم المفتاح المُستضاف أدناه. وإن كنت تحرّر TOML يدويًا، فتذكّر أن الصياغة هنا ليست أقواسًا معقوفة بل أقسامًا بين أقواس مربعة، ولذلك لا يمكن نسخ JSON من Cursor إلى هنا نسخًا آليًا. بعد الإضافة شغّل codex واطلب استدعاء get_masterchain_info — والردّ الذي يحمل seqno يؤكد نجاح الاتصال.

متى تنتقل إلى المفتاح المُستضاف mcp.tonnode.io وكيف تضعه

الخادم المحلي عبر npx ممتاز للتجربة وبناء نموذج أولي. لكن له سقفًا: فهو يمرّ عبر اللايت-سيرفرات العامة في إعداد TON العالمي. وهذه مشتركة ومحدودة — تردّ كثيرًا تحت الحِمل بـ not ready أو تسقط بمهلة ADNL، ولا تحتفظ بتاريخ عميق. وما إن يبدأ الوكيل بالعمل جدّيًا — يخدم مستخدمين، ويستطلع الأرصدة في حلقة، ويستدعي عشرات get-methods — حتى تصطدم بهذه الحدود.

يتضح الفارق في حالة بسيطة. لنفترض أن الوكيل يمرّ كل دقيقة على قائمة من خمسين محفظة، ويستدعي لكل واحدة get_balance بالإضافة إلى get_jetton_balance — أي نحو مئة استدعاء في المرور الواحد. على الإعداد العام ستصطدم هذه الحلقة شبه حتمًا بحدّ يقارب طلبًا واحدًا في الثانية: جزء من العناوين سيعيد not ready، وجزء سيسقط بمهلة، وسيضطر الوكيل إلى إعادة الطلبات فيزيد الضغط على اللايت-سيرفر المشترك أكثر. أما على نقطة النهاية المُستضافة بمفتاحك الخاص، فالمئة استدعاء نفسها تدخل ضمن سعة النقل المخصّصة لك، ويُسلَّم التاريخ وحالات الحسابات بثبات، دون سباق على مورد مشترك.

عندئذٍ يكون الوقت قد حان للانتقال إلى نقطة النهاية المُستضافة mcp.tonnode.io بمفتاحك الخاص وسعة نقل مضمونة. والمفتاح بصيغة tn_live_… هو رمز Bearer إلى https://mcp.tonnode.io/mcp. ويختلف الإعداد المُستضاف في وسيلة النقل: فبدلًا من تشغيل عملية، نحدّد HTTP وترويسة التفويض:

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": {
        "Authorization": "Bearer tn_live_…"
      }
    }
  }
}

ولـ Claude Code يوجد أمر جاهز — وانتبه إلى أن الخيارات تأتي قبل اسم الخادم:

claude mcp add --transport http ton https://mcp.tonnode.io/mcp \
  --header "Authorization: Bearer tn_live_…"

وفي Codex تُكتب نقطة النهاية المُستضافة في ~/.codex/config.toml — وتُحدَّد ترويسة التفويض في قسم مستقل:

[mcp_servers.ton]
url = "https://mcp.tonnode.io/mcp"

[mcp_servers.ton.headers]
Authorization = "Bearer tn_live_…"

نقطة مهمة تتعلق بالصدق في التسعير: الأدوات الـ 16 جميعها متاحة في كل الخطط، بما فيها Hobby المجانية. فالمفتاح يحدّد سعة النقل فقط، لا مجموعة الأدوات. لا وجود لـ«ميزات مدفوعة خلف اشتراك» — أنت تدفع مقابل تمرير الطلبات لا غير:

• Hobby — مجانية إلى الأبد، 60 طلبًا/دقيقة؛
• Pro — 29 دولارًا/شهريًا، 300 طلب/دقيقة؛
• Scale — 199 دولارًا/شهريًا، 1200 طلب/دقيقة.

يُمنح مفتاح Hobby المجاني فور تسجيل الدخول إلى لوحة التحكم، وبلا بطاقة بنكية. أي أن الانتقال من الوضع المحلي إلى المُستضاف لا يكلّفك شيئًا ما دامت الـ 60 طلبًا في الدقيقة تكفيك — وهذا وحده أوثق بكثير من اللايت-سيرفرات العامة.

ماذا تفعل إذا لم يظهر الخادم

نادرًا ما يتعطّل ربط MCP بطريقة معقّدة — فالسبب في الغالب واحد من ثلاثة تفاصيل صغيرة:

• الخادم غير مرئي في قائمة الأدوات. يقرأ العميل الإعداد عند الإقلاع فقط، ولذلك بعد تعديل الملف أعد تشغيل Claude Desktop أو Cursor بالكامل، أو أعد تشغيل جلسة Codex. وفي Claude Code تحقّق من الحالة بالأمر claude mcp list.
• الخادم ينهار عند التشغيل. عادةً لا يكون node/npx ضمن PATH — فالأمر npx -y @tonnode/mcp يجب أن يبدأ في طرفية عادية بلا أخطاء. وإن كان يعمل في الطرفية ولا يعمل من العميل، فاكتب في الإعداد المسار المطلق إلى npx داخل حقل command.
• أدوات القراءة تعيد not ready أو مهلة. هذا ليس خطأ في إعدادك، بل لايت-سيرفر عام محمّل بالطلبات. أعد المحاولة، وإن تكرر الأمر تحت الحِمل فانتقل إلى المفتاح المُستضاف — فهناك سعة نقل مخصّصة بدل طابور مشترك.

وتحقّق أيضًا من صحة صياغة JSON وTOML: فاصلة زائدة في mcpServers أو أقواس مختلطة في config.toml هي السبب الأكثر شيوعًا في تجاهل العميل للخادم صمتًا.

تمرين سريع — الأدوات التي ستستدعيها أولًا

مهما كان العميل، فالفحص النهائي واحد: استدعاء قراءة بسيط. وإليك أمثلة نموذجية لما تكتبه للوكيل، والأدوات التي تقف خلفها:

• «ما هو seqno الحالي للـ masterchain؟» ← get_masterchain_info. رأس الشبكة، وأفضل وسيلة للتأكد من أن MCP حيّ أصلًا.
• «كم GRAM في المحفظة UQ…؟» ← get_balance. رصيد العملة الأصلية.
• «كم USDT على هذا العنوان؟» ← get_jetton_balance. تُحسب محفظة الجيتون على السلسلة، ولا حاجة إلى معرفة عنوانها مسبقًا.
• «حوّل العنوان EQ… إلى صيغة UQ» ← parse_address. تحويل والتحقق من الصيغ دون اتصال بالشبكة.

بعد ذلك يمكنك أن تُسند إلى الوكيل مهامّ حقيقية:

• «تحقّق من get_account_state لهذا العنوان وأخبرني إن كان العقد منشورًا ومتى كانت آخر معاملة.»
• «عبر run_get_method استدعِ get_wallet_data من محفظة الجيتون وحلّل الردّ.» وكيفية استدعاء get-methods للقراءة فقط دون تثبيت أي SDK موضّحة في مقال استدعاء get-method بدون SDK.
• «كم عدد الخانات العشرية لهذا الجيتون؟ استدعِ get_jetton_info.» (لـ USDT ستّ خانات، ولمعظم الجيتونات تسع؛ وتحتاج إلى decimals كي تحوّل الوحدات الخام بشكل صحيح.)

وتجد نظرة عامة على كل إمكانات MCP لشبكة TON في الدليل الكبير.

الخلاصة

ربط الوكيل بشبكة TON هو حرفيًا أربعة أسطر JSON (أو أمر واحد) في إعداد عميلك. فالخادم المحلي npx -y @tonnode/mcp ينطلق بلا تثبيت وبلا مفتاح، ومعه مجموعة القراءة كاملة. وحين تصطدم بحدود اللايت-سيرفرات العامة، تبدّل وسيلة النقل إلى نقطة النهاية المُستضافة mcp.tonnode.io وتضع tn_live_…، دون تغيير سطر واحد في منطق الوكيل.

احصل على مفتاح Hobby المجاني وضعه في الإعداد خلال دقيقة ← tonnode.io/dashboard?plan=hobby. لا حاجة إلى بطاقة بنكية، ومجموعة الـ 16 أداة كاملة متاحة فورًا. وإن أردت أولًا أن ترى ما يجيده الخادم بالضبط، فألقِ نظرة على صفحة الأدوات.