返回专栏
· 32 分钟阅读

MCP Server 与 Client 的实现:从能力注册到协议通信的完整工程实践


一、MCP Server 与 Client 的职责划分

MCP 的工程实现可以分为两个核心部分:

  • MCP Server: 将外部业务能力封装为 MCP 标准接口。
  • MCP Client: 连接 MCP Server,发现和调用其提供的能力。

两者通过 MCP 协议通信,底层使用 JSON-RPC 消息格式和标准传输机制。

1.1 MCP Server 的核心职责

MCP Server 是能力提供方,负责将业务系统转换为模型可以理解和调用的标准能力。

主要职责:

模块 职责
能力注册 注册 Tools、Resources、Prompts
参数定义 声明输入参数及数据结构
参数校验 验证请求参数的类型和约束
请求处理 接收并路由 MCP 请求
业务执行 调用数据库、API、文件系统等
结果封装 将业务结果转换为 MCP 响应
权限控制 校验身份、授权范围和操作权限
异常处理 处理协议错误和业务错误

Server 并不需要理解大模型的内部推理过程。它只需要提供清晰、可靠、可调用的能力接口。

1.2 MCP Client 的核心职责

MCP Client 是能力调用方,通常运行在 Host 内部。

主要职责:

模块 职责
连接管理 建立和关闭 Server 连接
传输管理 管理 STDIO 或 Streamable HTTP
协议处理 发送和解析 JSON-RPC 消息
能力发现 获取 Server 提供的工具、资源和提示
工具调用 根据工具名称和参数发起调用
请求管理 管理请求 ID、超时和并发
结果处理 解析工具返回内容
异常处理 处理连接失败、协议错误和业务错误

Client 不直接执行 Server 内部的业务逻辑,而是通过协议请求 Server 完成操作。

1.3 两者的完整协作关系

flowchart TB
    A["用户请求"] --> B["Host"]
    B --> C["LLM"]
    B --> D["MCP Client"]

    D --> E["建立传输连接"]
    E --> F["MCP Server"]
    F --> G["能力注册表"]
    F --> H["业务处理层"]
    H --> I["Database / API / File System"]

    D --> J["发现 Tools"]
    J --> G
    D --> K["调用 Tool"]
    K --> F
    F --> H
    H --> L["返回执行结果"]
    L --> D
    D --> B
    B --> C

    style A fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style B fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style H fill:#EAF3EC,stroke:#83A995,color:#315D49
    style I fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F

这里需要区分两个层次:

协议调用与模型决策不是同一件事。

MCP Client 可以直接调用工具,并不要求每次调用都经过大模型。模型负责决定何时使用工具,Host 负责协调模型和 MCP Client,Client 负责执行协议调用。


二、MCP Server 的内部架构

一个可维护的 MCP Server 不应该只是若干个工具处理函数的集合,而应该具有清晰的分层结构。

2.1 推荐架构

