پیاده‌سازی کد برای ساخت سرور پروتکل متن مدل (MCP) و اتصال آن به Claude Desktop

در این آموزش عملی، ما یک سرور MCP (پروتکل متن مدل) می‌سازیم که به Claude Desktop اجازه می‌دهد تا از طریق API AlphaVantage، احساسات اخبار سهام و برترین برندگان و بازندگان روزانه را دریافت کند. از آنجا که اکثر مدل‌های زبان بزرگ (LLM) نمی‌توانند به طور مستقیم به داده‌های مالی بی‌درنگ دسترسی داشته باشند، این راه حل از MCP برای ارائه بینش‌های بی‌درنگ استفاده می‌کند.

ما دو ابزار را از سرور خود در معرض دید قرار می‌دهیم:

• get_news_sentiment
• get_top_movers

بیایید هر مرحله را بررسی کنیم.

ما ابتدا محیط خود را تنظیم می‌کنیم و با نصب مدیر بسته uv شروع می‌کنیم. برای مک یا لینوکس:

curl -LsSf https://astral.sh/uv/install.sh | sh

برای ویندوز (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

سپس یک دایرکتوری پروژه جدید ایجاد می‌کنیم و آن را با uv مقداردهی اولیه می‌کنیم.

uv init stockNews
cd stockNews

اکنون می‌توانیم یک محیط مجازی ایجاد و فعال کنیم. برای مک یا لینوکس:

uv venv
source .venv/bin/activate

برای ویندوز:

uv venv
.venv\Scripts\activate

اکنون وابستگی‌های مورد نیاز را نصب می‌کنیم.

uv add mcp httpx python-dotenv

اکنون یک فایل env. ایجاد می‌کنیم که شامل کلید API برای AlphaVantage است. برای تولید یک کلید API رایگان:

• به https://www.alphavantage.co/ بروید.
• روی دکمه Get free API key کلیک کنید یا از URL زیر استفاده کنید: https://www.alphavantage.co/support/#api-key
• ایمیل و سایر جزئیات مورد نیاز خود را وارد کنید. یک کلید API دریافت خواهید کرد — آن را کپی کرده و در جای امن نگهداری کنید، زیرا از این کلید برای احراز هویت درخواست‌های شما استفاده می‌شود.

اکنون یک فایل env. ایجاد کنید و خط زیر را اضافه کنید:

ALPHA_VANTAGE_API_KEY = your_api_key

ابتدا یک فایل stockNews.py در دایرکتوری که ایجاد کرده‌ایم ایجاد کنید و قطعه کدهای زیر را اضافه کنید:

وارد کردن بسته‌ها و تنظیم نمونه:

ابتدا بسته‌های لازم را وارد می‌کنیم و نمونه را برای استفاده از API تنظیم می‌کنیم.

from typing import Any
import os
import httpx
from mcp.server.fastmcp import FastMCP
from dotenv import load_dotenv

# Load .env variables
load_dotenv()
API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY")

# Initialize FastMCP server
mcp = FastMCP("alpha-finance")

# Constants
BASE_URL = "https://www.alphavantage.co/query"

بعد، توابع کمکی خود را برای پرس و جو از داده‌ها از AlphaVantage اضافه می‌کنیم.

async def call_alpha_vantage(endpoint: str, params: dict[str, Any]) -> dict[str, Any] | None:
    """Generic async caller to Alpha Vantage."""
    params["apikey"] = API_KEY
    params["function"] = endpoint
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(BASE_URL, params=params, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

دستگیره اجرای ابزار مسئول اجرای منطق هر ابزار است.

@mcp.tool()
async def get_news_sentiment(ticker: str) -> str:
    """Get news sentiment data for a stock ticker.

    Args:
        ticker: Stock ticker symbol (e.g., MSFT, AAPL)
    """
    data = await call_alpha_vantage("NEWS_SENTIMENT", {"tickers": ticker.upper()})
    if not data or "feed" not in data:
        return "Couldn't retrieve news sentiment."

    articles = data["feed"][:3]
    result = []
    for item in articles:
        result.append(f"""
📰 {item['title']}
Summary: {item['summary']}
Source: {item['source']} | Published: {item['time_published']}
""")
    return "\n---\n".join(result)

@mcp.tool()
async def get_top_movers() -> str:
    """Get top gainers and losers from the stock market.

    No arguments required.
    """
    data = await call_alpha_vantage("TOP_GAINERS_LOSERS", {})
    if not data:
        return "Couldn't retrieve top movers."

    gainers = data.get("top_gainers", [])[:3]
    losers = data.get("top_losers", [])[:3]

    result = "**Top Gainers**\n"
    result += "\n".join([
        f"{g['ticker']} ({g.get('change_percentage', 'N/A')})"
        for g in gainers
    ])

    result += "\n\n**Top Losers**\n"
    result += "\n".join([
        f"{l['ticker']} ({l.get('change_percentage', 'N/A')})"
        for l in losers
    ])

    return result

در نهایت، سرور را مقداردهی اولیه و اجرا می‌کنیم:

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

اکنون سرور خود را از یک هاست MCP موجود، Claude for Desktop، آزمایش خواهیم کرد.

ابتدا مطمئن شوید که Claude for Desktop را نصب کرده‌اید. اگر نه، آخرین نسخه را از منبع رسمی دانلود و نصب کنید. اگر از قبل آن را دارید، مطمئن شوید که به روز است.

بعد، باید Claude را برای اتصال به سرور MCP خود پیکربندی کنید. برای انجام این کار، فایل claude_desktop_config.json را که در دایرکتوری Claude قرار دارد، با استفاده از هر ویرایشگر متن باز کنید. اگر فایل وجود ندارد، آن را به صورت دستی ایجاد کنید.

برای MacOS/Linux:

{
    "mcpServers": {
        "stockNews": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/stockNews",
                "run",
                "stockNews.py"
            ]
        }
    }
}

