MCP 服务器开发入门

你的 AI 助手曾经想要访问实时数据吗？Model Context Protocol（MCP）服务器使这成为可能，而且构建和使用它们出人意料地简单！

你可能已经看过我关于使用 Playwright MCP 访问网站、生成测试想法，然后在与网站交互后生成实际 Playwright 测试的视频和文章。或者我如何用它为我购物。这就是 MCP 的力量。它为 AI agent 提供工具，使其能够做诸如连接浏览器或如同 GitHub MCP 那样创建拉取请求等事情。

在本教程中，你将创建一个天气服务器，将 GitHub Copilot 等 AI agent 连接到实时天气数据。本演示将使用 TypeScript，但你可以用其他语言构建 MCP 服务器，链接见文末。完成本教程后，你将能够向 AI 询问任何城市的天气信息，并获得真实的最新响应。

你将学到什么

使用 TypeScript SDK 从零开始构建 MCP 服务器

将其连接到真实的天气 API

将其与 VS Code 和 GitHub Copilot 集成

测试和调试你的服务器

前置要求

TypeScript/JavaScript 基础知识

在你的机器上安装 Node.js

VS Code（可选，但推荐）

什么是 MCP 服务器？

Model Context Protocol（MCP）服务器是连接 AI agent 与外部工具和数据源的桥梁。可以把它们想象成帮助 AI 理解和与现实世界应用交互的翻译器。

问题：访问限制

当你在 VS Code 中向 GitHub Copilot 询问天气信息时，你会得到这样的响应：

"我无法访问实时天气数据或通过此编码环境中的可用工具使用天气 API。"

解决方案：MCP 服务器

MCP 服务器提供缺失的环节，为 AI agent 提供访问实时数据和执行实际操作所需的工具。

我们的天气服务器将充当任何 MCP 兼容 AI 可调用的工具，用于获取世界任何城市的当前天气信息。

第 1 步：项目设置

让我们创建一个新项目并设置我们的开发环境。

1. 初始化项目

创建一个新目录并使用 npm 初始化它：

mkdir mcp-weather-server
cd mcp-weather-server
npm init -y

2. 创建主文件

创建我们的主 TypeScript 文件：

touch main.ts

3. 配置 Package.json

在 VS Code（或你喜欢的编辑器）中打开项目，通过添加 type 字段来修改 package.json，以启用 ES 模块：

