a2a mcpa2a mcp
Back to Blog
BlogApril 6, 20262

كيفية بناء أول خادم MCP الخاص بك: برنامج تعليمي خطوة بخطوة

كيفية بناء أول خادم MCP الخاص بك: برنامج تعليمي خطوة بخطوة

المتطلبات

قبل البدء، تأكد من توفر ما يلي:

  • تثبيت Python 3.10 أو أحدث.
  • معرفة أساسية بتركيبات Python والبرمجة غير المتزامنة (async code).
  • uv (مدير حزم Python السريع) - قم بتثبيته باستخدام curl -LsSf https://astral.sh/uv/install.sh | sh.
  • عميل MCP مثل Claude Desktop (قم بالتنزيل من claude.ai/download وحافظ على تحديثه).
  • محرر نصوص أو بيئة تطوير متكاملة (IDE).

لا توجد حاجة إلى خبرة مسبقة في MCP. سنقوم ببناء خادم MCP للطقس عمليًا يسمح للذكاء الاصطناعي بالاستعلام عن تنبيهات الطقس الفورية وتوقعاته عبر واجهة برمجة تطبيقات (API) الخدمة الوطنية للطقس.

الخطوة 1: إعداد البيئة

قم بإنشاء دليل مشروع نظيف وقم بتهيئته باستخدام uv:

mkdir weather-mcp-server
cd weather-mcp-server
uv init
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv add "mcp[cli]" httpx

هذا يقوم بتثبيت SDK Python الرسمي لـ MCP (FastMCP) و httpx لمكالمات API. أصبح لدى مشروعك الآن ملف pyproject.toml وبيئة افتراضية.

المخرجات المتوقعة: مجلد .venv جديد وتبعيات مدرجة في uv.lock.

الخطوة 2: إنشاء كود خادم MCP

قم بإنشاء الملف الرئيسي:

touch weather.py

الصق هذا الكود الكامل الجاهز للتشغيل في weather.py:

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# تهيئة خادم MCP
mcp = FastMCP("weather")

NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

# دالة مساعدة لاستدعاء واجهة برمجة تطبيقات NWS بأمان
async def make_nws_request(url: str) -> dict[str, Any] | None:
    headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

# تنسيق تنبيهات الطقس بشكل مناسب للذكاء الاصطناعي
def format_alert(feature: dict) -> str:
    props = feature["properties"]
    return f"""
Event: {props.get("event", "Unknown")}
Area: {props.get("areaDesc", "Unknown")}
Severity: {props.get("severity", "Unknown")}
Description: {props.get("description", "No description available")}
Instructions: {props.get("instruction", "No specific instructions provided")}
"""

# الأداة 1: الحصول على تنبيهات الطقس النشطة لولاية أمريكية
@mcp.tool()
async def get_alerts(state: str) -> str:
    """الحصول على تنبيهات الطقس الحالية لولاية أمريكية (مثل "CA" أو "TX")."""
    url = f"{NWS_API_BASE}/alerts/active/area/{state.upper()}"
    data = await make_nws_request(url)
    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."
    if not data["features"]:
        return f"No active alerts for {state.upper()}."
    alerts = [format_alert(f) for f in data["features"]]
    return "\n---\n".join(alerts)

الأداة 2: الحصول على توقعات الطقس لـ5 أيام لأي إحداثيات خط عرض/طول