flowchart TB
    A["MCP Client"] --> B["Transport Layer"]
    B --> C["Protocol Handler"]
    C --> D["Method Router"]

    D --> E["Tools Registry"]
    D --> F["Resources Registry"]
    D --> G["Prompts Registry"]

    E --> H["Tool Handler"]
    F --> I["Resource Handler"]
    G --> J["Prompt Handler"]

    H --> K["Application Service"]
    I --> K
    J --> K

    K --> L["Repository / Adapter"]
    L --> M["Database / External API / File System"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style E fill:#EAF3EC,stroke:#83A995,color:#315D49
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#EAF3EC,stroke:#83A995,color:#315D49
    style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style I fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style L fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style M fill:#F5F8F4,stroke:#B5CBBB,color:#40594A

各层的职责:

  • Transport Layer:处理 STDIO 或 HTTP 消息传输。
  • Protocol Handler:解析 JSON-RPC 消息并处理协议语义。
  • Method Router:根据 MCP 方法分发请求。
  • Registry:维护已注册的工具、资源和提示。
  • Handler:执行对应能力的处理逻辑。
  • Application Service:实现业务规则。
  • Repository / Adapter:访问底层系统。

SDK 通常已经封装了传输、协议解析和方法路由,因此开发者主要实现能力注册、业务处理和安全控制。

2.2 Server 的核心对象

以 TypeScript SDK v2 为例,服务端使用 McpServer 创建协议服务实例。

核心概念:

对象 作用
McpServer 管理 Server 能力与协议接口
Tool 注册可执行工具
Resource 注册可读取资源
Prompt 注册提示模板
Transport 提供底层通信通道
Handler 实际处理业务请求

Server 的生命周期由应用程序负责启动和关闭,传输对象负责承载协议消息。

2.3 创建项目

当前 TypeScript SDK v2 使用独立的 Server 和 Client 包。

mkdir mcp-demo
cd mcp-demo

npm init -y

npm install @modelcontextprotocol/server zod
npm install -D typescript tsx @types/node

npx tsc --init

建议项目结构:

mcp-demo/
├── src/
│   ├── server/
│   │   ├── index.ts
│   │   ├── tools.ts
│   │   ├── resources.ts
│   │   └── prompts.ts
│   ├── services/
│   │   └── user-service.ts
│   ├── repositories/
│   │   └── user-repository.ts
│   └── shared/
│       └── types.ts
├── package.json
└── tsconfig.json

这里将 MCP 协议层与业务服务层分开,避免工具处理函数直接承担所有业务逻辑。


三、MCP Server:实现工具注册与调用

Tools 是 MCP Server 最常见的能力类型。

它允许 Client 发现工具的名称、描述和输入结构,并通过 tools/call 请求执行。

3.1 定义一个 Tool

以用户查询工具为例。

import * as z from "zod/v4";

const inputSchema = {
  userId: z.string().min(1).describe("用户 ID"),
};

async function getUser(userId: string) {
  return {
    id: userId,
    name: "Alice",
    email: "alice@example.com",
  };
}

工具需要具备三个核心要素:

  1. 名称:用于调用时定位工具。
  2. 描述:帮助模型和客户端理解工具用途。
  3. 输入 Schema:定义调用参数的结构和约束。

工具描述不应该只写一个名称。对于模型而言,描述质量直接影响工具选择和参数构造的准确性。

3.2 注册 Tool

import { McpServer } from "@modelcontextprotocol/server";
import * as z from "zod/v4";

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

server.registerTool(
  "get_user",
  {
    title: "查询用户",
    description: "根据用户 ID 查询用户基本信息",
    inputSchema: {
      userId: z.string().min(1),
    },
  },
  async ({ userId }) => {
    const user = await getUser(userId);

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(user),
        },
      ],
    };
  },
);

registerTool 将工具元数据、输入 Schema 和执行处理函数绑定在一起。

当 Client 调用 tools/list 时,SDK 可以根据注册信息生成工具描述。

当 Client 调用 tools/call 时,SDK 根据工具名称找到对应处理函数。

3.3 工具参数校验

参数校验是 Server 实现中非常重要的一环。

不能因为 Client 声明了参数 Schema,就假设所有请求一定合法。

原因包括:

  • Client 可能存在实现缺陷。
  • 参数可能由模型生成。
  • 用户可能构造恶意请求。
  • 旧版本 Client 可能发送不兼容参数。
  • 网络请求可能被人为修改。

例如:

const searchSchema = {
  keyword: z.string().min(1).max(100),
  limit: z.number().int().min(1).max(50).default(10),
};

这里包含:

  • 类型约束。
  • 非空约束。
  • 字符长度限制。
  • 整数约束。
  • 数值范围限制。
  • 默认值。

参数 Schema 既是协议接口描述,也是服务端输入校验的重要依据。

但 Schema 校验不能代替业务权限校验。例如,userId 即使是合法字符串,也不代表当前用户有权读取该用户的数据。

3.4 Tool 的返回结果

MCP 工具通常通过 content 返回内容。

例如:

return {
  content: [
    {
      type: "text",
      text: "查询成功",
    },
  ],
};

也可以返回结构化数据:

return {
  content: [
    {
      type: "text",
      text: "查询成功",
    },
  ],
  structuredContent: {
    id: "1001",
    name: "Alice",
    active: true,
  },
};

