الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
MCP يعمل في الاتجاهين. الـ agent يستطيع استدعاء tools موجودة في سيرفرات MCP، أو يكون هو نفسه سيرفر MCP يناديه Claude Code وCursor وغيرهما من MCP clients. الاتجاهان موجودان في الـ subpath lousho/mcp، وحزمة @modelcontextprotocol/sdk هي peer dependency اختيارية: ثبّتها لاستخدام أي اتجاه منهما.
connectMcp وloadMcpTools وserveMcp مُصدَّرة من lousho/mcp؛ وجذر الحزمة وlousho/tools يصدّرانها أيضًا. أما createAgent({ mcpServers }) فلا يحتاج أي import من الـ subpath.

استخدام سيرفرات MCP داخل agent

createAgent({ mcpServers }) يأخذ نفس الـ map. السيرفرات تتصل عند await agent.ready()، أو تلقائيًا عند أول send() / stream(). tools كل سيرفر تنضاف باسم <server>__<tool> (مثل docs__search). إذا سيرفر فشل في الاتصال، النداء يفشل، والنداء التالي يحاول من جديد. agent.close() يقطع الاتصال بها (ويوقف عمليات stdio)؛ وأي tool call بعده، أو ready()، يعيد الاتصال. بدون mcpServers لا تفعل ready() وclose() شيئًا. بادئة vendor/ في الـ model تحدد الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).
مدخلات stdio تنطلق بـcommand وargs (داخل cwd إذا ضُبط)؛ وenv تُدمَج فوق قائمة المتغيرات المسموحة الافتراضية في MCP SDK (PATH وHOME وUSER وSHELL وTERM وLOGNAME على POSIX؛ وPATH وSYSTEMROOT وAPPDATA وTEMP وUSERPROFILE وعدد قليل غيرها على Windows)، وليس فوق process.env. وهذا صحيح سواء ضبطت env أو لا، لذلك أي متغير آخر يحتاجه السيرفر (API key، أو NODE_ENV، أو إعداد proxy) لا يُورَّث إلا إذا ذكرته: env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }. الـ tool call الفاشل (السيرفر خرج، أو انتهت مهلته، أو ردّ بخطأ في البروتوكول) يُرفض بـLOUSHO_MCP_CALL_FAILED مع ذكر <server>__<tool>. والسيرفر الذي لا يبدأ يفشل بـ LOUSHO_MCP_START_FAILED، ورسالته فيها exit code وآخر الأسطر التي كتبتها العملية على stderr. stderr: 'forward' (الافتراضي) ينسخ أيضًا stderr العملية إلى stderr العملية الحالية، و'capture' يحتفظ بآخر الأسطر فقط، و'inherit' / 'ignore' لا يحتفظان بشيء. connectTimeoutMs (لـ stdio أو HTTP) يحدّ مدة مصافحة initialize؛ والافتراضي هو 60 ثانية الخاصة بـ MCP SDK. افتراضيًا السيرفر الذي يفشل في الاتصال يُفشل كل send() للـ agent؛ علّم السيرفر الذي تستطيع الاستغناء عنه بـoptional: true فيُترك خارجًا مع console.warn بدل ذلك (وتبقى tools الخاصة به خارجًا طوال عمر الـ agent). وconnectMcp() تتخطى السيرفر optional بنفس الطريقة، حتى مع onError: 'throw'. مدخلات HTTP تستخدم streamable HTTP transport وترسل الـ headers الثابتة مع كل طلب. ويمكن لمدخل HTTP أيضًا تسجيل الدخول عبر OAuth كما يصفه MCP authorization spec: أضف oauth: { redirectUri } فيسجّل operator دخول الـ agent مرة واحدة؛ انظر سيرفرات MCP مع OAuth. كل tool call يستلم abort signal الخاص بالـ run، فإيقاف الـ run يلغي نداء MCP الجاري. timeoutMs على المدخل (stdio أو HTTP) يحدّ مدة كل نداء إلى ذلك السيرفر؛ وبدونه تُطبَّق المهلة الافتراضية في MCP SDK وهي 60 ثانية. وloadMcpTools(client, name, { timeoutMs }) تأخذ نفس الخيار. نتيجة الـ tool التي محتواها نص فقط تصل إلى الـ model على شكل { "text": ... }. كائن النتيجة يظل فيه content (الأجزاء) للكود الذي يقرأه، لكنه لا يُرسَل إلى الـ model مرة ثانية. النتائج التي فيها صور أو صوت أو resources تحتفظ بكل الأجزاء، وstructuredContent يُستخدم كنتيجة إذا أرسله السيرفر. بيانات Base64 (حقل data في جزء صورة أو صوت، أو blob في resource) تبقى على الجزء للكود، لكن الـ model يستلم بدلها نصًا مؤقتًا مثل [image: image/png, 400000 base64 characters, not sent to the model]. وكما في كل نتيجة tool، الباقي محدود بـmaxToolResultChars (انظر الـ Tools)، ووصف الـ tool الأطول من 2,000 حرف يُقص، لأنه يُرسَل مع كل طلب. الـ map هو نفسه الذي يعرّفه ملف spec؛ انظر الإعدادات (قسم mcpServers) لصيغة YAML.

