التوثيق

تكامل MCP

خادم MCP (بروتوكول سياق النموذج) يمكّن نماذج الذكاء الاصطناعي مثل Claude من التفاعل مع Asset Core من خلال استدعاء الأدوات عبر JSON-RPC.

المتطلبات المسبقة

  • تشغيل خدمات Asset Core (كتابة وقراءة)
  • مجموعة أدوات Rust لبناء خادم MCP
  • عميل متوافق مع MCP (Claude Desktop، إلخ)

الخطوة 1 - بناء خادم MCP

من مستودع Asset Core:

cargo build --release --bin mcp-server

الملف الثنائي موجود في target/release/mcp-server.

الخطوة 2 - تكوين عناوين URL للدايمون

خادم MCP يتصل بخدمات Asset Core الخاصة بك. قم بتكوينها عبر متغيرات البيئة:

export ASSETCORE_WRITE_URL=http://localhost:8080
export ASSETCORE_READ_URL=http://localhost:8081

الإعدادات الافتراضية هي localhost:8080 (كتابة) و localhost:8081 (قراءة).

الخطوة 3 - اختر وسيلة النقل

يدعم خادم MCP وسيلتين للنقل:

STDIO (افتراضي)

للتكامل المباشر مع Claude Desktop والعملاء المماثلين:

./target/release/mcp-server

يقرأ الخادم طلبات JSON-RPC من stdin ويكتب الردود إلى stdout.

SSE (Server-Sent Events)

للتكاملات المستندة إلى الويب:

إرشادات إضافية:

MCP_TRANSPORT=sse MCP_PORT=9000 ./target/release/mcp-server
المتغيرالوصف
MCP_TRANSPORTstdio (افتراضي) أو sse
MCP_PORTمنفذ الاستماع لـ SSE (مطلوب لـ SSE)

الخطوة 4 - اختبار الاتصال

قائمة الأدوات المتاحة:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./target/release/mcp-server

تحقق من صحة عملية الكتابة:

echo '{"jsonrpc":"2.0","id":2,"method":"assetcore_write_health"}' | ./target/release/mcp-server

الخطوة 5 - تقديم معاملة

إنشاء حاوية من خلال خادم MCP:

إرشادات إضافية:

echo '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "assetcore_commit",
  "params": {
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": "Standard",
          "owner": null
        }
      }
    ],
    "idempotency_key": "mcp-create-1001"
  }
}' | ./target/release/mcp-server

تتضمن الاستجابة نتيجة الالتزام مع أرقام التسلسل.

الخطوة 6 - تكوين سطح مكتب كلود

أضف خادم MCP إلى تكوين Claude Desktop الخاص بك:

إرشادات إضافية:

{
  "mcpServers": {
    "assetcore": {
      "command": "/path/to/mcp-server",
      "env": {
        "ASSETCORE_WRITE_URL": "http://localhost:8080",
        "ASSETCORE_READ_URL": "http://localhost:8081"
      }
    }
  }
}

يمكن الآن لـ Asset Core استخدام أدوات في المحادثات.

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

أخطاء “تم رفض الاتصال”

الخدمات غير قيد التشغيل أو أن عناوين URL غير صحيحة. تحقق من:

curl http://localhost:8080/v1/health
curl http://localhost:8081/v1/health

أخطاء “JSON-RPC غير صالح”

تأكد من أن كل طلب هو JSON صالح في سطر واحد. يستخدم بروتوكول MCP JSON مفصول بأسطر جديدة.

الأداة غير موجودة

يجب أن يتطابق اسم الطريقة تمامًا. الأدوات المتاحة:

  • tools/list
  • assetcore_commit
  • assetcore_write_health
  • assetcore_read_health
  • assetcore_read_freshness

استخدام acctl

يمكنك أيضًا تشغيل خادم MCP من خلال acctl:

إرشادات إضافية:

acctl adapters --transport stdio

هذا يستخدم اكتشاف التكوين ويحترم متغيرات البيئة ASSETCORE_*.

الخطوات التالية