两者用途不同:

  • content:面向通用内容展示和处理。
  • structuredContent:提供结构化结果,便于客户端程序直接消费。

如果工具定义了输出 Schema,应确保实际返回的数据符合该结构。

不要将所有结果都简单地 JSON 序列化为文本。对于需要程序化处理的数据,结构化输出更合适。

3.5 完整 Server 示例

下面实现一个可通过 STDIO 启动的用户服务 MCP Server。

// src/server/index.ts

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const users = [
  {
    id: "1001",
    name: "Alice",
    email: "alice@example.com",
  },
  {
    id: "1002",
    name: "Bob",
    email: "bob@example.com",
  },
];

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

// 注册查询用户工具
server.registerTool(
  "get_user",
  {
    title: "查询用户",
    description: "根据用户 ID 查询用户信息",
    inputSchema: {
      userId: z.string().min(1),
    },
  },
  async ({ userId }) => {
    const user = users.find((item) => item.id === userId);

    if (!user) {
      return {
        content: [
          {
            type: "text",
            text: `用户不存在:${userId}`,
          },
        ],
        isError: true,
      };
    }

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(user),
        },
      ],
      structuredContent: user,
    };
  },
);

// 注册用户列表工具
server.registerTool(
  "list_users",
  {
    title: "用户列表",
    description: "查询系统中的用户列表",
    inputSchema: {
      keyword: z.string().optional(),
    },
  },
  async ({ keyword }) => {
    const result = users.filter((user) => {
      if (!keyword) return true;

      return (
        user.name.includes(keyword) ||
        user.email.includes(keyword)
      );
    });

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result),
        },
      ],
      structuredContent: {
        users: result,
        total: result.length,
      },
    };
  },
);

// 启动 STDIO Server
serveStdio(() => server);

启动:

npx tsx src/server/index.ts

这个 Server 会通过标准输入输出与 MCP Client 通信。

注意:实际 STDIO Server 的 stdout 只能用于 MCP 协议消息,调试日志应输出到 stderr,不能使用普通 console.log 污染协议通道。


四、MCP Server:实现 Resources 与 Prompts

除了 Tools,Server 还可以提供 Resources 和 Prompts。

三者的设计目标不同,不能简单地都当作工具处理。

4.1 Resources:提供数据资源

Resources 主要用于暴露可读取的数据。

例如:

  • 配置文件。
  • 项目文档。
  • 数据库中的只读信息。
  • API 返回的数据。
  • 系统运行状态。

注册资源:

server.registerResource(
  "project-config",
  "config://project",
  {
    title: "项目配置",
    description: "读取当前项目的配置文件",
    mimeType: "application/json",
  },
  async (uri) => {
    const config = {
      name: "mcp-demo",
      version: "1.0.0",
      environment: "development",
    };

    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(config),
        },
      ],
    };
  },
);

Resource 的关键在于 URI。

Client 可以根据 URI 读取指定资源,而不必知道资源背后的数据库或文件系统实现。

4.2 Resource Template:参数化资源

有些资源不是固定地址,而是根据参数动态定位。

例如:

user://1001
user://1002
user://1003

这类场景可以使用 Resource Template。

server.registerResource(
  "user-profile",
  "user://{userId}",
  {
    title: "用户资料",
    description: "根据用户 ID 读取用户资料",
    mimeType: "application/json",
  },
  async (uri, { userId }) => {
    const user = users.find(
      (item) => item.id === userId,
    );

    if (!user) {
      throw new Error("User not found");
    }

    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(user),
        },
      ],
    };
  },
);

Resource Template 适合参数化资源访问,但它仍然是资源读取机制,不等同于可执行 Tool。

4.3 Prompts:提供可复用提示模板

Prompts 用于向 Client 暴露可复用的提示模板。

例如代码审查模板:

server.registerPrompt(
  "review_code",
  {
    title: "代码审查",
    description: "根据指定语言审查代码",
    argsSchema: {
      language: z.string(),
      code: z.string(),
    },
  },
  async ({ language, code }) => {
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `
请审查以下 ${language} 代码。

重点检查:
1. 逻辑错误
2. 性能问题
3. 安全风险
4. 可维护性

代码:

${code}
`,
          },
        },
      ],
    };
  },
);

