mcp-for-beginners 实战:用 TypeScript / Python / .NET / Java / Rust 编写你自己的 MCP 客户端

原创2026-10-09 14:34:241,748 阅读
文章标签:教程示例工程MCP 服务MCP Clients人工智能

mcp-for-beginners 实战:用 TypeScript / Python / .NET / Java / Rust 编写你自己的 MCP 客户端

客户端(Client)是直接与 MCP 服务器通信、请求资源(Resources)、工具(Tools)与提示词(Prompts)的自定义应用或脚本。与依赖 Inspector 图形界面的交互方式不同,编写自有客户端意味着完全可编程、可自动化的交互,这让你可以把 MCP 能力嵌入到自己的工作流、自动化任务和定制解决方案中。本文以 mcp-for-beginners 课程第二章「Creating a client」为骨架,结合仓库内 TypeScript、Python、.NET、Java、Rust 五套语言的完整示例源码,从导入库、实例化客户端、列出服务器功能、调用功能到运行客户端逐步拆解,学完你将掌握编写并测试跨语言 MCP 客户端、驱动上一章构建的 MCP 服务器的完整能力。

概述与学习目标

本课在 Model Context Protocol(MCP)生态中引入「客户端」这一概念。课程目标是:

  • 理解客户端能做什么;
  • 编写你自己的客户端;
  • 让客户端连接 MCP 服务器并完成测试,确认服务器行为符合预期。

上一章(01-first-server)已经教会你构建 MCP 服务器;本章则从「调用方」视角出发,让同一套服务器可以被你自己的程序驱动。

编写一个客户端需要做什么

从高层看,编写客户端要完成四件事:

  1. 导入正确的库:沿用与服务器相同语言的 MCP SDK,但使用不同的构造(客户端相关 API)。
  2. 实例化客户端:创建客户端实例,并把它连接到选定的传输(Transport)方式。
  3. 决定列出哪些功能:MCP 服务器自带资源、工具和提示词,你需要决定列出其中哪些。
  4. 把客户端集成到宿主应用:在了解服务器能力后,将其接入宿主应用,使得用户输入 prompt 或命令时能触发对应的服务器功能。

一个直观的 TypeScript 示例客户端(完整版见 solution/typescript/src/client.ts):

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["server.js"]
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  }
);

await client.connect(transport);

// 列出提示词
const prompts = await client.listPrompts();

// 获取一个提示词
const prompt = await client.getPrompt({
  name: "example-prompt",
  arguments: { arg1: "value" }
});

// 列出资源
const resources = await client.listResources();

// 读取资源
const resource = await client.readResource({
  uri: "file:///example.txt"
});

// 调用工具
const result = await client.callTool({
  name: "example-tool",
  arguments: { arg1: "value" }
});

这段代码做了三件事:导入库;创建客户端实例并通过 stdio 连接;列出并调用提示词、资源和工具。至此你就拥有一个能与 MCP 服务器对话的客户端。

练习:逐步编写客户端

下面按五个步骤逐段解释代码,你可以跟着一起写。

-1- 导入所需的库

我们需要客户端本身以及所选传输协议的引用。stdio 适合在本机运行的程序,SSE(Server-Sent Events)是另一种传输协议,将在后续章节介绍。本课以 stdio 为主线。

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

Python

from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client

.NET

using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Client;

Java

沿用上一章 01-first-server/solution/java 的 Java Spring Boot 工程结构,在 src/main/java/com/microsoft/mcp/sample/client/ 下新建 SDKClient 类并加入以下 imports(完整实现见 solution/java/src/main/java/com/microsoft/mcp/sample/client/SDKClient.java):

import java.util.Map;
import org.springframework.web.reactive.function.client.WebClient;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.spec.McpClientTransport;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.ListToolsResult;

Rust

在 Cargo.toml 中加入依赖(仓库中 solution 实际使用的版本见 solution/rust/Cargo.toml,其中 rmcp 已升级到 2.x):

[package]
name = "calculator-client"
version = "0.1.0"
edition = "2024"

[dependencies]
rmcp = { version = "0.5.0", features = ["client", "transport-child-process"] }
serde_json = "1.0.141"
tokio = { version = "1.46.1", features = ["rt-multi-thread"] }

随后在客户端代码中导入必要库:

use rmcp::{
    RmcpError,
    model::CallToolRequestParam,
    service::ServiceExt,
    transport::{ConfigureCommandExt, TokioChildProcess},
};
use tokio::process::Command;