{
  "name": "mcp-weather-server",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

为什么要用 ES 模块？MCP SDK 使用现代 JavaScript 模块，所以我们需要在项目中启用它们。

第 2 步：安装依赖

我们的 MCP 服务器需要两个关键库：

1. 安装 MCP SDK

Model Context Protocol SDK 提供了构建 MCP 服务器所需的一切：

npm install @modelcontextprotocol/sdk

2. 安装 Zod 用于数据验证

Zod 确保我们的服务器从 AI agent 接收有效数据：

npm install zod

你的 package.json 依赖项现在应该看起来像这样：

"dependencies": {
  "@modelcontextprotocol/sdk": "^1.13.1",
  "zod": "^3.25.67"
}

第 3 步：构建基础服务器

现在让我们创建我们的 MCP 服务器。打开 main.ts，让我们逐步构建它。

1. 添加必需的导入

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

2. 创建服务器实例

const server = new McpServer({
  name: "Weather Server",
  version: "1.0.0"
});

服务器使用 MCP 协议管理客户端（如 VS Code）和你的工具之间的所有通信。

3. 定义你的第一个工具

工具是 AI agent 可以调用的函数。让我们创建一个 get-weather 工具：

server.tool(
  'get-weather',
  'Tool to get the weather of a city',
  {
    city: z.string().describe("The name of the city to get the weather for")
  },
  async({ city }) => {
    // For now, return a simple static response
    return {
      content: [
        {
          type: "text",
          text: `The weather in ${city} is sunny`
        }
      ]
    };
  }
);

分解工具定义：

工具 ID：'get-weather' - 唯一标识符

描述：帮助 AI agent 理解这个工具的作用

Schema：定义参数（city 必须是字符串）

函数：调用时运行的实际代码

工作流程：

• AI agent 看到："Tool to get the weather of a city"
• AI agent 用以下参数调用它：{ city: "Paris" }
• Zod 验证输入
• 函数返回："The weather in Paris is sunny"

4. 设置通信

最后，我们需要设置服务器如何与 AI 客户端通信：

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

这里发生了什么：

• StdioServerTransport 使用你终端的输入/输出进行通信
• 非常适合本地开发
• 服务器从 stdin 读取请求并向 stdout 写入响应
• MCP 协议自动处理所有消息格式

5. 完整基础服务器示例

你完整的 main.ts 现在应该看起来像这样：

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

const server = new McpServer({
  name: "Weather Server",
  version: "1.0.0"
});

server.tool(
  'get-weather',
  'Tool to get the weather of a city',
  {
    city: z.string().describe("The name of the city to get the weather for")
  },
  async({ city }) => {
    return {
      content: [
        {
          type: "text",
          text: `The weather in ${city} is sunny`
        }
      ]
    };
  }
);

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

🎉 恭喜！你已经构建了你的第一个 MCP 服务器。让我们测试它！

第 4 步：使用 MCP Inspector 测试

在添加真实天气数据之前，让我们使用 MCP Inspector（一个用于调试 MCP 服务器的网络工具）来测试我们的服务器。

运行以下命令来为你的服务器打开 MCP Inspector：

npx -y @modelcontextprotocol/inspector npx -y tsx main.ts

运行命令后，你将看到终端输出，包括：

• 一个 localhost URL（如 http://127.0.0.1:6274）
• 一个唯一的会话令牌
• 一个预填充令牌的直接链接

💡 提示：点击已包含令牌的链接，以避免手动输入。

测试步骤

• 连接：在 Inspector 中点击"Connect"按钮
• 导航：在顶部导航中点击"Tools"
• 选择：选择你的 get-weather 工具
• 测试：输入一个城市名称（如"Palma de Mallorca"）并点击"Run Tool"

你应该看到响应："The weather in Palma de Mallorca is sunny"

连接错误？确保你使用了预填充令牌的链接

完美！你的 MCP 服务器正在工作。现在让我们让它真正有用。

第 5 步：添加真实天气数据

是时候让我们的服务器真正有用了！我们将与 Open-Meteo 集成，这是一个免费的天气 API，不需要 API 密钥。

天气 API 如何工作

为了获取天气数据，我们需要一个两步过程：

1. 将城市名转换为坐标（使用地理编码 API）
2. 使用坐标获取天气（使用天气 API）

更新你的工具函数

用这个增强版本替换你现有的工具函数：

server.tool(
  'get-weather',
  'Tool to get the weather of a city',
  {
    city: z.string().describe("The name of the city to get the weather for")
  },
  async({ city }) => {
    try {
      // Step 1: Get coordinates for the city
      const geoResponse = await fetch(
        `https://geocoding-api.open-meteo.com/v1/search?name=${city}&count=1&language=en&format=json`
      );
      const geoData = await geoResponse.json();

      // Handle city not found
      if (!geoData.results || geoData.results.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `Sorry, I couldn't find a city named "${city}". Please check the spelling and try again.`
            }
          ]
        };
      }

      // Step 2: Get weather data using coordinates
      const { latitude, longitude } = geoData.results[0];
      const weatherResponse = await fetch(
        `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,relative_humidity_2m,apparent_temperature,precipitation,weather_code&hourly=temperature_2m,precipitation&forecast_days=1`
      );

      const weatherData = await weatherResponse.json();

      // Return the complete weather data as JSON
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(weatherData, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching weather data: ${error.message}`
          }
        ]
      };
    }
  }
);

测试实时数据

• 重启你的 MCP Inspector（Ctrl+C，然后重新运行命令）
• 在网页界面中重新连接
• 用真实城市测试，如"Tokyo"或"New York"

你现在应该看到实际天气数据而不是"sunny"！🌤️

第 6 步：与 VS Code 和 GitHub Copilot 集成

现在让我们将你的天气服务器连接到 VS Code，以便你可以与 GitHub Copilot 一起使用它！

配置步骤

• 打开命令面板：Cmd/Ctrl + Shift + P
• 输入：MCP: Add Server
• 选择："Local server using stdio"
• 输入命令：npx -y tsx main.ts
• 名称：my-weather-server
• 设置类型：Local setup

这会在你的项目中创建一个 .vscode/mcp.json 文件：

{
  "inputs": [],
  "servers": {
    "my-weather-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/your-username/path/to/main.ts"
      ]
    }
  }
}

启动并测试

• 启动服务器：点击 MCP 面板中你的服务器名称旁边的"Start"按钮
• 验证：你应该看到"Running"状态
• 切换到 Agent 模式：点击 Copilot 侧边栏 → "Agent Mode"
• 提问："What's the weather like in Tokyo?"

GitHub Copilot 会要求许可使用你的天气工具，点击"Continue"继续。

预期结果

你不是得到原始 JSON，而是得到一个格式良好的天气报告，如：

> **Weather in Tokyo Today**  
> **Temperature:** 28°C (feels like 32°C)  
> **Humidity:** 75%  
> **Conditions:** Partly cloudy with light rain expected in the evening

完美！AI 自动将你的原始天气数据转变为漂亮的人类可读格式。

MCP 的力量

你的天气服务器展示了 MCP 的真正威力：

🤖 AI 承担重担

• 你提供原始数据，AI 创建漂亮的呈现
• 无需格式化响应，AI 处理用户体验

🔗 通用兼容性

• 与任何 MCP 兼容工具协作（VS Code、Claude 等）
• 一次编写，处处使用

⚡ 实时集成

• 总是最新数据，无缓存问题
• 在开发环境中无缝工作

进阶思路

• 添加天气警报、预报或空气质量数据
• 在同一服务器中构建其他工具

完整代码参考

这是你最终的 main.ts 文件：

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

const server = new McpServer({
  name: "Weather Server",
  version: "1.0.0"
});

server.tool(
  'get-weather',
  'Tool to get the weather of a city',
  {
    city: z.string().describe("The name of the city to get the weather for")
  },
  async({ city }) => {
    try {
      const response = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${city}&count=10&language=en&format=json`);
      const data = await response.json();

      if (data.results.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No results found for city: ${city}`
            }
          ]
        };
      }

      const { latitude, longitude } = data.results[0];
      const weatherResponse = await fetch(`https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&hourly=temperature_2m,precipitation,apparent_temperature,relative_humidity_2m&forecast_days=1`);

      const weatherData = await weatherResponse.json();

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(weatherData, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching weather data: ${error.message}`
          }
        ]
      };
    }
  }
);

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

