كيف تبني أول خادم MCP بلغة Python (وتختبره دون أي تطبيق ذكاء اصطناعي)

اكتب خادم MCP صغيرًا بلغة Python يضم أداتين، واختبره دون أي تطبيق ذكاء اصطناعي، وافحصه باستخدام MCP Inspector، ثم اربطه بمحرر الأكواد أو المساعد الذي تستخدمه.

Graphic of a small server box connected to a chat bubble and a code editor, for a guide to building an MCP server in Python

تشرح معظم أدلة Model Context Protocol (MCP) كيفية تثبيت خادم كتبه شخص آخر. أما هذا الدليل فيريك كيف تبني خادم MCP خاصًا بك بلغة Python: خادمًا صغيرًا يضم أداتين يمكن لأي تطبيق ذكاء اصطناعي يدعم MCP استدعاؤهما. ستبنيه، وتختبره دون أي تطبيق ذكاء اصطناعي، وتفحصه بأداة MCP Inspector الرسمية، ثم تربطه بمحرر أكواد أو مساعد ذكي.

أهم النقاط

  • غيّرت النسخة 2.x من MCP Python SDK الرسمية اسم فئة الخادم إلى MCPServer، لذا لم تعد كثير من الدروس القديمة تعمل كما كُتبت.
  • يكفي أن تزيّن دالة بـ @mcp.tool() لتصبح أداة؛ ويأتي اسمها ووصفها ومخطط مدخلاتها من الكود الذي تكتبه.
  • اختبر الخادم في الذاكرة باستخدام فئة Client في SDK، ثم عبر stdio باستخدام MCP Inspector الرسمي.
  • اربطه بـ Cursor أو VS Code أو Claude Desktop بإعطاء التطبيق أمر تشغيل عبر uv يتضمن مسارًا مطلقًا.

حتى 15 نوفمبر 2026، بلغت Python SDK الرسمية الإصدار 2.3.0 (صدر في 2 أكتوبر 2026)، وبلغت MCP Inspector الإصدار 2.15.0 (صدر في 12 نوفمبر 2026). غيّرت SDK 2.x اسم فئة الخادم الرئيسية، لذا لم تعد كثير من الدروس القديمة تعمل كما كُتبت. نُفّذت أوامر المشروع والاختبار وInspector الواردة أدناه على هذين الإصدارين.

ما هو خادم MCP

MCP معيار مفتوح المصدر لربط تطبيقات الذكاء الاصطناعي بالأنظمة الخارجية. تكفيك ثلاثة مصطلحات من وثائق SDK لمتابعة الشرح:

  • المضيف (host) هو تطبيق الذكاء الاصطناعي الذي تتحدث إليه، مثل مساعد دردشة أو محرر أكواد.
  • العميل (client) يعيش داخل المضيف ويتحدث بروتوكول MCP.
  • الخادم (server) هو ما ستبنيه. يمكنه تقديم أدوات (دوال يستدعيها النموذج)، وموارد (بيانات يحمّلها التطبيق)، ومطالبات prompts (قوالب يختارها المستخدم).

يركّز هذا الدليل على الأدوات فقط. الأداتان اللتان ستكتبهما، عدّاد كلمات وحاسبة تواريخ، تؤديان عملًا دقيقًا يتقنه الكود أكثر من تقديرات النموذج.

فيديو: The Model Context Protocol (MCP) (Anthropic)

ما الذي تحتاجه

  • uv، مدير مشاريع Python المستخدم في درس MCP الرسمي. يحمّل Python تلقائيًا إن لم يجد إصدارًا مناسبًا. تتطلب SDK إصدار Python 3.10 أو أحدث.
  • Node.js، وتحتاجه فقط لتشغيل Inspector في الخطوة 4. يتطلب Inspector 2.15.0 إصدار Node ^22.23.4 || ^24.22.1 || >=26.12.1.
  • تطبيق يدعم MCP للخطوة 5 (اختياري).

ثبّت uv على macOS أو Linux:

الطرفية
curl -LsSf https://astral.sh/uv/install.sh | sh

وعلى Windows، في PowerShell:

الكود
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

أعد تشغيل الطرفية بعد ذلك ليتعرّف النظام على الأمر uv.

بالأرقام

