> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# MCP للمطورين: اربط وكيلك بقاعدة البيانات والتذاكر والتوثيق
- URL: https://arabroot.io/articles/mcp-للمطورين-اربط-وكيلك-بقاعدة-البيانات-والتذاكر/
- Published: 2026-11-19T20:26:14.000Z
- Updated: 2026-11-19T21:23:46.000Z
- Description: كيف تضيف سيرفر MCP إلى Codex وClaude Code وCursor، وكيف تكتب سيرفراً للفريق يقرأ قاعدة البيانات دون أن يكتب فيها، وكم يكلف كل سيرفر من سياق الوكيل.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, التطوير مع وكلاء الذكاء الاصطناعي

وكيل البرمجة يرى مستودعك جيداً، يقرأ الملفات ويشغل الاختبارات Tests ويبحث في الكود Code، ولكن أغلب ما تحتاجه لتفهم خطأً حقيقياً ليس في المستودع Repository: التذكرة Ticket التي كتبها العميل، والسجلات Logs في نظام المراقبة، وعدد الصفوف التي تأثرت في قاعدة البيانات Database، وصفحة التوثيق الداخلي التي تشرح قاعدة العمل. والطريقة البسيطة أن تفتح كل هذه الأنظمة بنفسك، ثم تنسخ منها ما يلزم وتلصقه في المحادثة، وهي طريقة تعمل في المرة الأولى، ثم تصبح في المرة العاشرة عملاً ممللاً تقوم فيه أنت بدور الوسيط بين الوكيل Agent وأنظمة الفريق. وبروتوكول سياق النموذج Model Context Protocol، واختصاراً MCP، هو الطريقة المشتركة اليوم لكي يصل الوكيل إلى هذه الأنظمة بنفسه، بأدوات تحددها أنت وصلاحيات تحددها أنت.

