نصب و راه‌اندازی اولین MCP Server

خلاصه قسمت قبل

در قسمت اول فهمیدیم MCP چیه، چرا مهمه و چطور مشکل M×N رو حل می‌کنه. با معماری Client-Server آشنا شدیم و فهمیدیم هر MCP Server سه قابلیت داره: Tools، Resources و Prompts. حالا وقتشه دست به کار بشیم و اولین MCP Server خودمون رو راه بندازیم.

چرا این قسمت مهمه؟

خوندن درباره MCP خوبه، ولی تا وقتی خودت یه سرور ران نکنی و نبینی Claude داره ازش استفاده می‌کنه، واقعاً نمی‌فهمی چقدر قدرتمنده. این قسمت قراره تو رو از تئوری به عمل ببره. یه MCP Server ساده نصب می‌کنیم، وصلش می‌کنیم به Claude Desktop و می‌بینیم که واقعاً کار می‌کنه.

چی لازم داری؟

قبل از شروع، بذار مطمئن بشیم همه ابزارها آماده‌ست. لیست چیزهایی که لازم داری:

Node.js و npm: MCP SDK رسمی با TypeScript/JavaScript نوشته شده. Node.js موتوری هست که کد جاوااسکریپت رو خارج از مرورگر اجرا می‌کنه و npm مدیر بسته‌هاشه. وقتی Node.js رو نصب کنی، npm خودکار همراهش میاد.

برای چک کردن نسخه‌ها:

node --version   # باید v18+ باشه
npm --version    # باید v8+ باشه

Claude Desktop: اپلیکیشن دسکتاپ Claude که قابلیت MCP داره. می‌تونی از سایت Anthropic دانلودش کنی. این اپ به‌عنوان MCP Host عمل می‌کنه — یعنی همونجایی که تو باهاش حرف می‌زنی و Claude از طریقش به MCP Serverها وصل می‌شه.

یه Code Editor: هر ادیتوری که باهاش راحتی. VS Code پیشنهاد می‌شه چون خودش هم قابلیت MCP داره.

نصب MCP SDK

حالا بریم سراغ نصب. MCP SDK یه کتابخونه رسمیه که Anthropic ساخته و کار ساخت MCP Server رو خیلی ساده می‌کنه. به جای اینکه خودت پروتکل JSON-RPC رو پیاده‌سازی کنی، SDK همه اون بخش رو هندل می‌کنه و تو فقط روی منطق کارت تمرکز می‌کنی.

یه پوشه جدید بساز و پروژه رو راه بنداز:

mkdir my-first-mcp-server
cd my-first-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk

همین! SDK نصب شد. حالا بذار ببینیم چی گرفتیم.

بسته @modelcontextprotocol/sdk شامل همه چیزیه که برای ساخت یه MCP Server لازم داری: مدیریت اتصال، پارس کردن پیام‌های JSON-RPC، تعریف ابزارها، و ارسال پاسخ. تو فقط باید بگی «سرور من چه ابزارهایی داره و هر ابزار چی‌کار می‌کنه.»

ساخت اولین MCP Server

بیا یه MCP Server ساده بسازیم که فقط یه ابزار داره: یه ابزار ساعت که زمان فعلی رو برمی‌گردونه. ساده‌ست ولی همه مفاهیم اصلی رو پوشش می‌ده.

یه فایل به اسم index.js بساز:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "my-clock-server",
  version: "1.0.0"
});

