MCP开发入门教程：从零理解模型上下文协议

1. 什么是 MCP

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 于 2024 年底开源的一种开放协议，用于统一大语言模型与外部数据源、工具之间的通信方式。它解决的核心问题是：当模型需要访问数据库、文件系统、API 或企业内部系统时，不再需要为每个数据源单独编写适配代码，而是通过一套标准化的协议进行连接。

2. MCP 的核心架构

MCP 采用客户端-服务器架构，主要由以下三个角色组成：

MCP Host：运行大语言模型的宿主程序，例如 Claude Desktop、IDE 插件或自定义应用，负责发起请求并展示结果。
MCP Client：与 Host 同侧运行，负责与 MCP Server 建立连接、发送请求、接收响应。
MCP Server：暴露工具、资源和提示词能力的服务端，封装具体的数据源或业务逻辑。

一次典型的调用流程如下：Host 向 Client 发起工具调用请求，Client 通过 JSON-RPC 与 Server 通信，Server 执行具体操作后返回结构化结果，最终由 Host 呈现给模型或用户。

3. 环境准备

在开始开发之前，需要准备以下环境：

Node.js 18 及以上版本（或 Python 3.10 及以上版本，取决于你选择的 SDK）。
一个 MCP Host 用于测试，例如 Claude Desktop 或支持 MCP 的 IDE。
安装官方 SDK：TypeScript 使用 @modelcontextprotocol/sdk，Python 使用 mcp 包。

下面以 TypeScript 为例，创建一个新的项目并安装依赖：

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

4. 编写第一个 MCP Server

下面实现一个最简单的 MCP Server，它暴露一个「获取当前时间」的工具。创建 server.ts 文件：

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

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

server.tool(
  "get_current_time",
  { timezone: { type: "string", description: "时区，例如 Asia/Shanghai" } },
  async ({ timezone }) => {
    const now = new Date().toLocaleString("zh-CN", { timeZone: timezone });
    return { content: [{ type: "text", text: `当前时间：${now}` }] };
  }
);

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

代码说明：

McpServer 是 SDK 提供的高层封装，简化了工具注册流程。
server.tool 用于注册工具，第一个参数是工具名，第二个参数是入参 schema，第三个参数是执行函数。
StdioServerTransport 通过标准输入输出与 Host 通信，是本地开发最常用的传输方式。

5. 在 Host 中配置并测试

以 Claude Desktop 为例，在配置文件 claude_desktop_config.json 中添加如下配置：

{
  "mcpServers": {
    "time-server": {
      "command": "node",
      "args": ["dist/server.js"]
    }
  }
}

配置完成后重启 Host，即可在对话中调用 get_current_time 工具。你可以这样提问：「请告诉我现在东京的时间」，模型会自动调用该工具并返回结果。

6. 进阶：连接真实数据源

实际开发中，MCP Server 更多用于连接数据库、文件系统或第三方 API。下面以读取本地文件为例，演示如何暴露一个文件读取工具：

import { readFile } from "fs/promises";

server.tool(
  "read_file",
  { path: { type: "string", description: "文件绝对路径" } },
  async ({ path }) => {
    try {
      const content = await readFile(path, "utf-8");
      return { content: [{ type: "text", text: content }] };
    } catch (err) {
      return { content: [{ type: "text", text: `读取失败：${err.message}` }] };
    }
  }
);

通过这种方式，模型就能安全地访问你授权的本地文件，而无需直接暴露整个文件系统。