创建您的第一个 MCP 服务器

欢迎踏上 Model Context Protocol (MCP) 的第一步！无论您是 MCP 的新手还是希望深入了解的开发者，本指南将带您完成基本的设置和开发过程。您将发现 MCP 如何实现 AI 模型与应用程序之间的无缝集成，并学习如何快速准备环境以构建和测试基于 MCP 的解决方案。

简而言之：如果您开发 AI 应用程序，您可能知道可以为 LLM（大型语言模型）添加工具和其他资源，以使其更智能。然而，如果您将这些工具和资源放在服务器上，无论是否使用 LLM，任何客户端都可以使用该应用程序和服务器的功能。

概述

本课程提供了设置 MCP 环境和构建第一个 MCP 应用程序的实用指导。您将学习如何设置必要的工具和框架，构建基本的 MCP 服务器，创建主机应用程序，并测试您的实现。

Model Context Protocol (MCP) 是一个开放协议，标准化了应用程序向 LLM 提供上下文的方式。可以将 MCP 想象成 AI 应用程序的 USB-C 接口——它提供了一种标准化的方式，将 AI 模型连接到不同的数据源和工具。

学习目标

完成本课程后，您将能够：

• 为 C#、Java、Python、TypeScript 和 Rust 设置 MCP 开发环境
• 构建和部署具有自定义功能（资源、提示和工具）的基本 MCP 服务器
• 创建连接到 MCP 服务器的主机应用程序
• 测试和调试 MCP 实现

设置 MCP 环境

在开始使用 MCP 之前，准备开发环境并了解基本工作流程非常重要。本节将指导您完成初始设置步骤，以确保顺利开始使用 MCP。

前置条件

在开始 MCP 开发之前，请确保您具备以下条件：

• 开发环境：支持您选择的语言（C#、Java、Python、TypeScript 或 Rust）
• IDE/编辑器：Visual Studio、Visual Studio Code、IntelliJ、Eclipse、PyCharm 或其他现代代码编辑器
• 包管理器：NuGet、Maven/Gradle、pip、npm/yarn 或 Cargo
• API 密钥：用于您计划在主机应用程序中使用的任何 AI 服务

基本 MCP 服务器结构

一个 MCP 服务器通常包括：

• 服务器配置：设置端口、认证及其他设置
• 资源：提供给 LLM 的数据和上下文
• 工具：模型可以调用的功能
• 提示：用于生成或组织文本的模板

以下是 TypeScript 的一个简化示例：

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

// Create an MCP server
const server = new McpServer({
  name: "Demo",
  version: "1.0.0"
});