-2- 实例化客户端与传输

需要分别创建传输实例和客户端实例。

TypeScript

const transport = new StdioClientTransport({
  command: "node",
  args: ["server.js"]
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  }
);

await client.connect(transport);

这里的关键点:StdioClientTransport 通过 command 和 args 指定如何找到并启动服务器——客户端负责拉起子进程,因此必须给出服务器入口命令。Client 构造函数接收 { name, version } 作为客户端标识(MCP 协议要求每次连接携带客户端身份信息)。最后 connect(transport) 建立连接。仓库里的真实示例指向上一章的服务器:solution/typescript/src/client.ts 使用 command: "node", args: ["./build/index.js"]。

Python

from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client

# 为 stdio 连接创建服务器参数
server_params = StdioServerParameters(
    command="mcp",  # 可执行文件
    args=["run", "server.py"],  # 可选的命令行参数
    env=None,  # 可选的环境变量
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(
            read, write
        ) as session:
            # 初始化连接
            await session.initialize()



if __name__ == "__main__":
    import asyncio

    asyncio.run(run())

这里:StdioServerParameters 用于描述如何启动服务器;stdio_client(server_params) 作为异步上下文管理器返回 (read, write) 流;ClientSession 在其上建立会话并调用 initialize() 完成协议握手。入口处将 run 交给 asyncio.run。对照 solution/python/client.py,初始化后还会继续列资源、列工具、读资源、调工具。

.NET

using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Client;

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration
    .AddEnvironmentVariables()
    .AddUserSecrets<Program>();



var clientTransport = new StdioClientTransport(new()
{
    Name = "Demo Server",
    Command = "dotnet",
    Arguments = ["run", "--project", "path/to/file.csproj"],
});

await using var mcpClient = await McpClient.CreateAsync(clientTransport);

这里创建了 stdio 传输并得到客户端 mcpClient,后续用它列出和调用服务器功能。注意 Arguments 既可以指向 *.csproj 也可以直接指向可执行文件。仓库中的 .NET 客户端(solution/dotnet/Program.cs)甚至直接以相对路径定位同目录 server/bin/Debug/net9.0/server 可执行文件,实现客户端与服务器的同一仓库内自启动。

Java

public class SDKClient {

    public static void main(String[] args) {
        var transport = new WebFluxSseClientTransport(WebClient.builder().baseUrl("http://localhost:8080"));
        new SDKClient(transport).run();
    }

    private final McpClientTransport transport;

    public SDKClient(McpClientTransport transport) {
        this.transport = transport;
    }

    public void run() {
        var client = McpClient.sync(this.transport).build();
        client.initialize();

        // 你的客户端逻辑写在这里
    }
}

要点:main 方法设置指向 http://localhost:8080 的 SSE 传输(服务器将运行于此);客户端类以传输为构造参数;run() 中用 McpClient.sync(this.transport).build() 构建同步客户端并 initialize() 初始化连接。SSE 传输适合与 Java Spring Boot MCP 服务器进行 HTTP 通信。

Rust

该 Rust 客户端假定服务器是同一目录下的姊妹项目 calculator-server,以下代码会启动服务器并连接:

async fn main() -> Result<(), RmcpError> {
    // 假定服务器是同一目录下名为 "calculator-server" 的姊妹项目
    let server_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
        .parent()
        .expect("failed to locate workspace root")
        .join("calculator-server");

    let client = ()
        .serve(
            TokioChildProcess::new(Command::new("cargo").configure(|cmd| {
                cmd.arg("run").current_dir(server_dir);
            }))
            .map_err(RmcpError::transport_creation::<TokioChildProcess>)?,
        )
        .await?;

    // TODO: 初始化

    // TODO: 列出工具

    // TODO: 以 {"a": 3, "b": 2} 调用 add 工具

    client.cancel().await?;
    Ok(())
}

() .serve(...) 是 rmcp 的便捷启动模式,TokioChildProcess 负责把服务器作为子进程拉起并建立 stdio 通道,configure(|cmd| ...) 可定制子进程命令(cargo run + 工作目录)。注意仓库 solution 的 main.rs 实际上启动的是 dotnet run 的 .NET 服务器,并已把「初始化 / 列工具 / 调工具」三个 TODO 全部补齐。

-3- 列出服务器功能

现在客户端已能连接(在服务器运行的前提下),但还没有列出服务器能力,接下来做这件事。

TypeScript

// 列出提示词
const prompts = await client.listPrompts();

// 列出资源
const resources = await client.listResources();

// 列出工具
const tools = await client.listTools();

Python

# 列出可用资源
resources = await session.list_resources()
print("LISTING RESOURCES")
for resource in resources:
    print("Resource: ", resource)

# 列出可用工具
tools = await session.list_tools()
print("LISTING TOOLS")
for tool in tools.tools:
    print("Tool: ", tool.name)

Python 通过 list_resources() 与 list_tools() 列出资源与工具并打印。

.NET

foreach (var tool in await client.ListToolsAsync())
{
    Console.WriteLine($"{tool.Name} ({tool.Description})");
}

上面展示了如何列出服务器工具,并对每个工具打印名称(及描述)。

Java

// 列出并展示工具
ListToolsResult toolsList = client.listTools();
System.out.println("Available Tools = " + toolsList);

// 你也可以 ping 服务器以确认连接
client.ping();

listTools() 获取服务器上全部工具;ping() 验证连接可用;ListToolsResult 包含所有工具的名称、描述和输入模式(schema)。仓库的 SDKClient.java 在 client.initialize() 后立即调用 client.ping() 再 listTools()。

Rust

在 main 函数中初始化客户端后,可以初始化服务器并列出部分能力:

// 初始化
let server_info = client.peer_info();
println!("Server info: {:?}", server_info);

// 列出工具
let tools = client.list_tools(Default::default()).await?;
println!("Available tools: {:?}", tools);

仓库的 main.rs 对 peer_info() 返回的服务器信息做了更完整的展示:服务器名、版本、协议版本、instructions 以及 tools / resources / prompts / completions / logging 等能力开关,并逐个打印工具名与描述。

到这一步我们已经掌握了全部功能清单。这个客户端比较简单——需要显式地按需调用功能。下一章(03-llm-client)会构建接入自有大语言模型 LLM 的进阶客户端。现在先看如何调用服务器功能。

-4- 调用功能

调用功能时,必须确保参数(arguments)正确,某些场景还要指定所调功能的名字。

TypeScript


// 读取资源
const resource = await client.readResource({
  uri: "file:///example.txt"
});

// 调用工具
const result = await client.callTool({
  name: "example-tool",
  arguments: {
    arg1: "value"
  }
});

// 调用提示词
const promptResult = await client.getPrompt({
    name: "review-code",
    arguments: {
        code: "console.log(\"Hello world\")"
    }
})
  • 读取资源:调用 readResource() 并指定 uri。服务器端大概是这样注册的:

    server.resource(
        "readFile",
        new ResourceTemplate("file://{name}", { list: undefined }),
        async (uri, { name }) => ({
          contents: [{
            uri: uri.href,
            text: `Hello, ${name}!`
          }]
        })
    );
    

    客户端的 file://example.txt 与服务器的 file://{name} 模板匹配,example.txt 被映射为 name 参数。

  • 调用工具:指定 name 与 arguments:

    const result = await client.callTool({
        name: "example-tool",
        arguments: {
            arg1: "value"
        }
    });
    
  • 获取提示词:以 name 和 arguments 调用 getPrompt()。服务器端声明如下:

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

    与之匹配的客户端调用即为:

    const promptResult = await client.getPrompt({
        name: "review-code",
        arguments: {
            code: "console.log(\"Hello world\")"
        }
    })
    

仓库 solution/typescript/src/index.ts 演示了同款三件套:add 工具、file://{path} 资源模板、review-code 提示词,可作为「服务器对侧」的参照。

Python

# 读取资源
print("READING RESOURCE")
content, mime_type = await session.read_resource("greeting://hello")

# 调用工具
print("CALL TOOL")
result = await session.call_tool("add", arguments={"a": 1, "b": 7})
print(result.content)

read_resource("greeting://hello") 读取名为 greeting 的资源;call_tool("add", arguments={...}) 调用 add 工具。配套服务器 solution/python/server.py 用 @mcp.resource("greeting://{name}") 和 @mcp.tool() 分别声明了这两者。

.NET

  1. 调用工具:
var result = await mcpClient.CallToolAsync(
    "Add",
    new Dictionary<string, object?>() { ["a"] = 1, ["b"] = 3  },
    cancellationToken:CancellationToken.None);
  1. 打印结果:
Console.WriteLine(result.Content.First(c => c.Type == "text").Text);
// Sum 4

仓库 solution/dotnet/Program.cs 的调用形式类似(工具名 "add",参数 {"a": 1, "b": 3}),并用 ((TextContentBlock)result.Content[0]).Text 提取文本结果。

Java

// 调用各种计算器工具
CallToolResult resultAdd = client.callTool(new CallToolRequest("add", Map.of("a", 5.0, "b", 3.0)));
System.out.println("Add Result = " + resultAdd);

CallToolResult resultSubtract = client.callTool(new CallToolRequest("subtract", Map.of("a", 10.0, "b", 4.0)));
System.out.println("Subtract Result = " + resultSubtract);

CallToolResult resultMultiply = client.callTool(new CallToolRequest("multiply", Map.of("a", 6.0, "b", 7.0)));
System.out.println("Multiply Result = " + resultMultiply);

CallToolResult resultDivide = client.callTool(new CallToolRequest("divide", Map.of("a", 20.0, "b", 4.0)));
System.out.println("Divide Result = " + resultDivide);

CallToolResult resultHelp = client.callTool(new CallToolRequest("help", Map.of()));
System.out.println("Help = " + resultHelp);
  • 用 callTool() + CallToolRequest 调用多个计算工具;
  • 每次调用指定工具名和工具所需的 Map 参数;
  • 服务器工具期望具体的参数名(如数学运算的 "a"、"b");
  • 结果以 CallToolResult 返回,包含服务器响应。

仓库的 SDKClient.java 还额外调用了 power、squareRoot、absolute 等工具,并在结束时 client.closeGracefully() 优雅关闭。

Rust

// 以 {"a": 3, "b": 2} 调用 add 工具
let a = 3;
let b = 2;
let tool_result = client
    .call_tool(CallToolRequestParam {
        name: "add".into(),
        arguments: serde_json::json!({ "a": a, "b": b }).as_object().cloned(),
    })
    .await?;
println!("Result of {:?} + {:?}: {:?}", a, b, tool_result);

CallToolRequestParam 携带工具名与参数,参数用 serde_json::json! 构造;仓库 main.rs 还会解析返回内容中的文本块、检查 is_error 标志并打印友好的结果信息。

-5- 运行客户端

在终端执行以下命令:

TypeScript——在 package.json 的 scripts 中添加如下条目:

"client": "tsc && node build/client.js"
npm run client

Python

python client.py

.NET

dotnet run

Java——先确保 MCP 服务器运行在 http://localhost:8080,再运行客户端:

# 构建项目
./mvnw clean compile

# 运行客户端
./mvnw exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.SDKClient"

也可以直接运行 solution/java 提供的完整客户端工程:

# 进入 solution 目录
cd 03-GettingStarted/02-client/solution/java

# 构建并运行 JAR
./mvnw clean package
java -jar target/calculator-client-0.0.1-SNAPSHOT.jar

Rust

cargo fmt
cargo run

作业:自己动手写一个客户端

本作业要求综合所学,独立创建一个客户端。下面是可供客户端调用的服务器示例,试试再给服务器加更多功能让它更有意思:

TypeScript

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

// 创建 MCP 服务器
const server = new McpServer({
  name: "Demo",
  version: "1.0.0"
});

// 添加加法工具
server.tool("add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

// 添加动态问候资源
server.resource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  async (uri, { name }) => ({
    contents: [{
      uri: uri.href,
      text: `Hello, ${name}!`
    }]
  })
);

// 开始在 stdin 接收消息、在 stdout 发送消息

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCPServer started on stdin/stdout");
}