server.tool("get_current_time", "Returns the current date and time", {}, async () => {
  return {
    content: [{
      type: "text",
      text: new Date().toISOString()
    }]
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

بذار خط به خط ببینیم چی نوشتیم:

خط‌های ۱ و ۲: دو چیز اصلی از SDK وارد می‌کنیم — McpServer که هسته سرور ماست و StdioServerTransport که روش ارتباط رو مشخص می‌کنه. Stdio یعنی از ورودی/خروجی استاندارد (stdin/stdout) استفاده می‌کنیم — ساده‌ترین روش ارتباط.

خط‌های ۴-۷: یه سرور MCP جدید می‌سازیم و بهش اسم و نسخه می‌دیم. این اطلاعات به Client گفته می‌شه تا بدونه با چه سروری طرفه.

خط‌های ۹-۱۶: اینجا ابزارمون رو تعریف می‌کنیم. تابع server.tool() چهار تا آرگومان می‌گیره: اسم ابزار، توضیحش (که AI می‌خونه و می‌فهمه کِی باید ازش استفاده کنه)، شمای ورودی (اینجا خالیه چون ورودی نداریم)، و تابعی که ابزار رو اجرا می‌کنه.

خط‌های ۱۸-۱۹: Transport رو می‌سازیم و سرور رو بهش وصل می‌کنیم. از این لحظه سرور آماده‌ست و منتظر درخواسته.

وصل کردن به Claude Desktop

سرور آماده‌ست، حالا باید به Claude Desktop بگیم ازش استفاده کنه. این کار از طریق یه فایل تنظیمات انجام می‌شه.

فایل تنظیمات Claude Desktop رو پیدا کن:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

اگه فایل وجود نداره، بسازش. محتواش رو اینطوری بذار:

{
  "mcpServers": {
    "my-clock-server": {
      "command": "node",
      "args": ["/full/path/to/my-first-mcp-server/index.js"]
    }
  }
}

جای /full/path/to/ مسیر واقعی پوشه پروژه‌ات رو بذار.

حالا Claude Desktop رو ببند و دوباره باز کن. اگه همه چیز درست باشه، باید یه آیکون MCP (شکل چکش 🔨) ببینی که نشون می‌ده سرور وصله.

تست کردن

بیا ببینیم واقعاً کار می‌کنه. توی Claude Desktop بنویس:

«الان ساعت چنده؟»

اگه همه چیز درست باشه، Claude به جای اینکه بگه «من به ساعت دسترسی ندارم»، ابزار get_current_time رو صدا می‌زنه و ساعت دقیق سیستمت رو بهت می‌گه.

اگه کار نکرد، این چک‌لیست رو برو:

1. مسیر فایل: مسیر توی config باید مطلق باشه (مثلاً /Users/you/projects/my-first-mcp-server/index.js)
2. Node.js: مطمئن شو node توی PATH سیستمته
3. package.json: حتماً "type": "module" رو اضافه کردی
4. ریستارت: Claude Desktop رو کامل ببند و دوباره باز کن
5. لاگ‌ها: توی Claude Desktop برو به Developer > Open MCP Log تا خطاها رو ببینی

یه قدم جلوتر — ابزار با ورودی

ابزار ساعت ساده بود. بیا یه ابزار جذاب‌تر بسازیم که ورودی هم بگیره: یه ابزار محاسبه‌گر BMI (شاخص توده بدنی).

server.tool(
  "calculate_bmi",
  "Calculate BMI from weight (kg) and height (cm)",
  {
    weight: { type: "number", description: "Weight in kilograms" },
    height: { type: "number", description: "Height in centimeters" }
  },
  async ({ weight, height }) => {
    const heightInMeters = height / 100;
    const bmi = weight / (heightInMeters * heightInMeters);
    const category = bmi < 18.5 ? "Underweight"
      : bmi < 25 ? "Normal"
      : bmi < 30 ? "Overweight"
      : "Obese";

    return {
      content: [{
        type: "text",
        text: `BMI: ${bmi.toFixed(1)} (${category})`
      }]
    };
  }
);

تفاوت اصلی با ابزار قبلی، آرگومان سوم هست — شمای ورودی. اینجا داریم به AI می‌گیم «این ابزار دو عدد می‌خواد: وزن به کیلوگرم و قد به سانتی‌متر.» Claude از توضیحات هر فیلد می‌فهمه چی بپرسه و چطور مقادیر رو پر کنه.

حالا اگه توی Claude بنویسی «وزنم ۷۵ کیلوئه و قدم ۱۸۰ سانته، BMI رو حساب کن»، Claude خودکار از ابزار calculate_bmi استفاده می‌کنه و نتیجه رو بهت می‌گه.

چی یاد گرفتیم؟

بذار خلاصه کنیم چی از این قسمت برداشتیم:

• نصب آسون: با npm و یه بسته، همه چیز آماده‌ست
• ساختار ساده: یه سرور بساز، ابزارها رو تعریف کن، transport رو وصل کن
• Config Claude: یه فایل JSON ساده سرور رو به Claude معرفی می‌کنه
• ابزار بدون ورودی: مثل ساعت — فقط نتیجه برمی‌گردونه
• ابزار با ورودی: مثل BMI — پارامتر می‌گیره و پردازش می‌کنه