در این آموزش آماده Colab، ما نحوه ادغام هوش مصنوعی مولد Google Gemini 2.0 با یک سرور پروتکل زمینه مدل (MCP) درونپردازشی، با استفاده از FastMCP را نشان میدهیم. با شروع با یک اعلان getpass تعاملی برای گرفتن ایمن GEMINI_API_KEY شما، ما تمام وابستگیهای لازم را نصب و پیکربندی میکنیم: کلاینت پایتون google-genai برای فراخوانی API Gemini، fastmcp برای تعریف و میزبانی ابزارهای MCP ما در داخل پردازش، httpx برای ایجاد درخواستهای HTTP به API آب و هوای Open-Meteo و nest_asyncio برای وصله حلقه رویداد asyncio که از قبل در حال اجرا است. گردش کار با چرخش یک سرور "آب و هوا" FastMCP حداقل با دو ابزار، get_weather(latitude, longitude) برای پیشبینی سه روزه و get_alerts(state) برای هشدارهای آب و هوایی در سطح ایالت، شروع میشود، سپس یک FastMCPTransport ایجاد میکند تا یک کلاینت MCP را به آن سرور متصل کند. در نهایت، با استفاده از ویژگی فراخوانی تابع Gemini، یک اعلان زبان طبیعی را به Gemini ارسال میکنیم، از آن میخواهیم یک فراخوانی تابع را بر اساس طرحوارههای JSON صریح ما منتشر کند، و سپس آن فراخوانی را از طریق کلاینت MCP اجرا میکنیم، و دادههای آب و هوایی ساختاریافته را به دفترچه خود بازمیگردانیم.
from getpass import getpass
import os
api_key = getpass("Enter your GEMINI_API_KEY: ")
os.environ["GEMINI_API_KEY"] = api_key
ما به طور ایمن از شما میخواهیم کلید API Gemini خود را وارد کنید (بدون نمایش آن روی صفحه) و سپس آن را در متغیر محیطی GEMINI_API_KEY ذخیره میکنیم و به بقیه دفترچه شما اجازه میدهیم با API Google احراز هویت شود.
!pip install -q google-genai mcp fastmcp httpx nest_asyncio
ما تمام وابستگیهای اصلی مورد نیاز برای دفترچه Colab خود را در یک مرحله نصب میکنیم - google-genai برای تعامل با API Gemini، mcp و fastmcp برای ساخت و میزبانی سرور و کلاینت پروتکل زمینه مدل ما، httpx برای ایجاد درخواستهای HTTP به APIهای خارجی و nest_asyncio برای وصله حلقه رویداد، بنابراین کد ناهمزمان ما به آرامی اجرا میشود.
ما وصله nest_asyncio را روی حلقه رویداد موجود دفترچه اعمال میکنیم و به ما امکان میدهیم روالهای ناهمزمان asyncio (مانند تعاملات کلاینت MCP ما) را بدون مواجهه با خطاهای "حلقه رویداد از قبل در حال اجرا است" اجرا کنیم.
from fastmcp import FastMCP
import httpx
mcp_server = FastMCP("weather")
@mcp_server.tool()
def get_weather(latitude: float, longitude: float) -> str:
"""3-day min/max temperature forecast via Open-Meteo."""
url = (
f"https://api.open-meteo.com/v1/forecast"
f"?latitude={latitude}&longitude={longitude}"
"&daily=temperature_2m_min,temperature_2m_max&timezone=UTC"
)
resp = httpx.get(url, timeout=10)
daily = resp.json()["daily"]
return "\n".join(
f"{date}: low {mn}°C, high {mx}°C"
for date, mn, mx in zip(
daily["time"],
daily["temperature_2m_min"],
daily["temperature_2m_max"],
)
)
@mcp_server.tool()
def get_alerts(state: str) -> str:
"""Dummy US-state alerts."""
return f"No active weather alerts for {state.upper()}.
ما یک سرور FastMCP درونپردازشی به نام "weather" ایجاد میکنیم و دو ابزار را ثبت میکنیم: get_weather(latitude, longitude) که یک پیشبینی دمای 3 روزه را از API Open-Meteo با استفاده از httpx واکشی و قالببندی میکند و get_alerts(state) که یک پیام جایگزین را برای هشدارهای آب و هوایی ایالت ایالات متحده برمیگرداند.
import asyncio
from google import genai
from google.genai import types
from fastmcp import Client as MCPClient
from fastmcp.client.transports import FastMCPTransport
ما کتابخانههای اصلی برای ادغام MCP-Gemini خود را وارد میکنیم: asyncio برای اجرای کد ناهمزمان، google-genai و ماژول انواع آن برای فراخوانی Gemini و تعریف طرحوارههای فراخوانی تابع و Client FastMCP (با نام مستعار MCPClient) با FastMCPTransport آن برای اتصال سرور آب و هوای درونپردازشی ما به کلاینت MCP.
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
MODEL = "gemini-2.0-flash"
transport = FastMCPTransport(mcp_server)
ما کلاینت Google Gemini را با استفاده از GEMINI_API_KEY از محیط شما مقداردهی اولیه میکنیم، مدل gemini-2.0-flash را برای فراخوانی تابع مشخص میکنیم و یک FastMCPTransport را تنظیم میکنیم که mcp_server درونپردازشی را به کلاینت MCP متصل میکند.
function_declarations = [
{
"name": "get_weather",
"description": "Return a 3-day min/max temperature forecast for given coordinates.",
"parameters": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"description": "Latitude of target location."
},
"longitude": {
"type": "number",
"description": "Longitude of target location."
}
},
"required": ["latitude", "longitude"]
}
},
{
"name": "get_alerts",
"description": "Return any active weather alerts for a given U.S. state.",
"parameters": {
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "Two-letter U.S. state code, e.g. 'CA'."
}
},
"required": ["state"]
}
}
]
tool_defs = types.Tool(function_declarations=function_declarations)
ما به صورت دستی مشخصات طرحواره JSON را برای دو ابزار MCP خود تعریف میکنیم، get_weather (که عرض و طول جغرافیایی را به عنوان ورودیهای عددی میپذیرد) و get_alerts (که کد ایالت ایالات متحده را به عنوان یک رشته میپذیرد)، از جمله نامها، توضیحات، ویژگیهای مورد نیاز و انواع داده. سپس این اعلانات را در یک شی types.Tool (tool_defs) میپیچد، که به Gemini اطلاع میدهد چگونه فراخوانیهای تابع مربوطه را ایجاد و اعتبارسنجی کند.
async def run_gemini(lat: float, lon: float):
async with MCPClient(transport) as mcp_client:
prompt = f"Give me a 3-day weather forecast for latitude={lat}, longitude={lon}.".
response = client.models.generate_content(
model=MODEL,
contents=[prompt],
config=types.GenerateContentConfig(
temperature=0,
tools=[tool_defs]
)
)
call = response.candidates[0].content.parts[0].function_call
if not call:
print("No function call; GPT said:", response.text)
return
print(" Gemini wants:", call.name, call.args)
result = await mcp_client.call_tool(call.name, call.args)
print("\n Tool result:\n", result)
asyncio.get_event_loop().run_until_complete(run_gemini(37.7749, -122.4194))
در نهایت، این تابع ناهمزمان run_gemini یک جلسه کلاینت MCP را روی انتقال درونپردازشی ما باز میکند، یک اعلان زبان طبیعی را به Gemini ارسال میکند و درخواست یک پیشبینی 3 روزه را در مختصات داده شده دارد، فراخوانی تابع حاصل را (در صورت وجود) ضبط میکند، ابزار MCP مربوطه را فراخوانی میکند و دادههای آب و هوایی ساختاریافته را چاپ میکند، که همه اینها با اجرای آن در حلقه رویداد دفترچه با run_until_complete آغاز میشود.
در نتیجه، ما یک خط لوله کاملاً محصور داریم که نشان میدهد چگونه ابزارهای MCP سفارشی را در پایتون تعریف کنیم، آنها را از طریق FastMCP در معرض نمایش قرار دهیم و آنها را به طور یکپارچه با مدل Google Gemini 2.0 با استفاده از کلاینت google-genai ادغام کنیم. چارچوبهای کلیدی، FastMCP برای میزبانی MCP، FastMCPTransport و MCPClient برای انتقال و فراخوانی، httpx برای دسترسی به API خارجی و nest_asyncio برای سازگاری Colab، با هم کار میکنند تا فراخوانی تابع در زمان واقعی را بدون فرآیندهای خارجی یا لولههای stdio فعال کنند. این الگو توسعه و آزمایش محلی ادغامهای MCP را در Colab ساده میکند و یک الگو برای ساخت برنامههای کاربردی عامل پیشرفتهتر ارائه میدهد که استدلال LLM را با ابزارهای دامنه تخصصی ترکیب میکنند.