main().catch((error) => {
  console.error("Fatal error: ", error);
  process.exit(1);
});

Python

# server.py
from mcp.server.fastmcp import FastMCP

# 创建 MCP 服务器
mcp = FastMCP("Demo")


# 添加加法工具
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b


# 添加动态问候资源
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

.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 =>
{
    // 将所有日志配置到 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}";
}

Rust 方面,你在上一节已经学会了用 Rust 创建简单 MCP 服务器,可以在此基础上继续扩展。

解决方案与完整示例

解决方案目录结构

solution 目录包含完整、开箱即用的客户端实现,覆盖本教程全部概念,每个方案都同时包含客户端与服务器代码,按语言组织为独立、自洽的项目(详见 solution/README.md):

solution/
├── typescript/          # 基于 npm/Node.js 的 TypeScript 客户端
│   ├── package.json     # 依赖与脚本
│   ├── tsconfig.json    # TypeScript 配置
│   └── src/             # 源码(client.ts / index.ts)
├── java/                # Java Spring Boot 客户端工程
│   ├── pom.xml          # Maven 配置
│   ├── src/             # Java 源码
│   └── mvnw             # Maven wrapper
├── python/              # Python 客户端实现
│   ├── client.py        # 主客户端代码
│   ├── server.py        # 配套服务器
│   └── README.md        # Python 专属说明
├── dotnet/              # .NET 客户端工程
│   ├── dotnet.csproj    # 工程配置
│   ├── Program.cs       # 主客户端代码
│   └── dotnet.sln       # 解决方案文件
├── rust/                # Rust 客户端实现
│   ├── Cargo.lock       # Cargo 锁定文件
│   ├── Cargo.toml       # 工程配置与依赖
│   ├── src
│   │   └── main.rs      # 主客户端代码
└── server/              # 附加的 .NET 服务器实现
    ├── Program.cs       # 服务器代码
    └── server.csproj    # 服务器工程文件

