FastMCP - إطار عمل بايثون لإنشاء خوادم وعملاء MCP بسرعة

نظرة عامة على المشروع

FastMCP هو إطار عمل بايثون عالي المستوى لإنشاء خوادم وعملاء Model Context Protocol (MCP)، يهدف إلى تمكين المطورين من إنشاء أدوات ونشر موارد وتحديد مطالبات وربط المكونات بسرعة وسهولة. تم تطوير هذا المشروع وصيانته بواسطة مستخدم GitHub jlowin، وقد أصبح جزءًا مهمًا من نظام MCP البيئي.

لماذا تختار FastMCP؟

على الرغم من أن بروتوكول MCP قوي، إلا أن تنفيذه يتطلب الكثير من التعليمات البرمجية النمطية - إعداد الخادم ومعالجات البروتوكول وأنواع المحتوى وإدارة الأخطاء وما إلى ذلك. يتعامل FastMCP مع جميع تفاصيل البروتوكول المعقدة وإدارة الخادم، مما يتيح لك التركيز على بناء أدوات ممتازة.

أهداف تصميم FastMCP:

• 🚀 سريع: واجهات عالية المستوى تعني تعليمات برمجية أقل وتطوير أسرع
• 🍀 بسيط: قم ببناء خوادم MCP بأقل قدر من التعليمات البرمجية النمطية
• 🐍 Pythonic: يبدو طبيعيًا لمطوري بايثون
• 🔍 كامل: يوفر تطبيقًا كاملاً لمواصفات MCP الأساسية، ويدعم الخوادم والعملاء

الميزات الأساسية

الوظائف الأساسية

• إنشاء خوادم باستخدام أدوات تزيين بديهية، مع الحد الأدنى من التعليمات البرمجية النمطية
• وكيل الخوادم الحالية لتعديل التكوين أو طريقة النقل
• دمج الخوادم في تطبيقات معقدة
• إنشاء خوادم من مواصفات OpenAPI أو كائنات FastAPI
• التفاعل مع خوادم MCP برمجيًا
• الاتصال بأي خادم MCP باستخدام أي بروتوكول نقل
• اختبار الخوادم دون تدخل يدوي
• الاستفادة من وظائف MCP الأساسية، مثل أخذ عينات LLM

تطور الإصدار

جعل FastMCP 1.0 بناء خوادم MCP أمرًا بسيطًا للغاية، لدرجة أنه أصبح الآن جزءًا من Model Context Protocol Python SDK الرسمي!

يقدم FastMCP 2.0 العديد من الميزات الجديدة:

• وظائف متقدمة مثل وكالة ودمج خوادم MCP
• إنشاء خوادم تلقائيًا من مواصفات OpenAPI أو كائنات FastAPI
• تقديم وظائف العميل، مثل أخذ عينات LLM

طريقة التثبيت

يوصى باستخدام uv لتثبيت FastMCP:

uv pip install fastmcp

تثبيت التطوير:

git clone https://github.com/jlowin/fastmcp.git
cd fastmcp

uv sync

مثال البدء السريع

مثال الخادم الأساسي

# server.py
from fastmcp import FastMCP