2.3.0إصدار Python SDK المستخدم

2.15.0إصدار MCP Inspector المستخدم

3.10الحد الأدنى لإصدار Python

الخطوة 1: أنشئ المشروع

الطرفية
uv init --bare handy-tools
cd handy-tools
uv add "mcp[cli]"

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

الطرفية
uv run mcp version

المخرجات المتوقعة:

الكود
MCP version 2.3.0

الخطوة 2: اكتب الخادم

أنشئ ملفًا باسم server.py في مجلد المشروع:

الكود
from datetime import date

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("Handy Tools")


@mcp.tool()
def count_words(text: str) -> int:
    """Count the words in a piece of text."""
    return len(text.split())


@mcp.tool()
def days_between(start: str, end: str) -> int:
    """Count the days from one date to another. Dates use YYYY-MM-DD format."""
    try:
        first = date.fromisoformat(start)
        second = date.fromisoformat(end)
    except ValueError:
        raise ToolError("Dates must look like 2026-11-15 (YYYY-MM-DD).")
    return (second - first).days


if __name__ == "__main__":
    mcp.run()

وظيفة كل جزء:

  • MCPServer("Handy Tools") ينشئ الخادم. في SDK 2.x تستورده من mcp.server.
  • @mcp.tool() يحوّل الدالة إلى أداة. تقرأ SDK اسم الأداة من اسم الدالة، ووصفها من الـ docstring، ومخطط مدخلاتها من تلميحات الأنواع (type hints). لن تكتب أي JSON.
  • ToolError يرسل رسالة مفهومة إلى النموذج، فيتمكن من تصحيح وسائطه والمحاولة مجددًا.
  • mcp.run() دون وسائط يشغّل الخادم عبر stdio: يطلق المضيف ملفك كعملية فرعية ويتواصل معه عبر stdin وstdout.
مخطط يعرض أجزاء ملف خادم MCP بسيط بلغة Python ووظيفة كل جزء

الخطوة 3: اختبره من Python

تتضمن SDK فئة Client يمكنها الاتصال بكائن الخادم في الذاكرة، دون عملية فرعية ولا منفذ ولا ذكاء اصطناعي. أنشئ الملف check.py بجانب server.py:

الكود
import asyncio

from mcp import Client

from server import mcp


async def main() -> None:
    async with Client(mcp) as client:
        tools = await client.list_tools()
        print([tool.name for tool in tools.tools])

        result = await client.call_tool("count_words", {"text": "the quick brown fox"})
        print(result.structured_content)

        result = await client.call_tool("days_between", {"start": "2026-11-15", "end": "2027-01-01"})
        print(result.structured_content)

        result = await client.call_tool("days_between", {"start": "tomorrow", "end": "2027-01-01"})
        print(result.is_error, result.content[0].text)


asyncio.run(main())

شغّله:

الطرفية
uv run check.py

المخرجات المتوقعة:

الكود
['count_words', 'days_between']
{'result': 4}
{'result': 47}
True Error executing tool days_between: Dates must look like 2026-11-15 (YYYY-MM-DD).

سترى أيضًا سطر سجل INFO عن الاستدعاء الفاشل، وهو الخادم يسجّل ToolError. لاحظ أن التاريخ الخاطئ لم يرفع استثناءً في العميل: فاستدعاء الأداة الفاشل يعود كنتيجة عادية تكون فيها قيمة is_error هي True.

هل تعلم؟

استدعاء الأداة الفاشل لا يرفع استثناءً في العميل، بل يعود كنتيجة عادية قيمة is_error فيها True، وتحمل رسالة ToolError.

الخطوة 4: افحصه باستخدام MCP Inspector

MCP Inspector هو أداة الاختبار الخاصة بمشروع MCP نفسه. يشغّل وضع CLI فيه خادمك بالطريقة التي يشغّله بها مضيف حقيقي، ويطبع ما يعود منه. من مجلد المشروع:

الطرفية
npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list

في التشغيل الأول سيطلب الإذن لتنزيل الحزمة. بعدها يُفترض أن ترى JSON يسرد count_words وdays_between، ولكلٍّ منهما مخطط المدخلات الذي أنشأته SDK من تلميحات الأنواع.

الآن استدعِ أداة:

الطرفية
npx @modelcontextprotocol/inspector --cli uv run server.py \
  --method tools/call --tool-name days_between \
  --tool-args-json '{"start":"2026-11-15","end":"2027-01-01"}'

المخرجات المتوقعة:

الكود
{
  "content": [
    {
      "type": "text",
      "text": "47"
    }
  ],
  "structuredContent": {
    "result": 47
  },
  "isError": false
}

يمكن لـ SDK أيضًا تشغيل واجهة الويب الخاصة بـ Inspector:

الطرفية
uv run mcp dev server.py

يطبع عنوانًا محليًا مثل http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=... ويفتحه في متصفحك. في شاشة Servers (الخوادم)، فعّل مفتاح الاتصال بجانب خادمك، وافتح Tools، واختر count_words، واكتب نصًا ما، ثم انقر Execute Tool (تنفيذ الأداة). اضغط Ctrl+C في الطرفية عند الانتهاء.

الخطوة 5: اربطه بتطبيق ذكاء اصطناعي

ربط الخادم بمضيف يعني إخباره بالأمر الذي يشغّل خادمك. في هذا المشروع، الأمر هو:

الطرفية
uv --directory /ABSOLUTE/PATH/TO/handy-tools run server.py

شغّل pwd داخل مجلد المشروع لمعرفة المسار الحقيقي. جرّب الأمر بنفسك أولًا. لن يُطبع شيء ولن يعود الأمر، وهذا صحيح: فالخادم ينتظر مضيفًا يتحدث إليه. اضغط Ctrl+C لإيقافه.

تقبل تطبيقات كثيرة كتلة JSON نفسها لهذا الأمر:

الكود
{
  "mcpServers": {
    "handy-tools": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/handy-tools", "run", "server.py"]
    }
  }
}

أما مكان وضعها فيعتمد على التطبيق:

  • Cursor: احفظها في الملف .cursor/mcp.json داخل مشروع، أو في ~/.cursor/mcp.json لاستخدامها في كل مكان، وفق وثائق MCP في Cursor. تذكر تلك الوثائق أيضًا حقل "type": "stdio" للخوادم المحلية، رغم أن أمثلتها نفسها تُغفله.
  • VS Code: شغّل MCP: Add Server من لوحة الأوامر (Command Palette)، واختر Command (stdio) وأدخل أمر التشغيل، وفق وثائق VS Code.
  • Claude Desktop: شغّل uv run mcp install server.py، الذي يكتب الإدخال نيابةً عنك. إنه المضيف الوحيد الذي تضبطه SDK تلقائيًا.

أعد تشغيل التطبيق، ثم اسأل شيئًا مثل:

الكود
Use the days_between tool: how many days from 2026-11-15 to 2027-01-01?

يُفترض أن يكون الجواب 47. وتذكّر أن الأدوات تعمل على حاسوبك بصلاحيات حسابك، لذا لا تكشف إلا الإجراءات التي لا تمانع أن يطلقها نموذج. ولمثال على خادم جاهز أكبر، راجع دليلنا عن Chrome DevTools MCP.

مخطط تدفق لبناء خادم MCP بلغة Python واختباره وفحصه وربطه بتطبيق ذكاء اصطناعي

أخطاء شائعة وحلولها

  • ModuleNotFoundError: No module named 'mcp.server.fastmcp': كُتب هذا الكود لـ SDK 1.x. في 2.x أصبحت الفئة MCPServer، وتُستورد بالسطر from mcp.server import MCPServer. حدّث سطر الاستيراد، أو ثبّت الإصدار mcp<2 لمواصلة تشغيل الكود القديم.
  • TypeError: The @tool decorator was used incorrectly: كتبت @mcp.tool دون أقواس. استخدم @mcp.tool().
  • التطبيق لا يعرض خادمك: السبب المعتاد هو مسار نسبي. استخدم المسار المطلق للمشروع، وإذا لم يعثر التطبيق على uv، فاستبدل uv بالمسار الكامل الذي يعطيه which uv (على macOS وLinux) أو where uv (على Windows). أغلق التطبيق تمامًا وأعد فتحه بعد تعديل إعداداته.
  • ينقطع الاتصال أو تظهر قائمة الأدوات فارغة: عبر stdio، يحمل stdout البروتوكول نفسه، وقد يُفسده استدعاء print() عابر. استخدم وحدة logging في Python، التي تكتب إلى stderr.
  • npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecated، أو فشل استدعاء أداة مع Field required: إصدار Node.js لديك أقدم من أن يشغّل Inspector 2.x. في اختبار على Node 20، ثبّت npx بصمت الإصدار القديم 0.15.0، الذي يتجاهل --tool-args-json. تحقق باستخدام node --version وحدّث إلى إصدار مدعوم.
  • npx not found عند تشغيل mcp dev: إن Inspector تطبيق Node.js، لذا ثبّت Node.js أولًا.
  • Error executing tool <name> دون أي رسالة: تعطلت الأداة بسبب استثناء لم تحسب حسابه. تجد تتبع الخطأ (traceback) في سجل الخادم، لا في النتيجة.