مشاركة السيرفرات عبر connectMcp()

لمشاركة السيرفرات بين أكثر من agent، أو لتختار كيف تُعالَج الأعطال، استدعِ connectMcp(servers, options?) ومرّر tools الناتجة عنها بنفسك. هي تتصل بكل سيرفر وتسرد tools قبل أن تُكمِل، فتكون الـ tools معروفة من البداية. الخيارات:
  • onError: القيمة 'throw' (الافتراضية) ترفض الـ promise إذا سيرفر فشل في الاتصال، بعد إغلاق الباقي؛ والقيمة 'skip' تتجاوز ذلك السيرفر وتحذّر عبر logger.
  • lazy (الافتراضية true): بعد close() أو انقطاع الاتصال، الـ tool call التالي يعيد الاتصال. مع false النداء يفشل بدل ذلك. سرد الـ tools يحتاج اتصالًا، لذلك lazy لا تؤجّل أول اتصال أبدًا.
  • logger: يستقبل تحذيرات السيرفرات والـ tools المتخطّاة، وتحذيرًا (فيه exit code وآخر أسطر stderr) عندما ينغلق اتصال سيرفر بدون close() (الافتراضي: لا شيء).
  • tokens: الـ token store (AgentStore.tokens) للسيرفرات التي فيها oauth؛ مطلوب إذا كان أي سيرفر عنده oauth.
  • onToolsChanged(tools): تُستدعى بعد تغيّر قائمة tools أحد السيرفرات (انظر أدناه).
ترجع { tools, close(), status() }؛ وstatus() تعطي لكل سيرفر واحدة من القيم 'idle' (لم يتصل بعد، أو بعد close())، أو 'connected'، أو 'failed' (لم يستطع الاتصال، أو انقطع اتصاله، مثلًا خرجت عملية stdio؛ ومع lazy الـ tool call التالي يعيد الاتصال)، أو 'needs-auth' (سيرفر oauth لم يسجّل التطبيق دخوله إليه). الـ tools تُسرَد عبر كل صفحات tools/list (nextCursor)، حتى 100 صفحة لكل سيرفر. وعندما يرسل سيرفر notifications/tools/list_changed، تُسرَد tools الخاصة به من جديد: tools يتحدّث في مكانه (تُضاف الـ tools الجديدة، وتُحذف التي اختفت) وتُستدعى onToolsChanged. والـ agent الذي فيه mcpServers يعرض القائمة الجديدة من نداء الـ model التالي. tools هي Record<string, ToolDescriptor> بمفتاح <server>__<tool> — أي map، وليست الـ array التي تنتجها defineTool(). وcreateAgent({ tools }) يقبل الشكلين ويجمعهما: tools: [myTool, mcp.tools] تسجّل عناصر الـ array بأسمائها وعناصر الـ record بمفاتيحها، فتجتمع الـ tools الخاصة بك وtools MCP في قائمة واحدة. (النشر داخل record واحد، tools: { ...mcp.tools, my_tool: myTool }، يعمل أيضًا.)
mcp.tools record، وtools يقبل array أيضًا، فالشكلان يندمجان: tools: [mcp.tools, weatherTool] أو tools: [...createFsTools(workspace), ...Object.values(mcp.tools)] (كل descriptor من MCP يحمل اسم <server>__<tool> الخاص به، فيشتغل Object.values أيضًا).

أسماء الـ tools والفلترة

