简化 AI 集成：在 20 分钟内使用 TypeScript 构建单文件 MCP 服务器

厌倦了复杂的构建步骤和配置文件，仅仅是为了将 AI 能力连接到您的应用程序？

预览图AI 故事

要获得免费访问权限，您可以点击 这里。

上周，我花了三天时间尝试设置一个开发环境，以将 Anthropic's Claude 与我天气应用的自定义工具集成。构建错误、依赖冲突和配置噩梦让我开始质疑我的人生选择。就在这时，我发现了一种更好的方法：在一个单独的 TypeScript 文件中创建一个 MCP 服务器，无需构建步骤。

这之间的差别简直天壤之别。让我感到沮丧的几天工作变成了一个实际 可行 的 20 分钟任务。

什么是模型上下文协议 (MCP)？

无

简单来说，MCP 允许 AI 助手在需要特定能力时使用外部工具。如果 Claude 需要查看天气、转换货币或查询您的数据库，MCP 提供了实现这一目标的框架。

MCP 服务器充当 AI 模型与外部服务之间的接口，定义 AI 在需要时可以使用的工具。AI 处理理解和生成自然语言，而 MCP 服务器处理特定领域的功能。

前提条件

在此之前，您需要：

• 基本的 TypeScript 知识（但即使是 JavaScript 开发者也应该没问题）

• 您的机器上安装 Node.js

• 安装 Claude Code CLI（如果您想连接到 Claude）

设置项目

我们的目标是在一个单独的 TypeScript 文件中创建一个 MCP 服务器，无需构建步骤。我们将创建一个简单的天气服务作为我们的示例。

为您的项目创建一个新目录，并初始化一个package.json文件：

mkdir mcp-weather-server

cd mcp-weather-server

npm init -y

接下来，安装必要的依赖项：

npm install @modelcontextprotocol/sdk zod tsx

现在，在您的项目目录中创建一个名为main.ts的文件。这将是我们的单文件 MCP 服务器。

构建 MCP 服务器

让我们逐步解析 MCP 服务器的实现。

步骤 1：导入所需模块

首先，我们需要导入必要的模块：

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

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

import { z } from "zod";

McpServer类是我们实现的核心，允许我们定义和暴露工具。StdioServerTransport通过标准输入/输出实现通信，这是 Claude Code 与我们的服务器交互的方式。Zod 是一个以 TypeScript 为首的模式验证库，我们将用它来定义工具的参数。

步骤 2：创建 MCP 服务器

接下来，我们将初始化一个带有名称和版本的 MCP 服务器：

const server = new McpServer({

name: "Weather Service",

version: "1.0.0",

});

这创建了一个新的服务器实例，带有标识我们服务的元数据。

步骤 3：定义工具

现在，让我们向服务器添加一个工具。我们将创建一个简单的getWeather工具，返回指定城市的天气信息：

server.tool("getWeather")

.parameters(

  z.object({

    city: z.string().describe("The city to get weather for"),

  })

)

.handler(async ({ city }) => {

  // 在实际实现中，您将在此处调用天气 API

  return [

    {

      type: 'text',

      text: `Weather in ${city} is currently sunny with a temperature of 72°F.`

    }

  ];

});

让我们解析一下这里发生的事情：

1. 我们定义了一个名为 "getWeather" 的工具

2. 我们指定该工具接受一个包含单个参数city的对象，该参数是一个字符串

3. 我们实现了一个处理函数，当调用该工具时执行

4. 该处理函数返回一个内容对象的数组，在这种情况下只是一个文本消息

在实际场景中，处理函数可能会调用天气服务的 API 并返回实际的天气数据。对于这个示例，我们只是返回静态文本。

步骤 4：设置通信

最后，我们需要为服务器设置通信通道。由于我们希望通过标准输入/输出与 Claude Code 通信，我们将使用StdioServerTransport：

const transport = new StdioServerTransport();

await server.connect(transport);

这将我们的服务器连接到标准输入/输出流，使其能够接收命令并发送响应。

完整实现

这是我们单文件 MCP 服务器的完整实现：

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 Service",

version: "1.0.0",

});

server.tool("getWeather")

.parameters(

  z.object({

    city: z.string().describe("The city to get weather for"),

  })

)

.handler(async ({ city }) => {

  // 在实际实现中，您将在此处调用天气 API

  return [

    {

      type: 'text',

      text: `Weather in ${city} is currently sunny with a temperature of 72°F.`

    }

  ];

});

const transport = new StdioServerTransport();

await server.connect(transport);

就是这样！仅用这几行代码，我们就创建了一个功能齐全的 MCP 服务器，可以被 Claude Code 或其他 MCP 兼容的客户端使用。

连接到 Claude Code

现在我们有了 MCP 服务器，让我们将其连接到 Claude Code。这将允许 Claude 在与用户交互时使用我们的getWeather工具。

Claude Code 使用claude mcp add命令来注册 MCP 服务器。该命令启动一个交互式对话，您可以在其中指定要连接的服务器。

对于我们的服务器，您可以使用以下命令：

claude mcp add "weather-example" npx tsx "/path-to-your/main.ts"

让我们解析一下这个命令：

•claude mcp add是添加 MCP 服务器的基本命令