Prompts 的重点是提示模板管理,而不是执行外部业务操作。

4.4 三种能力的选择

能力 主要用途 是否执行操作
Tools 执行业务动作或计算 可以
Resources 暴露可读取的数据 主要用于读取
Prompts 提供可复用提示模板 不负责业务执行

选择时可以遵循:

  • 需要执行查询、创建、修改或计算,优先考虑 Tool。
  • 需要提供可读取的数据,考虑 Resource。
  • 需要提供标准化的提示模板,考虑 Prompt。

实际应用中三者可以组合使用。


五、MCP Server:业务逻辑与异常处理

工具注册只是入口,真正的工程难点在于业务逻辑的可靠执行。

5.1 不要将业务逻辑写在 Tool Handler 中

不推荐:

server.registerTool(
  "create_order",
  {
    description: "创建订单",
    inputSchema: {
      productId: z.string(),
      quantity: z.number(),
    },
  },
  async ({ productId, quantity }) => {
    // 参数校验
    // 用户权限判断
    // 库存查询
    // 价格计算
    // 数据库事务
    // 订单创建
    // 日志记录
    // 返回结果
  },
);

这种写法会导致协议处理和业务逻辑高度耦合。

更合理的方式是分层:

server.registerTool(
  "create_order",
  {
    description: "创建订单",
    inputSchema: {
      productId: z.string(),
      quantity: z.number().int().min(1),
    },
  },
  async ({ productId, quantity }) => {
    const result = await orderService.createOrder({
      productId,
      quantity,
    });

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result),
        },
      ],
      structuredContent: result,
    };
  },
);

业务规则放在 orderService,数据访问放在 Repository。

这样同一套业务逻辑可以被 MCP Server、REST API 和后台任务复用。

5.2 业务错误与协议错误

MCP Server 需要区分两类失败。

协议错误:

  • JSON-RPC 格式不正确。
  • 方法不存在。
  • 参数结构无效。
  • 请求不符合协议要求。

这类错误由 SDK 的协议层负责处理。

工具执行错误:

  • 用户不存在。
  • 库存不足。
  • 数据库不可用。
  • 外部 API 请求失败。
  • 当前用户没有执行权限。

工具业务错误可以通过工具结果的 isError 表达。

例如:

server.registerTool(
  "get_user",
  {
    description: "查询用户",
    inputSchema: {
      userId: z.string(),
    },
  },
  async ({ userId }) => {
    try {
      const user = await userService.getUser(userId);

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(user),
          },
        ],
        structuredContent: user,
      };
    } catch (error) {
      console.error("get_user failed:", error);

      return {
        content: [
          {
            type: "text",
            text: "查询用户失败,请检查用户 ID 或稍后重试",
          },
        ],
        isError: true,
      };
    }
  },
);

生产环境中不应把数据库连接字符串、SQL 堆栈、内部文件路径或访问令牌直接返回给模型。

5.3 幂等性与副作用控制

对于只读工具,重复调用通常不会造成数据修改。

但对于以下操作:

  • 创建订单。
  • 扣减库存。
  • 转账。
  • 删除文件。
  • 修改用户权限。

重复执行可能产生严重后果。

因此,具有副作用的工具应考虑:

  1. 幂等键。
  2. 操作记录。
  3. 数据库事务。
  4. 状态校验。
  5. 重复请求检测。
  6. 高风险操作的用户确认。

MCP 的请求 ID 只是协议层请求关联标识,不能直接当作业务幂等键。

同一个业务动作可能经过不同请求 ID 重试,因此需要独立设计业务幂等机制。


六、MCP Server:STDIO 与 Streamable HTTP 实现

Server 的业务能力可以保持一致,传输层则根据部署场景选择。

6.1 STDIO Server

STDIO 适合本地工具集成。

例如:

  • 本地文件系统。
  • 本地代码仓库。
  • 开发环境工具。
  • 桌面 AI 应用。

使用官方 TypeScript SDK v2:

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";

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

