تشرح معظم أدلة 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 (قوالب يختارها المستخدم).
يركّز هذا الدليل على الأدوات فقط. الأداتان اللتان ستكتبهما، عدّاد كلمات وحاسبة تواريخ، تؤديان عملًا دقيقًا يتقنه الكود أكثر من تقديرات النموذج.
ما الذي تحتاجه
- 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.

الخطوة 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.

أخطاء شائعة وحلولها
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.
- Build an MCP server (official tutorial)
- What is the Model Context Protocol?
- MCP Python SDK README, v2.3.0
- Python SDK: First steps
- Python SDK: Connect to a real host
- Python SDK: Testing
- Python SDK: Running your server
- Python SDK: Handling errors
- Python SDK: Troubleshooting
- mcp on PyPI
- MCP Inspector README, 2.15.0
- Inspector: smoke-testing an MCP server from the shell
- Installing uv
- uv: creating projects
- Cursor: Model Context Protocol
- VS Code: add and manage MCP servers





اكتب ردًّا