mcp = FastMCP("Demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

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

التثبيت على Claude Desktop:

fastmcp install server.py

شرح المفاهيم الأساسية

1. مثيل FastMCP

يمثل الكائن المركزي لتطبيق MCP، ويتعامل مع الاتصال وتفاصيل البروتوكول والتوجيه:

from fastmcp import FastMCP


mcp = FastMCP("My App")


mcp = FastMCP("My App", dependencies=["pandas", "numpy"])

2. الأدوات (Tools)

تسمح لـ LLM بتنفيذ العمليات عن طريق تنفيذ وظائف بايثون، وهي مناسبة للحسابات أو استدعاءات API الخارجية أو الآثار الجانبية:

import httpx
from pydantic import BaseModel

class UserInfo(BaseModel):
    user_id: int
    notify: bool = False

@mcp.tool()
async def send_notification(user: UserInfo, message: str) -> dict:
    """Sends a notification to a user if requested."""
    if user.notify:

        print(f"Notifying user {user.user_id}: {message}")
        return {"status": "sent", "user_id": user.user_id}
    return {"status": "skipped", "user_id": user.user_id}

@mcp.tool()
def get_stock_price(ticker: str) -> float:
    """Gets the current price for a stock ticker."""

    prices = {"AAPL": 180.50, "GOOG": 140.20}
    return prices.get(ticker.upper(), 0.0)

3. الموارد (Resources)

تعرض البيانات لـ LLM، وتوفر بشكل أساسي معلومات دون إجراء حسابات كبيرة أو آثار جانبية:

@mcp.resource("config://app-version")
def get_app_version() -> str:
    """Returns the application version."""
    return "v2.1.0"


@mcp.resource("db://users/{user_id}/email")
async def get_user_email(user_id: str) -> str:
    """Retrieves the email address for a given user ID."""

    emails = {"123": "alice@example.com", "456": "bob@example.com"}
    return emails.get(user_id, "not_found@example.com")

4. المطالبات (Prompts)

تحديد قوالب أو أنماط تفاعل قابلة لإعادة الاستخدام:

from fastmcp.prompts.base import UserMessage, AssistantMessage

@mcp.prompt()
def ask_review(code_snippet: str) -> str:
    """Generates a standard code review request."""
    return f"Please review the following code snippet for potential bugs and style issues:\n```python\n{code_snippet}\n```"

@mcp.prompt()
def debug_session_start(error_message: str) -> list[Message]:
    """Initiates a debugging help session."""
    return [
        UserMessage(f"I encountered an error:\n{error_message}"),
        AssistantMessage("Okay, I can help with that. Can you provide the full traceback and tell me what you were trying to do?")
    ]

وظائف متقدمة

1. خادم الوكيل

إنشاء خادم FastMCP يعمل كوسيط، ويوجه الطلبات إلى نقطة نهاية MCP أخرى:

import asyncio
from fastmcp import FastMCP, Client
from fastmcp.client.transports import PythonStdioTransport


proxy_client = Client(
    transport=PythonStdioTransport('path/to/original_stdio_server.py'),
)


proxy = FastMCP.from_client(proxy_client, name="Stdio-to-SSE Proxy")

if __name__ == "__main__":
    proxy.run(transport='sse')

2. دمج الخادم

بناء تطبيقات MCP كبيرة عن طريق إنشاء خوادم FastMCP معيارية و "تركيبها" على خادم رئيسي:

from fastmcp import FastMCP


weather_mcp = FastMCP("Weather Service")

@weather_mcp.tool()
def get_forecast(city: str):
    return f"Sunny in {city}"


news_mcp = FastMCP("News Service")

@news_mcp.tool()
def fetch_headlines():
    return ["Big news!", "Other news"]


mcp = FastMCP("Composite")
mcp.mount("weather", weather_mcp) 
mcp.mount("news", news_mcp)        

3. إنشاء خادم من API

إنشاء خوادم FastMCP تلقائيًا من واجهات برمجة تطبيقات الويب الحالية:

from fastapi import FastAPI
from fastmcp import FastMCP


fastapi_app = FastAPI(title="My Existing API")

@fastapi_app.get("/status")
def get_status():
    return {"status": "running"}


mcp_server = FastMCP.from_fastapi(fastapi_app)

4. وظائف العميل

التفاعل مع أي خادم MCP:

from fastmcp import Client

async with Client("path/to/server") as client:

    result = await client.call_tool("weather", {"location": "San Francisco"})
    print(result)
    

    res = await client.read_resource("db://users/123/profile")
    print(res)

تشغيل الخادم

وضع التطوير

fastmcp dev your_server_file.py

تثبيت الإنتاج

fastmcp install your_server_file.py

التشغيل المباشر

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

مشاريع مثال

يحتوي المشروع على العديد من ملفات الأمثلة:

• simple_echo.py: أدوات وموارد ومطالبات أساسية
• complex_inputs.py: استخدام نماذج Pydantic كمدخلات للأدوات
• mount_example.py: تركيب العديد من خوادم FastMCP
• sampling.py: استخدام إكمال LLM في خادم MCP
• screenshot.py: أداة ترجع كائن صورة
• text_me.py: أداة تتفاعل مع واجهة برمجة تطبيقات خارجية
• memory.py: مثال معقد مع تفاعلات قاعدة البيانات

دليل المساهمة

يرحب FastMCP بمساهمات المجتمع:

المتطلبات البيئية

• بايثون 3.10+
• مدير حزم uv

إعداد التطوير

git clone https://github.com/jlowin/fastmcp.git && cd fastmcp
uv venv && uv sync

الاختبار

uv run pytest -vv

جودة الكود

استخدم ruff و pre-commit:

pre-commit install
pre-commit run --all-files

أهمية المشروع

يسد FastMCP الفجوة بين تنفيذ بروتوكول MCP وتطوير التطبيقات العملية، مما يتيح للمطورين:

1. إنشاء نماذج أولية ونشر خوادم MCP بسرعة
2. دمج واجهات برمجة التطبيقات ومصادر البيانات الحالية بسهولة
3. بناء بنية تطبيقات الذكاء الاصطناعي معيارية وقابلة للتطوير
4. التركيز على منطق الأعمال بدلاً من تفاصيل تنفيذ البروتوكول