server.registerTool(
  "hello",
  {
    description: "返回问候信息",
    inputSchema: {},
  },
  async () => ({
    content: [
      {
        type: "text",
        text: "Hello MCP",
      },
    ],
  }),
);

serveStdio(() => server);

Host 启动 Server 子进程后,Client 通过子进程的标准输入输出与其通信。

6.2 Streamable HTTP Server

远程部署通常使用 Streamable HTTP。

import { McpServer } from "@modelcontextprotocol/server";
import { serve } from "@modelcontextprotocol/server/http";

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

server.registerTool(
  "get_status",
  {
    description: "获取系统运行状态",
    inputSchema: {},
  },
  async () => ({
    content: [
      {
        type: "text",
        text: JSON.stringify({
          status: "healthy",
          timestamp: new Date().toISOString(),
        }),
      },
    ],
  }),
);

serve(server, {
  port: 3000,
});

这里展示的是 SDK v2 的 HTTP 启动模式。实际部署时还需要根据所使用的 SDK 版本和运行环境配置认证、监听地址、请求限制和关闭流程。

6.3 传输层如何选择

场景 推荐传输
本地桌面应用 STDIO
本地开发工具 STDIO
本地子进程集成 STDIO
远程企业服务 Streamable HTTP
多实例部署 Streamable HTTP
云端 MCP 服务 Streamable HTTP

业务能力不应与传输实现耦合。

同一个 Server 可以通过不同 Transport 对外提供相同的业务接口,但应根据 SDK 的具体接口和部署方式配置相应的传输适配。


七、MCP Client 的内部架构

MCP Client 负责连接 Server 并使用其提供的能力。

它通常包括以下模块:

模块 职责
Client Instance MCP 客户端实例
Transport 传输连接
Protocol Layer JSON-RPC 消息管理
Discovery 能力发现
Tool Manager 工具列表和调用
Resource Manager 资源列表和读取
Prompt Manager 提示模板列表和获取
Request Manager 请求关联、超时和并发
Result Adapter 结果转换

7.1 Client 的工作流程

flowchart TD
    A["创建 MCP Client"] --> B["创建 Transport"]
    B --> C["连接 MCP Server"]
    C --> D["确定协议版本"]
    D --> E["发现 Server 能力"]
    E --> F["获取 Tools / Resources / Prompts"]
    F --> G["保存可用能力"]
    G --> H["等待调用请求"]
    H --> I["构造 MCP 请求"]
    I --> J["发送请求"]
    J --> K["接收响应"]
    K --> L["解析执行结果"]
    L --> M["返回 Host"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#EAF3EC,stroke:#83A995,color:#315D49
    style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style I fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style J fill:#EAF3EC,stroke:#83A995,color:#315D49
    style K fill:#EAF3EC,stroke:#83A995,color:#315D49
    style L fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style M fill:#DCEFE5,stroke:#4F8B70,color:#24563F

注意:能力发现与连接建立的具体顺序取决于协议版本和 SDK。旧版协议需要先完成初始化握手;新版无状态协议可以在需要时进行能力发现,再发送独立请求。

7.2 创建 Client

TypeScript SDK v2 将 Client 与 Server 拆分为独立包。

安装:

npm install @modelcontextprotocol/client

创建客户端:

import { Client } from "@modelcontextprotocol/client";

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

Client 负责 MCP 协议层面的能力调用,不负责决定大模型是否应该使用某个工具。

7.3 连接 STDIO Server

Client 可以启动一个本地 MCP Server 子进程。

import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

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

const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", "src/server/index.ts"],
});

await client.connect(transport);

这里的 Transport 负责:

  • 启动 Server 进程。
  • 管理标准输入输出。
  • 发送 JSON-RPC 消息。
  • 接收 Server 返回的消息。
  • 处理连接终止。

Client 不需要自己实现 JSON-RPC 编解码。

7.4 发现工具列表

连接成功后,可以获取 Server 提供的工具。

const result = await client.listTools();

console.log(result.tools);

典型返回结构:

{
  "tools": [
    {
      "name": "get_user",
      "description": "根据用户 ID 查询用户信息",
      "inputSchema": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string"
          }
        },
        "required": ["userId"]
      }
    }
  ]
}

