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).
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 يتوقف حتى يقرر إنسان (أو الـ callbackapprove الخاص بك).
سيرفرات 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، وعندما ترسل مهلة عند الـ clientnotifications/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.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فقط.