الـ providers تقبل أسماء tools تطابق ^[a-zA-Z0-9_-]{1,64}$؛ وMCP يسمح بأكثر من ذلك. اسم <server>__<tool> الذي فيه أحرف أخرى تُستبدل فيه بـ_، والاسم الأطول من 64 حرفًا يُختصر، مع hash قصير حتى تبقى الأسماء مختلفة؛ والأسماء التي تظل متصادمة تأخذ لاحقة _2 أو _3. السيرفر يُنادى دائمًا باسم الـ tool الأصلي، الذي يحتفظ به descriptor.metadata.mcp.tool، والـ tool الذي تغيّر اسمه يُسجَّل كتحذير. الأسماء الصالحة لا تتغير. لا يجوز لـ tool من MCP أن تأخذ اسم tool أخرى في الـ agent: إذا كان <server>__<tool> لسيرفر يساوي اسم tool محلية، يفشل الـ run بـ LOUSHO_CONFIG_INVALID بدل أن تحل tool الـ MCP محل الـ tool المحلية (ومحل بوابة الـ approval الخاصة بها). غيّر اسم الـ tool المحلية، أو اترك tool الـ MCP خارجًا عبر tools: { exclude }. tools: { include, exclude } على مدخل السيرفر (أو loadMcpTools(client, name, { tools })) يحمّل بعض tools فقط، بأسمائها في MCP: include يُبقي المذكورة فقط، ثم exclude يحذف المذكورة. واسم في include لا يعرضه السيرفر يُسجَّل كتحذير.

الـ approval على tools MCP

افتراضيًا كل tool من MCP تطلب approval: الـ run يتوقف حتى يقرر إنسان (أو الـ callback approve الخاص بك). سيرفرات MCP تصف كل tool بـ annotations: readOnlyHint و destructiveHint وidempotentHint وopenWorldHint وtitle. هي كلام السيرفر نفسه، وليست ضمانًا، لذلك الـ SDK لا يثق بها إلا إذا اخترت ذلك صراحةً عبر approval: 'annotations': عندها الـ tool مع readOnlyHint: true يعمل (ويمكن أن يعمل في plan mode)؛ والـ tool مع destructiveHint: true، أو الذي لا يرسل destructiveHint أصلًا (الافتراضي في spec MCP أنه destructive)، يوقف الـ run حتى يوافق إنسان؛ وdestructiveHint: false يعمل. الـ annotations الخام تبقى في descriptor.metadata.mcp.annotations في كل الأحوال، وtitle يصبح displayName. اضبط approval في مدخل السيرفر (mcpServers أو createAgent أو connectMcp()) أو في loadMcpTools(client, name, { approval }):
  • 'always' (الافتراضية): اسأل عن كل tool. والـ plan mode يرفض كل tools هذا السيرفر.
  • 'annotations': ثق بـ hints السيرفر، كما في الأعلى. استخدمها فقط مع سيرفرات تثق بها.
  • 'never': لا تسأل عن أي منها.
  • دالة ({ name, annotations, args }) => boolean تقرر لكل نداء (name هو اسم الـ tool المجرّد؛ وannotations هي {} إذا السيرفر لم يرسل شيئًا؛ وargs هي arguments النداء). تسمح لك بوضع بوابة على meta-tool مثل execute({ operation }) حسب arguments الخاصة به، لأن hints السيرفر ليست دائمًا صحيحة. في الكود فقط؛ أما ملف spec فيأخذ السلاسل الثلاث.
قواعد الصلاحيات تعمل أولًا، ولا يزال بإمكانها allow أو deny أو ask.

tools من client اتصلت به بنفسك

اتصل بـClient من @modelcontextprotocol/sdk بنفسك، وحمّل tools بـloadMcpTools()، ثم مرّر النتيجة إلى createAgent() (أو سجّلها في ToolRegistry):
loadMcpTools متوفرة أيضًا من جذر الحزمة ومن lousho/tools.

تشغيل agent كسيرفر MCP