每个语言方案都包含:教程中的全部客户端功能、正确的依赖与配置、构建/运行脚本、语言专属的详细 README,以及错误处理与结果处理示例。

运行步骤:进入首选语言目录(cd solution/typescript/、cd solution/java/、cd solution/python/、cd solution/dotnet/),按各目录 README 安装依赖、构建并运行客户端。预期输出大致如下:

Prompt: Please review this code: console.log("hello");
Resource template: file
Tool result: { content: [ { type: 'text', text: '9' } ] }

完整的单文件示例

仓库还在 03-GettingStarted/02-client 下提供了 5 个开箱即用、单文件的完整客户端实现:

语言 文件 说明
Java client_example_java.java 使用 SSE 传输、带全面错误处理的完整 Java 客户端
C# client_example_csharp.cs 使用 stdio 传输、自动启动服务器的完整 C# 客户端
TypeScript client_example_typescript.ts 完整支持 MCP 协议的 TypeScript 客户端
Python client_example_python.py 使用 async/await 模式的完整 Python 客户端
Rust client_example_rust.rs 基于 Tokio 异步操作的完整 Rust 客户端

每个完整示例都包含:连接建立与错误处理、服务器发现(工具/资源/提示词)、计算器运算(add、subtract、multiply、divide、help)、结果处理与格式化输出、全面错误处理,以及带逐步注释的干净代码。例如 client_example_typescript.ts 的 extractTextResult() 专门从 { type: "text", text } 结构里抽取文本,并在无文本时回退到整段 JSON 序列化。

