بناء خادم MCP ببايثون

طريقان إلى نفس الفكرة

قبل أن تبدأ

الفكرة الجوهرية

1الرسائل تحت الغطاء

قبل المكتبة، انظر للبروتوكول نفسه. هذا خادم مصغّر يعالج ثلاث رسائل JSON-RPC كما يرسلها العميل:

import json

MENU = {"latte": 14, "mocha": 16}
TOOLS = [{
    "name": "get_price",
    "description": "Price in riyals of one café menu item.",
    "inputSchema": {"type": "object", "properties": {"item": {"type": "string"}},
                    "required": ["item"]},
}]

def handle(request):
    method, rid = request["method"], request["id"]
    if method == "initialize":
        result = {"protocolVersion": "2025-06-18", "capabilities": {"tools": {}},
                  "serverInfo": {"name": "cafe", "version": "1.0"}}
    elif method == "tools/list":
        result = {"tools": TOOLS}
    elif method == "tools/call":
        item = request["params"]["arguments"]["item"]
        text = f"{item}: {MENU[item]} SAR" if item in MENU else f"no item {item}"
        result = {"content": [{"type": "text", "text": text}], "isError": item not in MENU}
    else:
        return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32601, "message": "unknown method"}}
    return {"jsonrpc": "2.0", "id": rid, "result": result}

for req in [{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}},
            {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
            {"jsonrpc": "2.0", "id": 3, "method": "tools/call",
             "params": {"name": "get_price", "arguments": {"item": "mocha"}}}]:
    print(json.dumps(handle(req))[:110])

2MCPServer: الخادم الحقيقي

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

from mcp.server import MCPServer

mcp = MCPServer("cafe")
MENU = {"latte": 14, "mocha": 16, "tea": 6}

@mcp.tool()
def get_price(item: str) -> str:
    """Price in riyals of one café menu item, e.g. 'latte'."""
    if item not in MENU:
        return f"No item called {item}. Available: {', '.join(MENU)}"
    return f"{item}: {MENU[item]} SAR"

@mcp.resource("menu://today")
def today_menu() -> str:
    """Today's full menu as plain text."""
    return "\n".join(f"{k}: {v} SAR" for k, v in MENU.items())

# run it under the inspector:  uv run mcp dev server.py
# or over HTTP:                uv run mcp run server.py --transport streamable-http

3الاختبار والربط

شغّل uv run mcp dev server.py لترى الأدوات وتجربها بلا نموذج. ثم أضف الخادم لإعدادات العميل (مثلًا ملف إعداد Claude Desktop) بأمر التشغيل نفسه.

مثال محلول

المسألة: النموذج لا يستخدم أداتك أبدًا. التحليل: الوصف «gets data» غامض، واسمها tool1. الحل: اسم search_orders ووصف «Search the café's orders by customer phone or date. Returns up to 20 orders, newest first.». بعد التعديل يختارها النموذج في الأسئلة الصحيحة.

خرافة مقابل حقيقة

أين تقابله في العمل

اختبر فهمك

بطاقات مراجعة سريعة

تحقق من فهمك