هل تعلم؟

عبر stdio، يحمل stdout البروتوكول نفسه، لذا قد يُفسد استدعاء print() عابر في خادمك الاتصال. أما وحدة logging في Python فتكتب إلى stderr بدلًا من ذلك.

الخلاصة

خادم MCP العامل ليس سوى ملف Python فيه بضع دوال مزيّنة. اكتب الأداة، وافحصها في الذاكرة باستخدام Client(mcp)، وتأكد منها عبر stdio باستخدام Inspector، ثم أعطِ أي مضيف أمر التشغيل. من هنا يمكنك إضافة موارد ومطالبات، أو تقديم الكود نفسه عبر HTTP باستخدام mcp.run(transport="streamable-http"). وإذا كان وكيلك يحتاج إلى تعليمات مكتوبة أكثر من حاجته إلى دوال جديدة، فدليلنا عن مهارات الوكلاء في Claude Code يغطي هذا الجانب.

الأسئلة الشائعة

ما الفرق بين المضيف والعميل والخادم في MCP؟

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

لماذا تظهر لي رسالة No module named mcp.server.fastmcp؟

كُتب ذلك الكود لـ SDK 1.x. في 2.x أصبحت الفئة MCPServer، وتُستورد بالسطر from mcp.server import MCPServer. حدّث سطر الاستيراد، أو ثبّت الإصدار mcp<2 لمواصلة تشغيل الكود القديم.

هل يمكنني اختبار خادم MCP دون تطبيق ذكاء اصطناعي؟

نعم. تتصل فئة Client في SDK بكائن الخادم في الذاكرة، دون عملية فرعية أو منفذ أو ذكاء اصطناعي. ثم يشغّل وضع CLI في MCP Inspector الخادم عبر stdio كما يفعل مضيف حقيقي.

ما إصدار Node.js الذي يحتاجه MCP Inspector؟

يتطلب Inspector 2.15.0 إصدار Node ^22.23.4 أو ^24.22.1 أو >=26.12.1. وعلى إصدارات Node الأقدم، قد يثبّت npx بصمت الإصدار القديم 0.15.0، الذي يتجاهل –tool-args-json.

اختبار سريع

في SDK 2.x، ما الفئة التي تنشئ خادم MCP؟

  • FastMCP
  • ToolError
  • MCPServer

غيّرت SDK 2.x اسم فئة الخادم الرئيسية إلى MCPServer، وتُستورد من mcp.server.

ما الذي قد يفعله استدعاء print() عابر بخادم MCP يعمل عبر stdio؟

  • يُفسد تدفق البروتوكول
  • لا شيء، فالمخرجات تُتجاهل
  • يعيد تشغيل الخادم

عبر stdio، يحمل stdout البروتوكول نفسه، لذا قد تُفسده أي مخرجات إضافية.

من أين تحصل SDK على مخطط مدخلات الأداة؟

  • من ملف JSON تكتبه
  • من تلميحات الأنواع في الدالة
  • من ملف إعدادات المضيف

تقرأ SDK مخطط المدخلات من تلميحات الأنواع، لذا لن تكتب أي JSON.

المصادر

تاريخ آخر تحقق من الروابط: 15 نوفمبر 2026.

بقلم Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

عن Mindloop Experience

الردود

اكتب ردًّا

المزيد من Mindloop Experience

كل مقالات Mindloop Experience

يمكنك التصفيق حتى 50 مرة.