@mcp.tool() async def get_forecast(latitude: float, longitude: float) -> str: """الحصول على توقعات الطلق لخط عرض وخط طول محددين.""" points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}" points_data = await make_nws_request(points_url) if not points_data: return "تعذر جلب بيانات التوقعات لهذا الموقع." forecast_url = points_data["properties"]["forecast"] forecast_data = await make_nws_request(forecast_url) if not forecast_data: return "تعذر جلب التوقعات التفصيلية." periods = forecast_data["properties"]["periods"][:5] forecasts = [] for period in periods: forecast = f""" {period["name"]}: درجة الحرارة: {period["temperature"]}°{period["temperatureUnit"]} الرياح: {period["windSpeed"]} {period["windDirection"]} التوقعات: {period["detailedForecast"]} """ forecasts.append(forecast) return "\n---\n".join(forecasts)

def main(): mcp.run(transport="stdio")

if name == "main": main()


**المفاهيم الأساسية الموضحة:**
- محددات `@mcp.tool()` تحول الدوال العادية غير المتزامنة إلى أدوات MCP يمكن للذكاء الاصطناعي اكتشافها واستدعائها.
- يعمل الخادم عبر **stdio** (الإدخال/الإخراج القياسي) – الافتراضي لخوادم MCP المحلية.
- يجب أن يذهب كل التسجيل إلى stderr (يتعامل FastMCP مع هذا تلقائياً).

## الخطوة 3: اختبار الخادم محلياً

شغّل الخادم:

```bash
uv run weather.py

المخرجات المتوقعة: يبقى الطرفية مفتوحة وصامتة (هذا طبيعي لخوادم stdio). سترى رسائل JSON-RPC فقط عندما يتصل عميل MCP.

اترك هذه الطرفية قيد التشغيل للخطوة التالية.

الخطوة 4: توصيل خادم MCP بـ Claude Desktop

  1. افتح Claude Desktop.
  2. أنشئ أو حرر ملف التكوين في:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

أضف هذا الإدخال بالضبط (استبدل /ABSOLUTE/PATH/TO/weather-mcp-server بمسار مجلدك الفعلي):

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/weather-mcp-server",
        "run",
        "weather.py"
      ]
    }
  }
}
  1. أغلق Claude Desktop تماماً (Cmd+Q على macOS أو الإغلاق من صينية النظام على Windows) وأعِد تشغيله.
  2. في Claude، انقر على "إضافة ملفات، موصلات، والمزيد" → مرر فوق الموصلات → يجب أن ترى "weather" مدرجاً.

الخطوة 5: استخدام خادم MCP الخاص بك مع الذكاء الاصطناعي

جرب هذه الأوامر في Claude Desktop:

  • "ما هي تنبيهات الطقس النشطة في تكساس؟"
  • "أعطني توقعات الطقس لسان فرانسيسكو (استخدم خط عرض 37.77، خط طول -122.41)."
  • "تحقق من التنبيهات في كاليفورنيا وأخبرني إذا كنت بحاجة للتحضير لأي شيء."

سيقوم Claude تلقائياً باكتشاف الأدوات، وطلب موافقتك للمرة الأولى، وإرجاع النتائج المنسقة.

السلوك المتوقع: سيقوم الذكاء الاصطناعي باستدعاء أدواتك في الخلفية وعرض إجابات بلغة طبيعية.

المشاكل الشائعة وحلولها

  • الخادم لا يظهر في Claude:

    • تأكد من صحة JSON (بدون فواصل زائدة في النهاية).
    • استخدم مساراً مطلقاً في التكوين.
    • أعد تشغيل Claude تماماً.
    • تحقق من سجلات النظام: ~/Library/Logs/Claude/mcp*.log (macOS) أو ما يعادلها على Windows.

  • أخطاء API أو عدم وجود بيانات:

    • NWS API يعمل فقط للمواقع في الولايات المتحدة.
    • استخدم رموز الولايات المكونة من حرفين (CA، TX، إلخ.).
    • يجب أن تكون الإحداثيات خطوط عرض/طول صالحة.

  • "أمر غير موجود":

    • تأكد من وجود uv في المسار PATH الخاص بك وأن البيئة الافتراضية مفعلة.
    • نفّذ uv --version للتحقق من التثبيت.

  • مهلة أو استجابة بطيئة:

    • زد المهلة في make_nws_request إذا لزم الأمر.
    • لدى NWS حدود معدل – تجنب الإرسال المتكرر في الإنتاج.

  • مشاكل الصلاحيات:

    • على macOS، منح Claude Desktop صلاحية الوصول الكامل للقرص في إعدادات النظام → الخصوصية والأمان.

الخطوات التالية

  • إضافة أدوات أكثر: أنشئ أدوات لقواعد البيانات، GitHub، Slack، أو واجهات برمجة التطبيقات الخاصة بك باستخدام نفس النمط @mcp.tool().
  • إضافة موارد وتوجيهات: استخدم mcp.resource() و mcp.prompt() للبيانات الشبيهة بالملفات والتوجيهات القابلة لإعادة الاستخدام.
  • نشر عن بعد: انتقل إلى نقل HTTP/SSE واستضف على AWS Lambda، Vercel، أو أي خادم (FastMCP يدعم stateless_http=True).
  • دعم لغات متعددة: جرب التطوير الرسمي TypeScript، Go، أو Rust SDKs لنفس الوظائف.
    • شارك خادمك: انشر المستودع حتى يتمكن الآخرون من إضافته عبر npx أو Docker.

الآن لديك خادم MCP وظيفي بالكامل يمكن لأي عميل ذكاء اصطناعي متوافق استخدامه. جرب، وسّع الأدوات، وابدأ في بناء تكاملات الذكاء الاصطناعي القوية اليوم!

Share this article
XFacebookLinkedInRedditHacker News