Client 可以根据工具列表构建工具注册表,供 Host 或模型使用。

7.5 调用 Tool

const result = await client.callTool({
  name: "get_user",
  arguments: {
    userId: "1001",
  },
});

console.log(result);

Client 不需要知道工具内部如何访问数据库,也不需要知道业务 API 的具体地址。

它只需要知道工具名称、参数结构和调用结果。

7.6 读取 Resource

const result = await client.readResource({
  uri: "config://project",
});

console.log(result.contents);

7.7 获取 Prompt

const result = await client.getPrompt({
  name: "review_code",
  arguments: {
    language: "TypeScript",
    code: "const a = 1;",
  },
});

console.log(result.messages);

以上展示的是 SDK 的高层调用接口。不同 SDK 版本的构造参数、导入路径和传输适配 API 可能不同,实际项目应以锁定版本的 API 文档为准。


八、MCP Client:工具发现与动态调用

Client 的重要能力之一,是动态发现 Server 提供的工具。

这意味着 Host 不必将所有工具名称和参数写死在代码中。

8.1 动态工具注册

假设 Client 连接了三个 Server:

  • GitHub Server。
  • Database Server。
  • Filesystem Server。

它们分别提供不同的工具。

Client 可以统一发现工具,并构建一份工具注册表。

flowchart TD
    A["MCP Client Manager"] --> B["GitHub Client"]
    A --> C["Database Client"]
    A --> D["Filesystem Client"]

    B --> E["GitHub Tools"]
    C --> F["Database Tools"]
    D --> G["Filesystem Tools"]

    E --> H["统一工具注册表"]
    F --> H
    G --> H

    H --> I["Host / LLM Tool Adapter"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#EAF3EC,stroke:#83A995,color:#315D49
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#EAF3EC,stroke:#83A995,color:#315D49
    style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F

8.2 工具名称冲突

不同 Server 可能注册相同名称的工具。

例如:

github.search
database.search
filesystem.search

如果只使用 search 作为全局名称,就可能出现冲突。

建议采用命名空间:

const toolRegistry = {
  "github.search": {
    server: "github",
    tool: "search",
  },
  "database.search": {
    server: "database",
    tool: "search",
  },
  "filesystem.search": {
    server: "filesystem",
    tool: "search",
  },
};

命名空间不仅解决名称冲突,还可以帮助 Host 识别工具来源和权限范围。

8.3 工具列表动态变化

Server 的工具集合可能发生变化。

例如:

  • 管理员启用新的业务能力。
  • 插件升级后增加工具。
  • 用户权限变化。
  • Server 根据配置动态注册工具。

Client 不应永久假设第一次发现的工具列表就是最终列表。

可以根据 Server 提供的列表变化通知、连接状态以及应用策略,重新获取工具清单。

同时应处理:

  • 工具被删除。
  • 工具参数结构变化。
  • 工具名称变化。
  • 权限变化。
  • Server 不可用。

工具描述和参数 Schema 也需要纳入缓存版本管理,避免 Client 使用过期定义调用工具。


九、MCP Client:多 Server 连接管理

真实 AI 应用通常需要连接多个 MCP Server。

因此,不能只实现一个简单的 Client 实例,还需要建立 Client Manager。

9.1 多 Server 架构

flowchart TB
    A["Host"] --> B["MCP Client Manager"]

    B --> C["Client A"]
    B --> D["Client B"]
    B --> E["Client C"]

    C --> F["GitHub Server"]
    D --> G["Database Server"]
    E --> H["Filesystem Server"]

    F --> I["GitHub API"]
    G --> J["Database"]
    H --> K["File System"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#EAF3EC,stroke:#83A995,color:#315D49
    style H fill:#EAF3EC,stroke:#83A995,color:#315D49
    style I fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style J fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style K fill:#F5F8F4,stroke:#B5CBBB,color:#40594A

一个 Client 通常对应一个 Server 的逻辑连接。

Host 通过 Client Manager 管理多个连接,而不是将多个 Server 的通信逻辑混在一个 Client 中。

9.2 Client Manager 的实现思路