// Add an addition tool
server.tool("add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

// Add a dynamic greeting resource
server.resource(
  "file",
  // The 'list' parameter controls how the resource lists available files. Setting it to undefined disables listing for this resource.
  new ResourceTemplate("file://{path}", { list: undefined }),
  async (uri, { path }) => ({
    contents: [{
      uri: uri.href,
      text: `File, ${path}!`
    }]
  })
);

// Add a file resource that reads the file contents
server.resource(
  "file",
  new ResourceTemplate("file://{path}", { list: undefined }),
  async (uri, { path }) => {
    let text;
    try {
      text = await fs.readFile(path, "utf8");
    } catch (err) {
      text = `Error reading file: ${err.message}`;
    }
    return {
      contents: [{
        uri: uri.href,
        text
      }]
    };
  }
);

server.prompt(
  "review-code",
  { code: z.string() },
  ({ code }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Please review this code:\n\n${code}`
      }
    }]
  })
);

// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);

在上述代码中，我们：

• 从 MCP TypeScript SDK 导入必要的类。
• 创建并配置一个新的 MCP 服务器实例。
• 注册一个自定义工具（calculator）及其处理函数。
• 启动服务器以监听传入的 MCP 请求。

测试和调试

在开始测试 MCP 服务器之前，了解可用工具和调试的最佳实践非常重要。有效的测试可以确保您的服务器按预期运行，并帮助您快速识别和解决问题。以下部分概述了验证 MCP 实现的推荐方法。

MCP 提供了一些工具来帮助您测试和调试服务器：

• Inspector 工具：这个图形界面允许您连接到服务器并测试工具、提示和资源。
• curl：您也可以使用命令行工具如 curl 或其他能够创建和运行 HTTP 命令的客户端连接到服务器。

使用 MCP Inspector

MCP Inspector 是一个可视化测试工具，它可以帮助您：

1. 发现服务器功能：自动检测可用的资源、工具和提示
2. 测试工具执行：尝试不同的参数并实时查看响应
3. 查看服务器元数据：检查服务器信息、架构和配置

# ex TypeScript, installing and running MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

运行上述命令后，MCP Inspector 将在浏览器中启动一个本地网页界面。您可以看到一个仪表板，显示已注册的 MCP 服务器及其可用工具、资源和提示。界面允许您交互式测试工具执行、检查服务器元数据并查看实时响应，从而更轻松地验证和调试 MCP 服务器实现。

以下是界面可能的样子：

常见设置问题及解决方案

问题	可能的解决方案
连接被拒绝	检查服务器是否正在运行以及端口是否正确
工具执行错误	检查参数验证和错误处理
认证失败	验证 API 密钥和权限
架构验证错误	确保参数与定义的架构匹配
服务器无法启动	检查端口冲突或缺少依赖项
CORS 错误	为跨域请求配置正确的 CORS 头
认证问题	验证令牌的有效性和权限

本地开发

对于本地开发和测试，您可以直接在机器上运行 MCP 服务器：

1. 启动服务器进程：运行您的 MCP 服务器应用程序
2. 配置网络：确保服务器可以通过预期的端口访问
3. 连接客户端：使用本地连接 URL，例如 http://localhost:3000    

# Example: Running a TypeScript MCP server locally
npm run start
# Server running at http://localhost:3000

构建您的第一个 MCP 服务器

我们在之前的课程中已经介绍了核心概念，现在是时候将这些知识付诸实践了。

服务器可以做什么

在开始编写代码之前，让我们回顾一下服务器可以做什么：

一个 MCP 服务器可以：

• 访问本地文件和数据库
• 连接到远程 API
• 执行计算
• 集成其他工具和服务
• 提供用户交互界面

很好，现在我们知道它的功能了，开始编写代码吧。

练习：创建服务器

要创建服务器，您需要完成以下步骤：

• 安装 MCP SDK。
• 创建项目并设置项目结构。
• 编写服务器代码。
• 测试服务器。

-1- 创建项目

.NET

dotnet new console -n McpCalculatorServer
cd McpCalculatorServer

-2- 添加依赖项

现在您已经创建了项目，接下来添加依赖项：

.NET

安装所需的 NuGet 包：

dotnet add package ModelContextProtocol --prerelease
dotnet add package Microsoft.Extensions.Hosting

-3- 编写服务器代码

.NET

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(consoleLogOptions =>
{
    // Configure all logs to go to stderr
    consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace;
});

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();
await builder.Build().RunAsync();

// add features

-4- 添加工具和资源

通过添加以下代码来添加工具和资源：

.NET

将以下内容添加到您的 Program.cs 文件：

[McpServerToolType]
public static class CalculatorTool
{
    [McpServerTool, Description("Adds two numbers")]
    public static string Add(int a, int b) => $"Sum {a + b}";
}

-5- 完整代码

让我们添加最后的代码以启动服务器：

.NET

创建一个 Program.cs 文件，内容如下：

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(consoleLogOptions =>
{
    // Configure all logs to go to stderr
    consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace;
});

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();
await builder.Build().RunAsync();

[McpServerToolType]
public static class CalculatorTool
{
    [McpServerTool, Description("Adds two numbers")]
    public static string Add(int a, int b) => $"Sum {a + b}";
}

-6- 测试服务器

使用以下命令启动服务器：

.NET

确保您在项目目录中：

cd McpCalculatorServer
dotnet run

-7- 使用 Inspector 运行

Inspector 是一个非常棒的工具，可以启动您的服务器并与之交互，以测试其是否正常工作。让我们启动它：

备注

"command" 字段可能看起来不同，因为它包含运行服务器的特定运行时命令。

.NET

确保您在项目目录中：

cd McpCalculatorServer
npx @modelcontextprotocol/inspector dotnet run

1. 通过选择“Connect”按钮连接到服务器，连接到服务器后，您应该会看到以下内容：

   

2. 选择“Tools”和“listTools”，您应该会看到“add”出现，选择“add”并填写参数值。您应该会看到以下响应，即来自“add”工具的结果：

   

恭喜您，您已经成功创建并运行了您的第一个服务器！

关键要点

• 使用语言特定的 SDK 设置 MCP 开发环境非常简单
• 构建 MCP 服务器需要创建并注册具有清晰架构的工具
• 测试和调试对于可靠的 MCP 实现至关重要