برای ویندوز:

{
    "mcpServers": {
        "stockNews": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\stockNews",
                "run",
                "stockNews.py"
            ]
        }
    }
}

این پیکربندی به Claude for Desktop اطلاع می‌دهد که:

• یک سرور MCP به نام “stockNews” وجود دارد.
• باید با استفاده از دستور زیر اجرا شود:
  uv –directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/stockNews run stockNews.py

پس از اضافه کردن این به فایل پیکربندی خود، فایل را ذخیره کرده و Claude for Desktop را مجدداً راه اندازی کنید تا تغییرات اعمال شود.

آزمایش با دستورات

برای تأیید اینکه Claude for Desktop دو ابزار را از سرور stockNews شما شناسایی کرده است، به دنبال نماد چکش در رابط Claude باشید — این نماد نشان دهنده دسترسی به ابزار است.

پس از کلیک بر روی نماد چکش، باید دو ابزار لیست شده را ببینید:

می‌توانیم سرور را با اجرای دستورات زیر آزمایش کنیم:

• احساسات اخبار برای Apple چیست؟
• برترین برندگان و بازندگان بازار سهام چه کسانی هستند؟

وقتی از Claude سوال می‌پرسید:

1. مشتری پرس و جوی شما را به Claude ارسال می‌کند.
2. Claude ابزارهای موجود (مانند get_news_sentiment یا get_top_movers) را بررسی می‌کند و تعیین می‌کند که کدام یک را بر اساس سوال شما استفاده کند.
3. ابزار انتخاب شده از طریق سرور MCP که قبلاً پیکربندی کرده‌اید اجرا می‌شود.
4. ابزار نتایج را به Claude باز می‌گرداند.
5. Claude از این نتایج برای ایجاد یک پاسخ زبان طبیعی استفاده می‌کند.
6. پاسخ نهایی در رابط چت به شما نشان داده می‌شود.
   

این جریان یکپارچه همان چیزی است که به Claude اجازه می‌دهد تا به روشی ساختاریافته و کنترل شده با داده‌های بی‌درنگ تعامل داشته باشد.

سرور بینش سهام مبتنی بر MCP ما، قابلیت‌های Claude Desktop را با فعال کردن بازیابی داده‌های مالی بی‌درنگ گسترش می‌دهد. با ادغام API AlphaVantage با یک سرور MCP سفارشی، کاربران می‌توانند احساسات اخبار زنده را دریافت کرده و برترین حرکت‌کنندگان بازار را مستقیماً از طریق Claude پیگیری کنند. این تنظیمات کاربران را قادر می‌سازد تا با بینش‌های سهام به موقع و قابل اقدام — همه در یک رابط مکالمه — تجزیه و تحلیل مالی را کارآمدتر، زمینه‌ای و تعاملی‌تر کنند.