serveMcp() عكس loadMcpTools(): تعرض الـ agent (واختياريًا بعض tools) كسيرفر MCP، فيستطيع Claude Code وCursor وغيرهما من MCP clients مناداته.
  • Stateless. كل نداء لـ tool الـ agent محادثة جديدة.
  • الإلغاء. إلغاء طلب MCP يوقف الـ run (agent.send(message, { signal })). وعبر HTTP يتوقف الـ run أيضًا عندما ينقطع الـ client، وعندما ترسل مهلة عند الـ client notifications/cancelled في POST لاحق: ذلك الإلغاء يُطابَق مع الطلب بالـ id الخاص به وبالـ client. السيرفر لا يحتفظ بأي session state، لكنه يرد على initialize بترويسة Mcp-Session-Id، والتي يرسلها Streamable HTTP clients (connectMcp() وMCP SDK) مرة أخرى، فيمكن التمييز بين client اثنين خلف نفس العنوان ونفس الـ token. أما الـ client الذي لا يرسل session id فيُعرَف بعنوانه البعيد وAuthorization وUser-Agent، ويُتجاهل الإلغاء الذي يرسله إذا طابق أكثر من طلب جارٍ. والطلب الملغى يُرَد عليه بخطأ JSON-RPC (-32800، Request cancelled).
  • الأخطاء. فشل الـ agent يرجع نتيجة MCP فيها isError: true.
  • الـ approvals. الـ tools المشروطة بـ approval لا يمكن الموافقة عليها عبر MCP. الـ run الذي يتوقف بانتظار approval يرجع isError: true مع رسالة توضّح ذلك، وتُرفض الـ approvals المعلّقة الخاصة به بدون إكمال الـ run، حتى لا تتراكم في approval store الخاص بالـ agent. والـ tools المعلَّمة needsApproval لا تُعرض مباشرة إلا إذا مرّرت allowApprovalTools: true؛ وإذا فعلت، الـ clients يشغّلونها بدون أي موافقة بشرية.
  • stdio. لا يُكتب على stdout شيء غير بروتوكول MCP؛ التحذيرات تذهب إلى stderr.
  • HTTP. يربط 127.0.0.1 افتراضيًا. أضف auth: { type: 'bearer', token } لاشتراط ترويسة Authorization: Bearer. والربط بـ host غير loopback بدون auth يسجّل تحذيرًا. ولمنع DNS rebinding (صفحة ويب تعيد توجيه الـ domain الخاص بها إلى جهازك)، الربط على loopback يرد بـ403 إلا إذا كانت ترويسة Host هي localhost أو عنوان 127.x.x.x أو [::1] (وليس أبدًا اسمًا مثل 127.attacker.example)، وأي طلب ترويسة Origin فيه ليست same-origin مع Host يأخذ 403. اضبط allowedHosts: ['mcp.internal'] لقبول أسماء أخرى (يحل محل الافتراضي الخاص بـ loopback؛ وعلى ربط غير loopback لا يوجد فحص لـ Host إلا إذا ضبطته) وallowedOrigins: ['https://app.example'] لقبول طلبات المتصفح من origin آخر. القيمة ['*'] تعطّل أيًّا من الفحصين.

Annotations

tools/list تحمل annotations MCP حتى يعرف الـ clients ماذا يفعل كل tool. الـ tool الذي يحتاج approval يُعلَن بـreadOnlyHint: false, destructiveHint: true؛ وحدّد الـ hints بنفسك عبر annotations (تُرسَل كما هي). الـ tool بلا hints لا يرسل شيئًا، فيظل agent من Lousho يستهلك هذا السيرفر يسأل قبل تشغيله (انظر approval في connectMcp())؛ أما readOnlyHint: true فيشتغل بدون سؤال. الـ tool الذي يحتاج approval لا يُعلَن أبدًا read-only. الـ tools المدمجة read_file وlist_dir وglob وgrep وtodo_read وcurrent_date و day_name كلها read-only.

من الـ CLI

lousho mcp يقدّم ملف spec لـ agent (عبر stdio افتراضيًا):
لاستخدامه من MCP client، أضفه إلى إعدادات MCP عند العميل (مثل .mcp.json في Claude Code):

القيود

  • الـ tools المشروطة بـ approval لا يمكن الموافقة عليها عبر MCP عندما تقدّم agent: الـ run الذي يتوقف لـ approval يرجع isError: true، والـ tools المعلَّمة needsApproval لا تُعرض إلا إذا ضُبطت allowApprovalTools.
  • الـ clients عبر HTTP يرسلون الـ headers الثابتة مع كل طلب. أما OAuth (oauth) فملك التطبيق: grant واحدة لكل سيرفر للـ agent كله، يسجّل دخولها operator؛ ولا توجد grants لكل مستخدم حتى الآن.
  • نداءات serveMcp() stateless: كل نداء لـ tool الـ agent محادثة جديدة، وHTTP transport يقبل POST فقط.