上手步骤:从上表选择语言 → 通读完整示例文件理解实现 → 按 complete_examples.md 运行 → 按需定制扩展。各语言在传输、服务器启动方式、异步模型与关键库上的差异一览:

语言 传输 服务器启动 异步模型 关键库
Java SSE/HTTP 外部启动 同步 WebFlux、MCP SDK
C# Stdio 自动 Async/Await .NET MCP SDK
TypeScript Stdio 自动 Async/Await Node MCP SDK
Python Stdio 自动 asyncio Python MCP SDK
Rust Stdio 自动 Async/Await Rust MCP SDK、Tokio

solution 目录 vs 完整单文件示例:solution 提供带构建文件、依赖齐全、可立即运行的完整工程结构(更接近生产形态);完整示例则是单文件、聚焦的参考代码(便于跨语言对比学习)。两者各有价值——完整工程用于实战项目,单文件示例用于学习与参考。

本章要点

关于客户端的核心结论:

  • 客户端既能发现服务器功能,也能调用服务器功能;
  • 客户端可以在自身启动时同时拉起服务器(如本章所示),也可以连接已经运行中的服务器;
  • 除了上一章介绍的 Inspector 之外,编写客户端是测试服务器能力的绝佳途径——可编程、可自动化、可嵌入自定义工作流。

相关示例与下一步

课程还提供了各语言的 Calculator 示例,可继续深入:Java Calculator、.NET Calculator、JavaScript Calculator、TypeScript Calculator、Python Calculator、Rust Calculator。

下一步:阅读创建带 LLM 的客户端,让客户端接入自己的大语言模型,实现更智能的 MCP 应用。

登录后查看全文
mcp-for-beginners