后续步骤：增强你的服务器

准备好将你的天气服务器提升到下一个水平了吗？这是一些想法：

🚀 其他天气工具

server.tool('get-forecast', 'Get 7-day weather forecast', ...)

server.tool('get-alerts', 'Get severe weather warnings', ...)

server.tool('get-air-quality', 'Get air pollution data', ...)

📦 分享你的服务器

发布到 NPM：使其可供他人使用

恭喜！

🎉 恭喜！你已成功构建了你的第一个 MCP 天气服务器！

你的成就

✅ 从零开始创建了一个功能性 MCP 服务器

✅ 集成了来自外部 API 的实时天气数据

✅ 将其连接到 VS Code 和 GitHub Copilot

✅ 学习了 Model Context Protocol 的基础知识

关键收获

• 简洁性：MCP 服务器比看起来要容易得多
• 功能：真实数据使 AI 交互的价值大幅增加
• 灵活性：相同的服务器可跨多个 AI 平台工作
• 前沿：你正在为下一代 AI 构建基础设施

下一步？

可能性无限！天气只是开始，现在你可以将 AI 连接到数据库、API、文件系统和你能想象的任何服务。

📚 资源和进阅读

官方文档

Model Context Protocol Documentation - 完整 MCP 参考

本教程中使用的 API

Open-Meteo Weather API - 免费天气数据服务

库

Zod Documentation - TypeScript schema 验证

示例

MCP Examples Repository - 示例服务器

Playwright MCP - 使用 Playwright 提供浏览器自动化功能

Demo Repo - 演示可在 GitHub 上获得

特别感谢 Miguel Angel Duran 的出色课程和讲解。查看他的西班牙语视频了解类似演示：Learn MCP! For Beginners + Create Our First MCP From Scratch