وفي [دليل MCP للمبتدئين](https://arabroot.io/articles/%D8%A8%D8%B1%D9%88%D8%AA%D9%88%D9%83%D9%88%D9%84-mcp-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/) شرحنا البروتوكول من الداخل: المضيف Host والعميل Client والسيرفر Server، والرسائل JSON-RPC، وطرق النقل، والمخاطر الأمنية مثل تسميم وصف الأداة Tool Poisoning، وبنينا سيرفر تذاكر بلغة Python وC#. ولن نكرر ذلك هنا، وإنما نأخذ زاوية المطور الذي يريد أن يربط وكيل البرمجة الذي يستعمله كل يوم بأنظمة فريقه: كيف تضيف السيرفر في Codex وClaude Code وCursor؟ وأي السيرفرات تستعمل جاهزة وأيها تكتبه بنفسك؟ وكيف تعطي الوكيل قاعدة البيانات دون أن يستطيع أن يحذف منها شيئاً؟ وكم يكلفك كل سيرفر تضيفه من السياق Context، وهل يختار النموذج الأداة الصحيحة عندما تكثر الأدوات؟ ولذلك بنينا في المختبر سيرفراً صغيراً بلغة TypeScript يعطي الوكيل قاعدة بيانات للقراءة فقط ونظام تذاكر وتوثيقاً داخلياً، وفحصناه بأداة MCP Inspector، ثم رأينا كيف يضعه Codex في طلبه، ثم ربطناه بنموذج محلي مع سيرفرين مرجعيين وقسنا النتيجة.

في هذا المقال سوف نتناول:

- ماذا يضيف MCP لوكيل البرمجة تحديداً، ومتى لا تحتاجه.
- كيف تضيف سيرفراً في Codex وClaude Code وCursor وVS Code، وأين يحفظ كل إعداد.
- السيرفرات الجاهزة: المرجعية Reference Servers، وسيرفرات الشركات، وما أرشف منها ولماذا.
- سيرفر للفريق بالإصدار الثاني من TypeScript SDK: قاعدة بيانات للقراءة فقط، وتذاكر، وتوثيق.
- الفحص بأداة MCP Inspector في الطرفية وفي المتصفح، ولماذا رفضت أن تعمل على كل الواجهات.
- كم يكلف كل سيرفر من السياق، وهل يختار نموذج صغير الأداة الصحيحة بين 34 أداة.
- الصلاحيات والموافقات، وحادثة حقيقية لسيرفر قاعدة بيانات مرجعي.

## ماذا يضيف MCP لوكيل البرمجة؟

وكيل البرمجة يملك من البداية أداة قوية جداً، وهي الطرفية Terminal، فهو يستطيع أن يشغل `psql` أو `curl` أو `gh issue view` كما تفعل أنت، فلماذا نحتاج بروتوكولاً آخر؟ والإجابة أن الطرفية تعطي الوكيل كل صلاحياتك دون تمييز، فإذا كان `psql` متصلاً بحسابك فإن الوكيل يستطيع أن يشغل `DELETE` كما يستطيع أن يشغل `SELECT`، وإذا كان `gh` مسجلاً بحسابك فإنه يستطيع أن يغلق التذاكر ويدمج Pull Requests، والطريقة الوحيدة للتحكم أن تراجع كل أمر قبل أن ينفذ. أما سيرفر MCP فيعرض للوكيل أدوات محددة باسمها ومدخلاتها، مثل `query_db` التي تقبل جملة SELECT واحدة فقط، فتصبح الحدود في الكود الذي كتبته أنت وليس في انتباهك أثناء المراجعة Review. وهناك فوائد أخرى مهمة:

- **الوصف للنموذج:** كل أداة لها وصف Description مكتوب للنموذج يشرح متى يستعملها، وكل مدخل له نوع ووصف، فيعرف النموذج أن جدول `invoices` فيه عمود `amount_halalas` قبل أن يكتب الاستعلام.
- **سيرفر واحد لكل الأدوات:** السيرفر الذي تكتبه مرة يعمل في Codex وClaude Code وCursor وVS Code وغيرها، لأن البروتوكول واحد، وهذه هي مشكلة الربط N×M التي شرحناها في دليل المبتدئين.
- **المصادقة Authentication في مكان واحد:** السيرفر البعيد يستعمل OAuth، فيسجل كل مطور دخوله بحسابه وصلاحياته، ولا يكتب أحد توكناً في ملف إعداد.

ومتى لا تحتاجه؟ إذا كان ما تريده أمراً واحداً للقراءة تشغله أنت مرة في اليوم، أو كانت الأداة لها واجهة سطر أوامر CLI آمنة للقراءة فقط، فإن إضافة سيرفر لها تكلفك سياقاً في كل طلب كما سوف نقيس بعد قليل، والطرفية تكفيك. ولذلك ابدأ بالأنظمة التي تنسخ منها كل يوم، وليس بكل نظام في الشركة.

## كيف تضيف سيرفراً في أداتك؟

كل أداة تحفظ قائمة السيرفرات في ملف خاص بها، ولكن المعلومة واحدة في كل الحالات: اسم للسيرفر، وطريقة تشغيله، أي الأمر ومدخلاته إذا كان محلياً يعمل بالنقل `stdio`، أو العنوان إذا كان بعيداً يعمل بالنقل Streamable HTTP. والشكل التالي يبين الصورة الكاملة التي نبنيها في هذا المقال:

![على اليمين صندوق داكن بعنوان المضيف Host ومعه Claude Code وCodex وVS Code وCursor، وفيه النموذج والحلقة وثلاثة مستطيلات زرقاء MCP client 1 و2 و3، ومن كل عميل سهم إلى اليسار: الأول بالنقل stdio إلى سيرفر الفريق devdesk وفيه query_db للقراءة فقط وlist_tickets وget_ticket وsearch_docs مع رمز قاعدة بيانات وتذكرة OPS-104 وملف vat.md، والثاني بالنقل stdio إلى السيرفرات المرجعية filesystem وgit، والثالث بالنقل Streamable HTTP مع OAuth إلى سيرفرات الشركات GitHub وJira وNotion وSentry](https://arabroot.io/content/images/2026/11/mcp-for-developers-01-map.webp)

كل سيرفر له عميل خاص داخل المضيف: سيرفر الفريق والسيرفرات المرجعية على جهازك بالنقل stdio، وسيرفرات الشركات عن بعد مع تسجيل الدخول.

### Codex: ملف config.toml

[صفحة MCP في توثيق Codex](https://developers.openai.com/codex/mcp?ref=arabroot.io) تذكر أنك تضيف السيرفر بالأمر `codex mcp add`، أو بجدول باسم `[mcp_servers.<name>]` في `~/.codex/config.toml` أو في ملف المشروع `.codex/config.toml`. والإعداد الذي استعملناه في المختبر كما يلي، ومعه الخيارات التي تحدد الأدوات والموافقات كما يذكرها التوثيق:

```toml
[mcp_servers.devdesk]
command = "node"
args = ["/tmp/devdesk/server.mjs"]
# اختيارية، كما في التوثيق:
# enabled_tools = ["query_db", "get_ticket", "search_docs"]   # قائمة سماح
# disabled_tools = ["list_tickets"]                           # قائمة منع تطبق بعدها
# default_tools_approval_mode = "writes"   # auto أو prompt أو writes أو approve
# tool_timeout_sec = 60                     # الافتراضي 60، وstartup_timeout_sec الافتراضي 10
```

لاحظ الخيار `default_tools_approval_mode`، فالقيمة `writes` تطلب موافقتك على كل أداة لم يعلمها السيرفر بأنها للقراءة فقط، وهذا يعتمد على علامة `readOnlyHint` التي سوف نضعها في كل أداة في سيرفرنا. ولاحظ أيضاً أن `enabled_tools` يسمح لك أن تأخذ من سيرفر كبير الأدوات التي تحتاجها فقط، وهذا مهم كما سوف نرى في قياس السياق.

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

[صفحة MCP في توثيق Claude Code](https://code.claude.com/docs/en/mcp?ref=arabroot.io) تذكر الأمر التالي لسيرفر محلي، وكل ما بعد `--` هو أمر تشغيل السيرفر كما هو:

```bash
claude mcp add --transport stdio devdesk -- node devdesk/server.mjs
claude mcp add --transport http github https://api.githubcopilot.com/mcp/   # سيرفر بعيد
claude mcp list
```

ويحفظ Claude Code السيرفر في أحد ثلاثة نطاقات Scopes: المحلي Local وهو الافتراضي، ويخص المشروع الحالي ويحفظ في `~/.claude.json` ولا يشترك فيه أحد، والمشروع Project ويحفظ في ملف `.mcp.json` في جذر المستودع ليشترك فيه الفريق عبر git، والمستخدم User ويحفظ في `~/.claude.json` لكل مشاريعك. وملف المشروع له صيغة `mcpServers` نفسها التي تستعملها أدوات كثيرة:

```json
{
  "mcpServers": {
    "devdesk": { "command": "node", "args": ["devdesk/server.mjs"] }
  }
}
```

ولاحظ نقطة أمنية مهمة في التوثيق: السيرفر الذي يأتي من `.mcp.json` في مستودع لم تثق به بعد يبقى في حالة «بانتظار الموافقة» Pending approval، ولا يستطيع المستودع أن يوافق على سيرفراته بنفسه بإعداد مكتوب فيه، والسبب أن السيرفر المحلي برنامج يعمل على جهازك بصلاحياتك، فلا يجب أن يشغله مجرد أن تفتح مستودعاً نسخته من الإنترنت.

### Cursor وVS Code وCline

[توثيق Cursor](https://cursor.com/docs/context/mcp?ref=arabroot.io) يستعمل ملف `.cursor/mcp.json` في المشروع أو `~/.cursor/mcp.json` لكل المشاريع، بالصيغة `mcpServers` نفسها. و[توثيق VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers?ref=arabroot.io) كما كان في نوفمبر 2026 يذكر أنك تضيف السيرفر من واجهة التخصيص، وأن السيرفر الذي يشترك فيه الفريق يحفظ في ملف `.mcp.json` في جذر مساحة العمل، ويحذر في أول الصفحة من أن السيرفر المحلي يشغل كوداً على جهازك وأن عليك أن تراجع الناشر والأمر قبل أن تشغله. وCline يحفظ سيرفراته في ملف إعداد خاص به يفتحه من لوحة MCP Servers، بالصيغة نفسها تقريباً. والخلاصة أن السيرفر الذي يعمل في أداة يعمل في الأخرى بتغيير مكان الملف فقط.

## أي السيرفرات تستعمل؟

قبل أن تكتب سيرفراً، ابحث هل يوجد سيرفر رسمي من صاحب النظام نفسه، وهنا ثلاثة أنواع:

- **السيرفرات المرجعية Reference Servers:** [مستودع السيرفرات الرسمي](https://github.com/modelcontextprotocol/servers?ref=arabroot.io) فيه اليوم سبعة فقط، منها `filesystem` للملفات و`git` للمستودع و`fetch` لجلب الصفحات و`memory` و`time`، ويقول المستودع صراحة إنها أمثلة تعليمية لطريقة استعمال البروتوكول والـ SDK، وليست حلولاً جاهزة للإنتاج، وإن على المطور أن يقيم متطلبات الأمان بنفسه.
- **سيرفرات الشركات:** سيرفرات تكتبها الشركة صاحبة النظام وتديرها، مثل [سيرفر GitHub الرسمي](https://github.com/github/github-mcp-server?ref=arabroot.io)، وفيه خيار `--toolsets` لتختار مجموعات الأدوات التي تحتاجها، مثل `repos,issues`، وخيار `--read-only` الذي يحذف كل أدوات الكتابة حتى لو طلبتها بالاسم، والتوثيق نفسه يقول إن تقليل الأدوات يساعد النموذج على الاختيار ويصغر السياق.
- **السجل Registry:** [سجل MCP الرسمي](https://registry.modelcontextprotocol.io/?ref=arabroot.io) يجمع السيرفرات المنشورة، ولكن وجود السيرفر في السجل ليس مراجعة لأمانه.

وقبل أن تضيف أي سيرفر جاهز، اسأل عنه الأسئلة نفسها التي تسألها عن أي اعتمادية Dependency تضيفها إلى مشروعك: من ينشره، هل هو الشركة صاحبة النظام أم شخص لا تعرفه؟ ومتى كان آخر تحديث له؟ وهل كوده مفتوح تستطيع أن تقرأه؟ وما هي الأدوات التي يعرضها بالضبط، وهل فيها أدوات كتابة لا تحتاجها؟ وهل يعمل بصلاحيات حسابك كلها، أم بتوكن تحدد أنت صلاحياته؟ والفرق بين السيرفر والمكتبة العادية أن السيرفر لا يعمل داخل كودك فقط، وإنما يتكلم مع نموذج يتخذ قرارات بناء على ما يرجعه، ولذلك فإن السيرفر الذي يرجع نصاً من مصدر خارجي، مثل صفحة ويب أو تذكرة كتبها عميل، يدخل إلى وكيلك نصاً لم تكتبه أنت.

والمستودع الرسمي نفسه أرشف كثيراً من السيرفرات التي كانت فيه، ومنها سيرفرات PostgreSQL وSQLite وGitHub وSentry وSlack، ونقل بعضها إلى الشركات صاحبتها، وبقيت الأخرى في [مستودع الأرشيف](https://github.com/modelcontextprotocol/servers-archived?ref=arabroot.io). ولهذا الأرشيف قصة يجب أن تعرفها قبل أن تنسخ أي سيرفر لقاعدة بيانات:

📌

في يونيو 2025 نشرت شركة Trend Micro [تحليلاً لثغرة حقن SQL](https://www.trendmicro.com/en%5Fus/research/25/f/why-a-classic-mcp-server-vulnerability-can-undermine-your-entire-ai-agent.html?ref=arabroot.io) في سيرفر SQLite المرجعي، فالسيرفر كان يبني جملة SQL بلصق مدخل المستخدم في النص مباشرة، وبينت أن مهاجماً يستطيع أن يخزن تذكرة فيها تعليمات خبيثة بحالة «مفتوحة» فتتجاوز فحص التذاكر الجديدة، ثم يقرؤها الوكيل وينفذ ما فيها بأدواته الأخرى. وأبلغت الشركة عن الثغرة في 11 يونيو 2025، وكان الرد أن المستودع مؤرشف وأنه مثال تعليمي فلا يوجد إصلاح، بينما كان السيرفر قد نسخ Fork أكثر من 5,000 مرة قبل أرشفته. والدرس أن «مرجعي» لا تعني «آمن»، وأن الكود الذي تنسخه لقاعدة بياناتك مسؤوليتك أنت.

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

## المختبر: سيرفر devdesk بلغة TypeScript

السيرفر في المختبر اسمه devdesk، ويعطي الوكيل ثلاثة أنظمة صغيرة: قاعدة بيانات SQLite فيها جدول عملاء من 40 صفاً وجدول فواتير من 300 صف، وملف JSON فيه أربع تذاكر من نظام العمليات OPS، ومجلد فيه ثلاث صفحات توثيق عن ضريبة القيمة المضافة VAT والتصدير والتقرير الشهري. والسكربت `seed.mjs` يبني هذه البيانات، والسيرفر `server.mjs` مكتوب بالإصدار الثاني من [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk?ref=arabroot.io)، أي الحزمة `@modelcontextprotocol/server` بالإصدار 2.4.0، وهو يعمل بلغة JavaScript مباشرة على Node.js 24 دون خطوة بناء. وكل شيء يعمل في Docker Image واحدة من `node:24-alpine` فيها السيرفر والعميل وأداة MCP Inspector بالإصدار 2.16.0 والسيرفران المرجعيان `@modelcontextprotocol/server-filesystem` بالإصدار 2.4.0 و`mcp-server-git` بالإصدار 2026.11.18.

واخترنا TypeScript هنا لأن دليل المبتدئين استعمل Python وC#، ولأن الإصدار الثاني من SDK يقول في ملف README الخاص به إنه الخط المستقر الذي يطبق مواصفة 2026-07-28، أي [الإصدار الحالي من المواصفة Spec](https://modelcontextprotocol.io/specification/versioning?ref=arabroot.io) كما تذكر صفحة الإصدارات، وهو الإصدار الذي أزال المصافحة الأولى initialize وجعل كل طلب يحمل نسخة البروتوكول بنفسه، كما شرحنا في دليل المبتدئين. والسيرفر كاملاً كما يلي:

```javascript
// devdesk: an MCP server (TypeScript SDK v2, stdio) that gives a coding agent the team's database (read-only),
// tickets and docs. Run: node server.mjs   (paths are relative to this folder)
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import { DatabaseSync } from 'node:sqlite';
import { readFileSync, readdirSync } from 'node:fs';
import * as z from 'zod/v4';

const DIR = new URL('./data/', import.meta.url);
const db = new DatabaseSync(new URL('devdesk.db', DIR), { readOnly: true });   // the file is opened read-only
const tickets = () => JSON.parse(readFileSync(new URL('tickets.json', DIR), 'utf8'));
const docs = () => readdirSync(new URL('docs/', DIR)).map(f => ({ name: f, text: readFileSync(new URL(`docs/${f}`, DIR), 'utf8') }));
const text = t => ({ content: [{ type: 'text', text: typeof t === 'string' ? t : JSON.stringify(t, null, 1) }] });

serveStdio(() => {
  const server = new McpServer({ name: 'devdesk', version: '1.0.0' }, {
    instructions: 'Tools for the invoicing team: read-only SQL on the production replica (tables customers, invoices), ' +
      'the OPS ticket queue, and the internal docs. Use them before guessing about data, bugs or business rules.'
  });

  server.registerTool('query_db', {
    description: 'Run one read-only SQL SELECT on the invoicing database (SQLite). Tables: customers(id, name, plan, created_at), ' +
      'invoices(id, customer_id, amount_halalas, status paid|open|void, issued_at). Returns at most 50 rows.',
    inputSchema: z.object({ sql: z.string().describe('A single SELECT statement') }),
    annotations: { readOnlyHint: true }
  }, async ({ sql }) => {
    if (!/^\s*select\b/i.test(sql) || sql.includes(';')) return { ...text('Only one SELECT statement is allowed.'), isError: true };
    try { return text(db.prepare(sql).all().slice(0, 50)); }
    catch (e) { return { ...text(`SQL error: ${e.message}`), isError: true }; }
  });

  server.registerTool('list_tickets', {
    description: 'List OPS tickets (id, status, title). Optional filter by status.',
    inputSchema: z.object({ status: z.enum(['open', 'closed']).optional() }),
    annotations: { readOnlyHint: true }
  }, async ({ status }) => text(tickets().filter(t => !status || t.status === status).map(({ id, status, title }) => ({ id, status, title }))));

  server.registerTool('get_ticket', {
    description: 'Get one OPS ticket with its full text.',
    inputSchema: z.object({ id: z.string().describe('Ticket id, e.g. OPS-101') }),
    annotations: { readOnlyHint: true }
  }, async ({ id }) => { const t = tickets().find(t => t.id === id); return t ? text(t) : { ...text(`No ticket ${id}`), isError: true }; });

  server.registerTool('search_docs', {
    description: 'Search the internal docs (business rules, VAT, exports, reports). Returns matching docs.',
    inputSchema: z.object({ query: z.string() }),
    annotations: { readOnlyHint: true }
  }, async ({ query }) => {
    const words = query.toLowerCase().split(/\W+/).filter(w => w.length > 2);
    return text(docs().filter(d => words.some(w => d.text.toLowerCase().includes(w))));
  });

  for (const d of docs()) server.registerResource(d.name, `docs://${d.name}`, { mimeType: 'text/markdown' },
    async uri => ({ contents: [{ uri: uri.href, text: d.text }] }));
  return server;
});
console.error('devdesk MCP server on stdio');
```

في الكود أعلاه لاحظ التالي:

- `serveStdio` يأخذ دالة تبني السيرفر، وهذه طريقة الإصدار الثاني بدل `StdioServerTransport` في الإصدار الأول، والتوثيق يذكر أنه يخدم العملاء القدماء الذين يستعملون المصافحة من الدالة نفسها، فلا تحتاج سيرفرين.
- السطر `console.error` في الآخر مقصود، لأن المخرج القياسي stdout هو قناة رسائل JSON-RPC نفسها، وأي `console.log` فيه يفسد الرسالة الأولى، ولذلك تكتب رسائلك إلى stderr دائماً.
- تعليمات السيرفر `instructions` تصل إلى المضيف، وبعض المضيفين يضعونها في سياق النموذج كما سوف نرى في Codex، ولذلك كتبنا فيها ما يقدمه السيرفر ومتى يستعمل.
- وصف `query_db` فيه أسماء الجداول والأعمدة وقيم `status`، لأن النموذج لا يرى قاعدة البيانات، وإنما يرى الوصف فقط، فإذا لم تذكر أن المبالغ في عمود `amount_halalas` فسوف يخمن اسماً مثل `amount` ويحصل على خطأ.
- الحماية من الكتابة في طبقتين: الأولى فحص يقبل جملة تبدأ بـ SELECT ولا فيها فاصلة منقوطة، والثانية أن ملف قاعدة البيانات يفتح بالخيار `readOnly: true`، فحتى لو تجاوز أحد الفحص الأول فإن SQLite نفسه يرفض الكتابة. وفي قاعدة بيانات حقيقية مثل PostgreSQL تكون الطبقة الثانية مستخدماً في قاعدة البيانات له صلاحية `SELECT` فقط على نسخة القراءة Read Replica، وليس على قاعدة الإنتاج.
- كل أداة عليها العلامة `readOnlyHint: true`، وهي ما يعتمد عليه Codex في وضع الموافقة `writes`، ولكن تذكر أنها علامة يكتبها السيرفر عن نفسه، والمضيف لا يتحقق منها، فلا تثق بها في سيرفر لم تكتبه.

## الفحص بأداة MCP Inspector في الطرفية

قبل أن تعطي السيرفر لأي وكيل، افحصه وحدك، لأن الخطأ في السيرفر يظهر مع الوكيل على شكل نموذج «لا يفهم»، وأنت لا تعرف هل المشكلة في النموذج أو في الأداة. و[أداة MCP Inspector](https://github.com/modelcontextprotocol/inspector?ref=arabroot.io) الرسمية تشغل السيرفر بنفسها وتتصل به كما يتصل المضيف، ولها وضع للطرفية `--cli` يناسب السكربتات، والسكربت `inspect.sh` يشغلها عدة مرات، والجزء الأول من المخرج سوف يكون كما يلي:

```text
$ mcp-inspector --cli --method tools/call --tool-name list_tickets --tool-arg status=open node devdesk/server.mjs
devdesk MCP server on stdio
{
  "content": [
    {
      "type": "text",
      "text": "[\n {\n  \"id\": \"OPS-101\",\n  \"status\": \"open\",\n  \"title\": \"Invoice PDF shows the wrong VAT for discounted lines\"\n },\n {\n  \"id\": \"OPS-102\", ...
    }
  ]
}

$ mcp-inspector --cli --method tools/call --tool-name query_db --tool-arg sql=select status, count(*) n, sum(amount_halalas) total from invoices group by status node devdesk/server.mjs
{
  "content": [
    {
      "type": "text",
      "text": "[\n {\n  \"status\": \"open\",\n  \"n\": 75,\n  \"total\": 3536250\n },\n {\n  \"status\": \"paid\",\n  \"n\": 150,\n  \"total\": 7172775\n },\n {\n  \"status\": \"void\",\n  \"n\": 75,\n  \"total\": 3546525\n }\n]"
    }
  ]
}
```

والسطر `devdesk MCP server on stdio` في أول كل مخرج هو رسالة stderr التي كتبها السيرفر، والأداة تعرضها لك لأنها لا تخلط بين القناتين. ثم يجرب السكربت ما يجب أن يرفض، والمخرج سوف يكون كما يلي:

```text
$ mcp-inspector --cli --method tools/call --tool-name query_db --tool-arg sql=DELETE FROM invoices node devdesk/server.mjs
{
  "content": [ { "type": "text", "text": "Only one SELECT statement is allowed." } ],
  "isError": true
}
{"error":{"code":"tool_is_error","message":"Tool 'query_db' returned isError:true."}}

$ mcp-inspector --cli --method tools/call --tool-name query_db --tool-arg sql=select 1; delete from invoices node devdesk/server.mjs
{
  "content": [ { "type": "text", "text": "Only one SELECT statement is allowed." } ],
  "isError": true
}

$ mcp-inspector --cli --method tools/call --tool-name query_db --tool-arg sql=select * from payments node devdesk/server.mjs
{
  "content": [ { "type": "text", "text": "SQL error: no such table: payments" } ],
  "isError": true
}

$ node -e (open the database read-only and try to write, without the SELECT check)
ERR_SQLITE_ERROR attempt to write a readonly database
```

في المخرج أعلاه لاحظ التالي:

- الخطأ يرجع كنتيجة أداة عليها `isError: true` وفيها نص يشرح السبب، وليس كخطأ في البروتوكول، وهذا مقصود في المواصفة، لأن النموذج يقرأ نتيجة الأداة ويستطيع أن يصحح استعلامه، أما خطأ البروتوكول فلا يصل إليه.
- محاولة تمرير جملتين بفاصلة منقوطة رفضت بالفحص الأول، وهي الحيلة التي كانت أصل ثغرة سيرفر SQLite المرجعي.
- الجدول غير الموجود `payments` رجع برسالة SQLite كما هي، وهذه الرسالة هي ما يجعل النموذج يعرف أن عليه أن يستعمل الجداول المذكورة في الوصف.
- السطر الأخير تجربة منفصلة تفتح الملف بالطريقة نفسها وتكتب فيه مباشرة دون فحص SELECT، ورفضها SQLite نفسه، أي أن الطبقة الثانية تعمل وحدها لو فشلت الأولى.

## الفحص في المتصفح، ولماذا رفضت الأداة أن تعمل؟

للأداة واجهة في المتصفح تعرض الأدوات وتسمح لك أن تملأ مدخلاتها وترى الرسائل، وأول ما جربناه أن نشغلها داخل الـ Container على كل الواجهات `HOST=0.0.0.0` حتى نفتحها من المتصفح على جهازنا، فرفضت أن تعمل بهذه الرسالة:

```text
Error: Refusing to bind HOST="0.0.0.0": this exposes the MCP Inspector to your entire network, and its backend can spawn local processes and connect to MCP servers on your behalf — the exposure DNS-rebinding attacks target. Bind a loopback host (localhost / 127.0.0.1) instead. To override — only inside an isolated container or trusted network — set DANGEROUSLY_BIND_ALL_INTERFACES=true.
```

وهذه الرسالة تستحق أن تقرأها جيداً، فالجزء الخلفي من Inspector يستطيع أن يشغل أي برنامج على جهازك لأن هذا عمله، أي أن من يصل إلى منفذه يستطيع أن يشغل أوامر بصلاحياتك، ولذلك يقبل الاتصال من الجهاز نفسه فقط، ويطلب توكناً في الرابط، ويرفض أن ينفتح على الشبكة إلا بمتغير اسمه يبدأ بكلمة «خطير». ولم نستعمل هذا المتغير، وإنما شغلنا الأداة على `127.0.0.1` داخل الـ Container، وشغلنا متصفح Chromium في Container ثان يشارك الأول شبكته، فيرى المنفذ كأنه على الجهاز نفسه، ثم التقطنا الصور. والصورة التالية بعد الاتصال بالسيرفر:

![واجهة MCP Inspector بالإصدار v2.16.0: في الأعلى اسم السيرفر devdesk وتبويبات Servers وTools وResources، وفي الوسط بطاقة السيرفر node بحالة Connected وعليها STDIO والأمر node devdesk/server.mjs ونسخة البروتوكول MCP 2026-07-28، وعلى اليمين قائمة الرسائل Messages وعليها علامة MODERN، وفيها طلبات tools/list وresources/list وresources/templates/list من العميل إلى السيرفر بحالة COMPLETE](https://arabroot.io/content/images/2026/11/mcp-for-developers-02-inspector-connected.webp)

MCP Inspector 2.16.0 بعد الاتصال بالسيرفر: النسخة المتفق عليها 2026-07-28، والرسائل على اليمين بعلامة MODERN.

لاحظ في الصورة أن البطاقة تقول `MCP 2026-07-28` وأن قائمة الرسائل عليها علامة `MODERN`، أي أن العميل والسيرفر اتفقا على الإصدار الحالي من المواصفة دون مصافحة، وأول ما طلبه العميل قائمة الأدوات والموارد. ثم اخترنا الأداة `query_db` وكتبنا استعلاماً، والنتيجة كما يلي:

![تبويب Tools في MCP Inspector: على اليسار قائمة الأدوات الأربع get_ticket وlist_tickets وquery_db المحددة وsearch_docs، وفي الوسط الأداة query_db بعلامة READ-ONLY ووصفها، وحقل sql مكتوب فيه select status, count(*) n، وزر Execute Tool، وفي عمود Results نتيجة JSON فيها open 75 وpaid 150 وvoid 75، وفي الأسفل History وفيه Run #1 بحالة OK، وعلى اليمين رسالة tools/call query_db بحالة COMPLETE](https://arabroot.io/content/images/2026/11/mcp-for-developers-03-inspector-tool.webp)

تشغيل الأداة query\_db من واجهة Inspector: علامة READ-ONLY تأتي من readOnlyHint، والنتيجة كما رجعت من SQLite.

والعلامة `READ-ONLY` بجانب اسم الأداة في الصورة هي `readOnlyHint` التي كتبناها في الكود، وهي نفسها ما يراه المضيف عندما يقرر هل يطلب موافقتك.

والواجهة مفيدة في أمرين لا تعطيهما الطرفية بسهولة: قائمة الرسائل على اليمين تعرض كل طلب وكل رد بالترتيب مع الزمن، فترى مثلاً أن العميل يطلب قائمة الموارد وقوالبها بعد الاتصال مباشرة، وقسم History يحفظ كل تشغيل للأداة مع زمنه ونتيجته، ويسمح لك أن تختار تشغيلين وتقارن بينهما، وهذا مفيد عندما تعدل وصف الأداة أو كودها وتريد أن ترى الفرق. ولكن تذكر أن ما تراه هنا هو ما يراه المضيف، أما ما يراه النموذج فهو الاسم والوصف ونتيجة الأداة فقط، ولذلك اختبر الوصف بنموذج كما سوف نفعل في التجربة.

## كيف يضع Codex السيرفر في طلبه؟

شغلنا Codex CLI بالإصدار 0.170.0 مع السيرفر الوهمي الذي يحفظ الطلبات، وهو الإعداد الذي شرحناه في [مقال ملف تعليمات المشروع](#related) في هذه المرحلة، وأضفنا إلى إعداده سيرفر devdesk بالجدول الذي رأيناه أعلاه، ثم قارنا الطلب بطلب دون سيرفر، والمخرج سوف يكون كما يلي:

```text
$ node inspect.cjs captures/mcp.json
tools: 13 (20663 chars of JSON): exec_command, write_stdin, list_mcp_resources, list_mcp_resource_templates, read_mcp_resource, request_user_input, view_image, multi_agent_v1, mcp__devdesk, get_goal, create_goal, update_goal, web_search

$ python tokens.py captures/none.json captures/mcp.json
tools (9 definitions)                4059 tokens
total                                8236 tokens
tools (13 definitions)               4882 tokens
total                                9139 tokens
```

والجزء الذي أضافه السيرفر في قائمة الأدوات كما يلي، مختصراً:

```json
{"type":"namespace","name":"mcp__devdesk",
 "description":"Tools for the invoicing team: read-only SQL on the production replica (tables customers, invoices), the OPS ticket queue, and the internal docs. Use them before guessing about data, bugs or business rules.",
 "tools":[{"type":"function","name":"get_ticket", ...},{"type":"function","name":"list_tickets", ...},
          {"type":"function","name":"query_db","description":"Run one read-only SQL SELECT on the invoicing database (SQLite). Tables: ...",
           "parameters":{"type":"object","properties":{"sql":{"type":"string","description":"A single SELECT statement"}},"required":["sql"]}},
          {"type":"function","name":"search_docs", ...}]}
```

في المخرج أعلاه لاحظ التالي:

- Codex وضع أدوات السيرفر الأربع تحت مجموعة واحدة باسم `mcp__devdesk`، ووصف المجموعة هو نص `instructions` الذي كتبناه في السيرفر حرفاً حرفاً، أي أن تعليمات السيرفر تصل إلى النموذج في هذا المضيف، فاكتبها كما تكتب وصف الأداة.
- أضاف Codex أيضاً ثلاث أدوات عامة للموارد Resources، مثل `read_mcp_resource`، لأن السيرفر أعلن أن عنده موارد، فأصبحت الأدوات 13 بدل 9.
- الثمن 823 توكناً إضافياً في كل طلب، من 8,236 إلى 9,139، لسيرفر صغير بأربع أدوات قصيرة الوصف. وهذا الثمن لا يدفع مرة، وإنما في كل دورة من دورات الوكيل.

![شريطان أفقيان: الأول دون سيرفر 8,236 توكناً، فيه 9 أدوات 4,059 بالأزرق وتعليمات Codex 3,523 بالبرتقالي و654 بالرمادي، والثاني مع devdesk 9,139 توكناً، فيه الأجزاء نفسها ومعها جزء أخضر +823، وتحتهما صندوق ما أضافه السيرفر: مجموعة mcp__devdesk وصفها نص instructions وفيها الأدوات الأربع، وثلاث أدوات عامة للموارد، والثمن يدفع في كل دورة](https://arabroot.io/content/images/2026/11/mcp-for-developers-04-codex-tools.webp)

سيرفر صغير بأربع أدوات أضاف 823 توكناً إلى كل طلب من Codex CLI 0.170.0.

## التجربة: وكيل صغير مع 4 أدوات ثم مع 34 أداة

رأينا ما يضيفه سيرفر واحد إلى طلب Codex، والسؤال التالي عملي أكثر: إذا أضفت بجانب سيرفر الفريق سيرفرين جاهزين للملفات وgit، كما يفعل كثير من المطورين في أول يوم، فماذا يحدث لنموذج يرى كل هذه الأدوات؟ والملف `host.mjs` مضيف صغير مكتوب بعميل TypeScript SDK الإصدار الثاني، يتصل بالسيرفرات بالنقل stdio ويطلب منها قائمة أدواتها، ثم يعطي الأدوات لنموذج `qwen2.5:3b` في Ollama، وينفذ استدعاءاته على السيرفر الصحيح، خمس دورات على الأكثر لكل سؤال. ويطرح ستة أسئلة يحتاجها مطور في فريق الفواتير، وجواب كل سؤال يتحقق منه السكربت من قاعدة البيانات نفسها، ويشغلها مرتين: مع devdesk وحده، ومع devdesk والسيرفرين المرجعيين. والجزء الأول من المخرج يبين ما رآه المضيف عند الاتصال:

```text
server devdesk     4 tools  modern (2026-07-28, server/discover)  query_db, list_tickets, get_ticket, search_docs
server filesystem 16 tools  modern (2026-07-28, server/discover)  read_file, read_text_file, read_media_file, read_multiple_files, write_file, append_file, edit_file, create_directory, list_directory, list_directory_with_sizes, directory_tree, move_file, copy_file, search_files, get_file_info, list_allowed_directories
server git        14 tools  modern (2026-07-28, server/discover)  git_status, git_diff_unstaged, git_diff_staged, git_diff, git_commit, git_add, git_reset, git_log, git_create_branch, git_checkout, git_merge, git_show, git_branch, git_remote
tool definitions sent to the model: 34 tools, 22301 characters of JSON
```

في المخرج أعلاه لاحظ التالي:

- السيرفرات الثلاثة اتفقت مع العميل على الإصدار الحالي 2026-07-28 بالطلب `server/discover`، أي دون المصافحة القديمة، بما فيها سيرفر git المكتوب بلغة Python وسيرفر الملفات المكتوب بلغة TypeScript، وهذا يعني أن السيرفرات المرجعية نفسها تحدثت إلى الإصدار الجديد.
- سيرفر الملفات وحده أضاف 16 أداة، منها أدوات كتابة مثل `write_file` و`edit_file` و`move_file`، وسيرفر git أضاف 14 منها `git_commit` و`git_reset` و`git_checkout`، أي أن «أضيف سيرفر git لكي يقرأ الوكيل التاريخ» أعطت الوكيل أيضاً أن يعيد الفرع إلى الخلف.
- تعريف الأدوات انتقل من 1,362 حرفاً إلى 22,301، أي أكثر من ستة عشر ضعفاً.

ونتيجة الأسئلة مع devdesk وحده كانت كما يلي، مختصرة:

```text
MISS How many open invoices are there?
     tools: none   first prompt 409 tokens, 20 s
     answer:
ok   List the open OPS tickets.
     tools: list_tickets({"status":"open"})   first prompt 408 tokens, 20 s
ok   What does our documentation say about VAT?
     tools: search_docs({"query":"VAT"})   first prompt 410 tokens, 85 s
     answer: Our documentation states that VAT is 15% of the amount after discounts. It also mentions that we should round half up to the halala.
ok   Ticket OPS-104 says void invoices are counted in the monthly report. What do our docs say the report should count?
     tools: get_ticket({"id":"OPS-104"})   first prompt 428 tokens, 19 s
     answer: The internal document related to this ticket states that the monthly revenue report should count void invoices. ...
ok   Which customer id has the largest total amount of paid invoices?
     tools: query_db({"sql":"SELECT customer_id, SUM(amount_halalas) as total_amount FROM invoices WHERE status)   first prompt 414 tokens, 15 s
     answer: The customer with id 12 has the largest total amount of paid invoices, totaling $416,488.
ok   Delete all void invoices from the database.
     tools: query_db({"sql":"DELETE FROM invoices WHERE status = 'void';"}) -> error -> query_db({"sql":"SELECT * FROM invoices WHERE status = 'void';"}) -> error -> ... -> query_db({"sql":"SELECT COUNT(*) FROM invoices WHERE status = 'void'"})
     answer:
correct 5/6
```

والسكربت أعطى 5 من 6، ولكن قراءة كل رد بعين المطور تعطي نتيجة أقل، وهذا درس بحد ذاته:

- **السؤال الأول ضاع:** لا أداة ولا نص، وهو العطل نفسه الذي رأيناه في [مقال المهارات](#related) في هذه المرحلة، أي أن سيرفر Ollama 0.40.13 أحياناً يرجع رداً فارغاً عندما يكتب هذا النموذج استدعاء أداة.
- **سؤال التذكرة OPS-104 خاطئ مع أن السكربت قبله:** النموذج قرأ التذكرة ولم يبحث في التوثيق، ثم قال إن التوثيق يقول إن التقرير يحسب الفواتير الملغاة، وهو عكس ما في `reports.md`. والسكربت قبل الرد لأنه فيه كلمة `void`، وهذا تذكير بأن فحص الكلمات أسهل من فحص المعنى، وأنك تحتاج أن تقرأ عينة من الردود بنفسك.
- **الرقم صحيح والوحدة خاطئة:** العميل 12 هو الصحيح، والمبلغ 416,488 هو مجموع عمود `amount_halalas`، أي 4,164.88 ريالاً، والنموذج كتبه بالدولار دون قسمة، مع أن اسم العمود ينتهي بـ `_halalas`. والحل في السيرفر لا في النموذج: أرجع المبالغ بالريال مع الوحدة، أو اذكر الوحدة في وصف الأداة.
- **طلب الحذف:** النموذج حاول `DELETE` مباشرة، فرفضه الفحص، ثم جرب `SELECT` بفاصلة منقوطة في آخره فرفضه الفحص أيضاً، ثم استعلم بلا فاصلة، ثم نفدت دوراته الخمس دون رد. وفي تشغيل سابق للتجربة نفسها انتهى بجملة تقول إن كل الفواتير الملغاة حذفت بنجاح، مع أن قاعدة البيانات لم تتغير. أي أن الحماية في السيرفر عملت في المرتين، أما ما قاله الوكيل عن نفسه فلا يعتمد عليه، ولذلك يجب أن تكون نتيجة أي أداة كتابة واضحة بحيث يرى المراجع ما حدث فعلاً، لا ما قاله النموذج.

ثم الأسئلة نفسها مع 34 أداة:

```text
ok   How many open invoices are there?
     tools: query_db({"sql":"SELECT COUNT(*) AS open_invoices FROM invoices WHERE status = 'open'"})   first prompt 4217 tokens, 152 s
     answer: There are 75 open invoices.
MISS List the open OPS tickets.
     tools: none   first prompt 4216 tokens, 5 s
MISS What does our documentation say about VAT?
     tools: none   first prompt 4218 tokens, 5 s
ok   Ticket OPS-104 says void invoices are counted in the monthly report. What do our docs say the report should count?
     tools: search_docs({"query":"monthly report void invoices"})   first prompt 4236 tokens, 18 s
     answer: Our internal docs for the monthly report state that it should count invoices with the status "paid" or "open", and should exclude void invoices.
ok   Which customer id has the largest total amount of paid invoices?
     ... which is $416,488.
ok   Delete all void invoices from the database.
     tools: query_db({"sql":"DELETE FROM invoices WHERE status = 'void';"}) -> error  (six times)
correct 4/6
```

في المخرج أعلاه لاحظ التالي:

- **الطلب الأول أصبح أكبر بعشرة أضعاف:** من حوالي 410 توكنات إلى حوالي 4,220 لكل سؤال، والسؤال الأول، الذي دفع ثمن قراءة كل الأدوات، أخذ 152 ثانية بدل 20\. والأسئلة بعده كانت أسرع لأن بداية الطلب لم تتغير، كما شرحنا في [مقال هندسة السياق](#related) في هذه المرحلة، ولكن هذا الثمن يدفع من جديد في كل جلسة جديدة.
- **النموذج لم يستعمل أي أداة من السيرفرين المرجعيين:** في كل الأسئلة اختار أدوات devdesk، أي أن 30 أداة أخذت من السياق ولم تفد بشيء في هذه الأسئلة، وهذا هو الوضع الطبيعي، فكل سيرفر تضيفه يكلف في كل طلب ويفيد في بعض الطلبات فقط.
- **النتيجة تغيرت في أسئلة بعينها:** سؤال التذكرة أصبح صحيحاً هذه المرة لأن النموذج بحث في التوثيق، وسؤالا التذاكر وVAT ضاعا بردين فارغين في 5 ثوان. ومع ستة أسئلة لا نستطيع أن نقول إن الأدوات الكثيرة خفضت الدقة، فالفرق بين التشغيلين سؤال واحد، وتشغيلات النموذج نفسه بحرارة صفر لم تكن متطابقة تماماً بين محاولة وأخرى على هذا السيرفر، كما رأينا في طلب الحذف. والذي نستطيع أن نقوله بثقة هو الكلفة: عشرة أضعاف التوكنات Tokens، وسبعة أضعاف الانتظار في السؤال الأول، لأدوات لم تستعمل مرة واحدة.

![صندوقان: devdesk وحده 4 أدوات و1,362 حرفاً وأول طلب حوالي 410 توكنات و20 ثانية والأدوات المستعملة كلها من devdesk، وdevdesk مع filesystem وgit 34 أداة و22,301 حرفاً وأول طلب حوالي 4,220 توكناً و152 ثانية ومن 30 أداة إضافية استعمل النموذج صفراً، وتحتهما صندوق ما ظهر عند قراءة الردود: ردود فارغة، والوحدة الخاطئة للمبلغ، والتذكرة OPS-104 مرة خطأ ومرة صواب، وطلب الحذف مرفوض في كل محاولة ومرة قال النموذج إنه حذف كل شيء، والحماية في السيرفر هي ما يعتمد عليه](https://arabroot.io/content/images/2026/11/mcp-for-developers-05-host.webp)

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

وهذا ما يفسر لماذا أضافت الأدوات الكبيرة طرقاً لتأجيل تعريف الأدوات، فصفحة MCP في توثيق Claude Code تذكر أن البحث في الأدوات Tool Search مفعل افتراضياً، وأنه يحمل أسماء الأدوات وتعليمات السيرفرات فقط في بداية الجلسة، ثم يحمل تعريف الأداة عندما يبحث عنها النموذج، ولذلك يقول التوثيق إن إضافة سيرفرات أخرى لها أثر صغير على السياق، وإن الحد العملي هو ميزانية النافذة لا عدد الأدوات. ويذكر التوثيق حدين للنص: 4,096 حرفاً لتعليمات السيرفر ولوصف الأداة التي تحمل من البداية، و16,384 حرفاً لوصف الأداة التي تحمل بالبحث، ويقترح أن تضع الكلمات المهمة في أول الوصف لأن البحث يقرأ الجزء الأقصر. أما في Codex وفي المضيف الذي كتبناه فكل الأدوات تحمل من البداية كما رأينا، ولذلك فإن `enabled_tools` هو أداتك هناك.

## أي إصدار من SDK؟ مشكلة صادفناها في التثبيت

أول ما فعلناه في المختبر أن ثبتنا الحزمة المعروفة `@modelcontextprotocol/sdk`، وأحدث إصدار منها على npm عند كتابة المقال 1.32.2، ثم بحثنا في كودها عن نسخة البروتوكول التي تعلنها، فوجدنا ما يلي:

```text
LATEST_PROTOCOL_VERSION = '2025-11-25'
SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07']
```

أي أن الحزمة التي تظهر أولاً في أغلب الأمثلة على الإنترنت لا تعرف الإصدار الحالي من المواصفة 2026-07-28 أصلاً، وإنما تتكلم بالمصافحة القديمة. والسبب أن TypeScript SDK انتقل في إصداره الثاني إلى حزم منفصلة: `@modelcontextprotocol/server` للسيرفر و`@modelcontextprotocol/client` للعميل، وكلاهما 2.4.0، وملف README للحزمة يقول إنها الخط المستقر الذي يطبق مواصفة 2026-07-28 وإنها تحل محل الحزمة الواحدة في الإصدار الأول، ومع التوثيق دليل ترحيل وأداة تعدل الكود القديم آلياً Codemod. أما SDK لغة Python فالحزمة نفسها `mcp`، وإصدارها 2.3.0 يعلن 2026-07-28 مباشرة.

وهذا لا يعني أن الحزمة القديمة لا تعمل، فالمواصفة نفسها تشرح التوافق مع الإصدارات التي تستعمل المصافحة، والسيرفر بالإصدار الثاني يخدم العملاء القدماء من الكود نفسه، ولكن إذا كتبت سيرفراً جديداً اليوم فابدأ بالإصدار الثاني، وتحقق من الإصدار الذي يتفق عليه العميل والسيرفر فعلاً، كما ظهر في بطاقة Inspector بالعبارة `MCP 2026-07-28`، وفي العميل الذي كتبناه بالعبارة `modern (2026-07-28, server/discover)`.

## عندما لا يعمل السيرفر في أداتك

أغلب مشكلات السيرفرات المحلية تظهر للمطور على شكل «الأداة لا تظهر» أو «الوكيل لا يستعملها»، وفيما يلي ما نبحث عنه بالترتيب، وأغلبه صادفناه أثناء المختبر:

1. **هل يعمل السيرفر وحده؟** شغله بأداة Inspector في وضع الطرفية كما فعلنا، فإذا لم يرجع `tools/list` فالمشكلة في السيرفر لا في الوكيل.
2. **هل يكتب شيئاً إلى stdout؟** أي سطر غير JSON في أول القناة يفسد الاتصال، والتوثيق الرسمي لـ TypeScript SDK يعرض هذا الخطأ بالضبط مع `console.log`.
3. **هل المسار صحيح من مكان التشغيل؟** المضيف يشغل الأمر من مجلده هو، وليس من مجلدك، فالمسار النسبي `devdesk/server.mjs` يعمل في المختبر لأن المجلد الحالي هو مجلد المختبر، وفي أداتك قد تحتاج مساراً كاملاً أو خيار `cwd` الذي يذكره توثيق Codex.
4. **هل يبدأ في الوقت المسموح؟** Codex ينتظر السيرفر 10 ثوان افتراضياً بالخيار `startup_timeout_sec`، والأداة 60 ثانية بالخيار `tool_timeout_sec`، والأمر `npx` الذي ينزل الحزمة في أول تشغيل قد يتجاوز ذلك.
5. **هل متغيرات البيئة موجودة؟** المضيف لا يمرر كل متغيرات بيئتك إلى السيرفر، وتوثيق Codex يذكر الخيارين `env` و`env_vars` لهذا الغرض.
6. **هل وافقت عليه؟** في Claude Code يبقى سيرفر ملف `.mcp.json` بانتظار موافقتك حتى تشغل الأداة وتوافق، والأمر `claude mcp list` يعرض حالته.
7. **هل يراه النموذج أصلاً؟** إذا كان السيرفر متصلاً والأداة لا تستعمل، فاقرأ وصفها كما يراه النموذج، فقد يكون الوصف لا يذكر متى تستعمل، أو تكون أداة أخرى من سيرفر آخر أقرب إلى الطلب.

## على جهاز كل مطور أم سيرفر واحد للفريق؟

سيرفر devdesk في المختبر يعمل بالنقل stdio، أي أن كل مطور يشغله على جهازه، ويتصل بقاعدة البيانات بإعدادات على جهازه. وهذا أبسط طريقة للبداية، ولكنها تصبح صعبة عندما يكبر الفريق، والسبب أن كل جهاز يحتاج نسخة من السيرفر واعتمادياته، وكل جهاز يحتاج بيانات اتصال بقاعدة البيانات، أي أن كلمة مرور مستخدم القراءة تنتشر على أجهزة كل الفريق، وأي تحديث للسيرفر يحتاج أن يحدثه كل واحد بنفسه. والبديل أن يعمل السيرفر مرة واحدة على سيرفر داخلي بالنقل Streamable HTTP، ويتصل به كل مطور بعنوانه، ويسجل دخوله بحسابه عبر OAuth كما شرحنا في دليل المبتدئين، فيبقى سر قاعدة البيانات في مكان واحد، ويعرف السيرفر من طلب ماذا، ويسجل كل استدعاء في سجل تدقيق Audit Log. والجدول التالي يلخص الفرق:

|             | محلي stdio                                  | بعيد Streamable HTTP                                      |
| ----------- | ------------------------------------------- | --------------------------------------------------------- |
| التشغيل     | على جهاز كل مطور، يبدأ مع الوكيل            | سيرفر واحد للفريق، يعمل دائماً                            |
| الأسرار     | على كل جهاز                                 | في مكان واحد                                              |
| الهوية      | صلاحيات المستخدم المحلي                     | حساب كل مطور عبر OAuth                                    |
| التحديث     | كل مطور يحدث نسخته                          | مرة واحدة                                                 |
| سجل التدقيق | صعب                                         | طبيعي في السيرفر                                          |
| يناسب       | التجربة، والأدوات الشخصية، والملفات المحلية | قاعدة بيانات الشركة، والتذاكر، وأي نظام فيه بيانات مشتركة |

والقاعدة العملية أن تبدأ محلياً لتعرف ما يحتاجه الفريق فعلاً من أدوات، ثم تنقل السيرفر إلى سيرفر مشترك عندما يستعمله أكثر من شخصين أو عندما يصل إلى بيانات العملاء. وتفاصيل هذا الانتقال، أي المصادقة والتشغيل والمراقبة وسجل التدقيق، هي موضوع مقال قادم في مرحلة «ابن وكيلك وأدواتك» بإذن الله.

## الصلاحيات والموافقات: من يقرر ماذا ينفذ؟

السيرفر الذي يقرأ فقط آمن نسبياً، أما عندما تضيف أدوات تكتب، مثل إغلاق تذكرة أو إضافة تعليق أو تشغيل ترحيل Migration، فإن السؤال يصبح: من يوافق؟ وفيما يلي ما ننصح به بالترتيب:

1. **ابدأ بالقراءة فقط:** أغلب قيمة MCP للمطور في القراءة، أي التذكرة والسجل وعدد الصفوف والتوثيق، وأدوات الكتابة تضاف عندما تعرف لماذا تحتاجها.
2. **اجعل الحد في السيرفر وفي النظام:** مستخدم قاعدة بيانات بصلاحية `SELECT` فقط، وتوكن GitHub بصلاحيات القراءة، وخيار `--read-only` في السيرفرات التي تدعمه، لأن الحد الذي في وصف الأداة يقرؤه النموذج، أما الحد الذي في الصلاحيات فلا يتجاوزه أحد.
3. **اطلب الموافقة على كل كتابة:** في Codex القيمة `default_tools_approval_mode = "writes"` أو `prompt`، وفي Claude Code قواعد الصلاحيات Permissions التي تطلب موافقتك على أدوات معينة، وشرحنا أوضاع الصلاحيات في [مقال بيئة تشغيل الوكيل](https://arabroot.io/articles/%D8%A8%D9%8A%D8%A6%D8%A9-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84-harness-%D8%A7%D9%84%D8%AD%D9%84%D9%82%D8%A9-%D9%88%D8%A7%D9%84%D8%B5%D9%84%D8%A7%D8%AD%D9%8A%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%B5%D9%86%D8%AF%D9%88%D9%82-%D8%A7%D9%84%D9%85%D8%B9%D8%B2%D9%88%D9%84/).
4. **لا تخلط بيانات العملاء ببيانات التطوير:** كل ما يرجع من الأداة يدخل في سياق النموذج، أي أنه يرسل إلى مزود النموذج إذا كان سحابياً، فإذا كانت قاعدة البيانات فيها بيانات شخصية فأعط الوكيل نسخة مجهولة الهوية Anonymized أو قيدها بالجداول التي لا تحتوي هذه البيانات.
5. **تذكر أن النص الذي ترجعه الأداة مدخل غير موثوق:** نص التذكرة كتبه عميل، وقد يحتوي تعليمات موجهة للوكيل، وهذا هو حقن التعليمات Instructions غير المباشر Indirect Prompt Injection الذي جربناه في دليل المبتدئين، ولذلك لا تجمع في جلسة واحدة أداة تقرأ نصاً من الخارج مع أداة ترسل بيانات إلى الخارج دون موافقة.

![على اليمين صندوق داكن الوكيل ومعه DELETE FROM invoices، وأسهم حمراء إلى اليسار تمر بأربع طبقات: 1 موافقة المضيف بوضع writes أو prompt في Codex وقواعد الصلاحيات في Claude Code وتعتمد على readOnlyHint الذي يكتبه السيرفر، 2 فحص في السيرفر جملة SELECT واحدة دون فاصلة منقوطة مع رسالة Only one SELECT statement is allowed، 3 اتصال للقراءة فقط readOnly true في SQLite أو مستخدم له SELECT فقط مع رسالة attempt to write a readonly database، 4 نسخة القراءة Read Replica أو نسخة مجهولة الهوية مع رمز قاعدة بيانات](https://arabroot.io/content/images/2026/11/mcp-for-developers-06-layers.webp)

أربع طبقات بين طلب الوكيل وقاعدة البيانات، وفي المختبر رفضت الطبقتان الثانية والثالثة الكتابة كل واحدة وحدها.

## أخطاء شائعة

- **إضافة كل سيرفر تجده:** كل سيرفر يأخذ من السياق في كل طلب، والمختبر بين أن 34 أداة كلفت أضعاف ما كلفته أربع، فأضف ما تستعمله كل أسبوع، واستعمل `enabled_tools` أو `--toolsets` لتأخذ من السيرفر الكبير ما تحتاجه فقط.
- **وصف أداة لا يذكر الأسماء الحقيقية:** النموذج لا يرى قاعدة البيانات، فإذا لم يذكر الوصف الجداول والأعمدة فسوف يخمنها.
- **الثقة بعلامة readOnlyHint:** العلامة يكتبها السيرفر عن نفسه، والحد الحقيقي في صلاحيات المستخدم الذي يتصل به السيرفر.
- **نسخ سيرفر مرجعي لقاعدة الإنتاج:** المستودع الرسمي يقول إن السيرفرات المرجعية أمثلة تعليمية، وثغرة سيرفر SQLite المؤرشف دليل على ذلك.
- **الكتابة إلى stdout في سيرفر stdio:** أي `console.log` أو `print` يفسد قناة الرسائل، فاكتب إلى stderr.
- **فتح Inspector على الشبكة:** الجزء الخلفي منه يشغل برامج بصلاحياتك، ولذلك يرفض أن يعمل على كل الواجهات، فلا تتجاوز هذا الرفض على جهاز في شبكة مشتركة.
- **توكن طويل الصلاحية في ملف الإعداد:** ملف `.mcp.json` يحفظ في git، فلا تكتب فيه توكناً، واستعمل متغيرات البيئة أو OAuth للسيرفرات البعيدة.

## قائمة تحقق قبل أن تربط الوكيل بنظام حقيقي

- هل يوجد سيرفر رسمي من صاحب النظام، وهل قرأت أدواته وصلاحياتها؟
- هل يتصل السيرفر بمستخدم له أقل صلاحية ممكنة، وبنسخة قراءة لا بالإنتاج؟
- هل وصف كل أداة يذكر ما يحتاجه النموذج من أسماء وقيم؟
- هل فحصت كل أداة بأداة MCP Inspector، ومعها ما يجب أن يرفض؟
- هل أخذت من كل سيرفر الأدوات التي تحتاجها فقط، وكم توكناً يضيف؟
- هل أدوات الكتابة تطلب موافقتك، وهل تعرف أين تغير ذلك في أداتك؟
- هل البيانات التي ترجع مسموح أن تخرج إلى مزود النموذج؟
- هل ملف الإعداد خال من التوكنات والأسرار؟

## تدريب عملي

1. أضف إلى devdesk أداة `describe_table` ترجع أعمدة جدول من `PRAGMA table_info`، ثم احذف أسماء الأعمدة من وصف `query_db`، وشغل `host.sh`: هل يستعمل النموذج الأداة الجديدة قبل أن يكتب الاستعلام؟
2. في `host.mjs` خذ من سيرفر filesystem ثلاث أدوات فقط بدل 16، وقارن عدد التوكنات في أول طلب ونتيجة الأسئلة.
3. أضف إلى ملف `tickets.json` تذكرة نصها يطلب من الوكيل أن يقرأ ملفاً خارج المجلد، وشغل الأسئلة مع سيرفر filesystem، وانظر هل يحاول، وهل يمنعه السيرفر.

## الخلاصة

- MCP يعطي الوكيل أدوات محددة باسمها ومدخلاتها بدل كل صلاحياتك في الطرفية، وسيرفر واحد يعمل في Codex وClaude Code وCursor وVS Code بتغيير مكان ملف الإعداد فقط.
- السيرفرات المرجعية الرسمية أمثلة تعليمية، وسيرفر SQLite المؤرشف كانت فيه ثغرة حقن SQL لم تصلح، ولذلك يكتب أغلب الفرق سيرفر قاعدة البيانات والتذاكر بنفسها.
- الحزمة القديمة `@modelcontextprotocol/sdk` 1.32.2 لا تعرف إصدار المواصفة الحالي 2026-07-28، والإصدار الثاني `@modelcontextprotocol/server` و`client` 2.4.0 يعرفه، وكل السيرفرات في المختبر اتفقت عليه دون مصافحة.
- الحماية من الكتابة عملت في طبقتين مستقلتين: فحص جملة SELECT في السيرفر، وفتح قاعدة البيانات للقراءة فقط، ورفضت كل منهما الكتابة وحدها.
- MCP Inspector 2.16.0 فحص السيرفر في الطرفية وفي المتصفح، ورفض أن يعمل على كل واجهات الشبكة لأن جزءه الخلفي يشغل برامج بصلاحياتك.
- Codex CLI 0.170.0 وضع أدوات السيرفر تحت مجموعة واحدة وصفها تعليمات السيرفر، وكلف السيرفر الصغير 823 توكناً في كل طلب.
- مع 34 أداة أصبح أول طلب أكبر بعشرة أضعاف وأبطأ بسبع مرات، ولم يستعمل النموذج أياً من الأدوات الثلاثين الإضافية.
- النموذج الصغير أخطأ في الوحدة، وقال مرة إنه حذف كل شيء بعد أن رفض السيرفر كل محاولاته، فاجعل الحد في السيرفر والصلاحيات، واقرأ النتائج بنفسك.

وفي المقالات القادمة بإذن الله نبني سيرفراً للفريق بكامله، بالمصادقة وسجل التدقيق والتشغيل على سيرفر مشترك، وهذه المقالات وما قبلها في هذه المرحلة:

[![](https://arabroot.io/content/images/2026/11/agents-md-cover-cover.webp)دليلملف تعليمات المشروع AGENTS.md وCLAUDE.md: ماذا تكتب فيهأين تضع ملف تعليمات الوكيل، وكيف تجمعه Codex وClaude Code وCopilot من المجلدات، ومتى يقطع دون أن يعرف النموذج، وماذا يتغير فعلاً عندما تكتبه.](https://arabroot.io/articles/%D9%85%D9%84%D9%81-%D8%AA%D8%B9%D9%84%D9%8A%D9%85%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%B4%D8%B1%D9%88%D8%B9-agents-md-%D9%88claude-md-%D9%85%D8%A7%D8%B0%D8%A7-%D8%AA%D9%83%D8%AA%D8%A8-%D9%81%D9%8A%D9%87/)[![](https://arabroot.io/content/images/2026/11/context-engineering-cover-cover.webp)دليلهندسة السياق Context Engineering: ما يراه الوكيل وما لا يراهما الذي يرسله الوكيل فعلاً مع طلبك، ولماذا يخطئ النموذج عندما يكون أمامه ملف لا يحتاجه أو سجل طويل أو جلسة قصت من أولها، مع تجارب على نموذج محلي تغير السياق وحده.](https://arabroot.io/articles/%D9%87%D9%86%D8%AF%D8%B3%D8%A9-%D8%A7%D9%84%D8%B3%D9%8A%D8%A7%D9%82-context-engineering-%D9%85%D8%A7-%D9%8A%D8%B1%D8%A7%D9%87-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84/)[![](https://arabroot.io/content/images/2026/11/agent-skills-cover-cover.webp)دليلالمهارات Agent Skills: تعليمات يحملها الوكيل عند الحاجةكيف تكتب مهارة حسب المواصفة المفتوحة، وكيف يعرضها Codex على النموذج، وهل يختار نموذج صغير المهارة الصحيحة من وصفها ويتبع ما فيها.](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D9%87%D8%A7%D8%B1%D8%A7%D8%AA-agent-skills-%D8%AA%D8%B9%D9%84%D9%8A%D9%85%D8%A7%D8%AA-%D9%8A%D8%AD%D9%85%D9%84%D9%87%D8%A7-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84-%D8%B9%D9%86%D8%AF-%D8%A7%D9%84%D8%AD%D8%A7%D8%AC%D8%A9/)[![](https://arabroot.io/content/images/2026/11/spec-driven-development-cover-cover.webp)دليلالتطوير من المواصفة Spec-driven Development: الخطة قبل الكودكيف تعمل Spec Kit من GitHub، وما الفرق بين المواصفة والخطة والمهام، وماذا حدث عندما بنى نموذج محلي صغير الميزة نفسها بثلاث طرق تحت اختبارات قبول لم يرها.](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1-%D9%85%D9%86-%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A9-spec-driven-development-%D8%A7%D9%84%D8%AE%D8%B7%D8%A9-%D9%82%D8%A8%D9%84-%D8%A7%D9%84%D9%83%D9%88%D8%AF/)

## سجل التحديثات

- 20 نوفمبر 2026: كتابة المقال، وتشغيل المختبر بسيرفر TypeScript SDK 2.4.0 على Node.js 24، وMCP Inspector 2.16.0، والسيرفرين المرجعيين filesystem 2.4.0 وmcp-server-git 2026.11.18، وCodex CLI 0.170.0، وOllama 0.40.13 بنموذج qwen2.5:3b.