•"weather-example"是此连接的名称

•npx tsx "/path-to-your/main.ts"是运行我们服务器的命令

npx tsx部分尤其重要。它允许我们直接运行 TypeScript 文件而无需构建步骤，这正是我们方法的一个关键优势。

一旦该命令成功完成，Claude Code 就能够在需要时使用我们的getWeather工具。

测试集成

要测试我们的集成是否正常工作，您可以与Claude Code开始对话，并询问特定城市的天气。Claude应该能够识别需要使用getWeather工具，并以适当的参数调用它。

例如，您可以问：

What's the weather like in London today?

Claude应该使用getWeather工具，将“London”作为城市参数，并从我们的服务器响应信息。

扩展服务器

虽然我们的示例很简单，但您可以轻松扩展这种方法，以创建更复杂和实用的工具。以下是一些想法：

添加多个工具

您可以通过多次调用server.tool()将多个工具添加到单个MCP服务器中：

server.tool("getWeather")

// ... 天气工具实现

server.tool("convertCurrency")

// ... 货币转换工具实现进行真实的API调用

您需要进行实际的API调用，而不是返回静态数据。因此，您可能需要修改getWeather工具以进行真实的API调用：

import fetch from "node-fetch";

// ...

server.tool("getWeather")

.parameters(

  z.object({

    city: z.string().describe("The city to get weather for"),

  })

)

.handler(async ({ city }) => {

  const apiKey = process.env.WEATHER_API_KEY;

  const url = `https://api.weatherservice.com/current?city=${encodeURIComponent(city)}&apiKey=${apiKey}`;

  const response = await fetch(url);

  const data = await response.json();

  return [

    {

      type: 'text',

      text: `Weather in ${city} is currently ${data.condition} with a temperature of ${data.temperature}°F.`

    }

  ];

});返回结构化数据

MCP支持返回简单文本以外的结构化数据。这可以包括图像、表格、JSON等。以下是一个返回文本和JSON数据的示例：

server.tool("getWeatherDetailed")

.parameters(

  z.object({

    city: z.string().describe("The city to get weather for"),

  })

)

.handler(async ({ city }) => {

  // 获取天气数据...

  return [

    {

      type: 'text',

      text: `Weather in ${city} is currently sunny.`

    },

    {

      type: "json",

      json: {

        temperature: 72,

        condition: "sunny",

        humidity: 45,

        windSpeed: 5,

        forecast: [

          { day: "tomorrow", condition: "partly cloudy", high: 75, low: 60 },

          { day: "day after", condition: "rainy", high: 68, low: 58 }

        ]

      }

    }

  ];

});为什么这种方法很重要

这种单文件创建MCP服务器的方法提供了几个关键优势：

1.简单性：对所有技能水平的开发者更易于访问。

2.可移植性：不必担心复杂的依赖管理或构建配置。

3.快速开发：您可以快速更改MCP服务器并立即测试，而无需等待构建过程完成。

4.与现代AI工具的集成：随着更多桌面应用程序与MCP集成（如Cursor和Windsurf），创建自定义工具的简单方法变得越来越重要。

应用想法

None

MCP服务器的可能性几乎是无限的。以下是您可能构建的一些实际示例：

1. 数据分析工具

创建工具以分析来自各种来源的数据。这将使Claude能够根据最新信息提供见解和可视化。

2. 内容生成助手

构建帮助特定类型内容生成的工具，例如图像创建、代码格式化或专业文档模板。

3. 与内部系统的集成

将Claude连接到您公司的内部系统，使其能够检查库存、更新客户记录或执行其他业务特定功能。

4. 自定义研究助手

开发搜索特定数据库或知识库的工具，使Claude能够在小众领域提供更专业和准确的信息。

最佳实践

None

在开发自己的MCP服务器时，请记住以下最佳实践：

1. 错误处理

实现健壮的错误处理，以确保您的工具能够优雅地处理意外输入或API故障：

.handler(async ({ city }) => {

try {

  // 实现...

} catch (error) {

  return [

    {

      type: 'text',

      text: `Sorry, I encountered an error while fetching weather data: ${error.message}`

    }

  ];

}

});2. 输入验证

使用Zod丰富的验证功能，以确保输入满足您的要求：

.parameters(

z.object({

  city: z.string().min(1).max(100).describe("The city to get weather for"),

  units: z.enum(["metric", "imperial"]).optional().default("imperial")

    .describe("Temperature units (metric or imperial)")

})

)3. 文档

为您的工具和参数提供清晰的描述，以帮助Claude理解何时以及如何使用它们：

server.tool("getWeather")

.description("Get current weather conditions for a specified city")

.parameters(

  // ...

)4. 安全性

注意安全考虑，特别是在处理敏感数据或进行身份验证的API调用时：

• 将API密钥存储在环境变量中，而不是在代码中

• 在使用输入进行API调用之前验证和清理所有输入

• 考虑速率限制以防止滥用

结论

我们探讨了如何在TypeScript中创建单文件MCP服务器并将其连接到Claude Code。这种方法提供了一种简单灵活的方式来扩展AI能力，通过自定义工具，而无需传统服务器设置的复杂性。

tags: #mcps #model-context-protocol #claude #artificial-intelligence #llm