项目简介

该项目是 Zuplo 提供的 Model Context Protocol (MCP) 服务器端开发工具包 (SDK)，使用 TypeScript 编写，旨在帮助开发者快速构建符合 MCP 标准的应用后端。它支持基于 'fetch' API 的远程服务器架构，可以方便地部署在各种支持 'fetch' API 的环境中，如 Zuplo, Node.js, Deno, Workerd 等。

主要功能点

核心 MCP 服务器实现: 提供了 'MCPServer' 类，用于管理 MCP 服务器的状态和能力。
工具 (Tools) 管理: 允许注册、列出和执行 LLM 客户端调用的工具。支持使用 Zod 或自定义验证器定义工具的输入参数。
传输协议: 提供了 'HTTPStreamableTransport' 实现，支持通过 HTTP (包括 SSE 用于服务器到客户端的消息流) 进行通信，符合 WinterTC 关于流式 HTTP 传输的规范。
JSON-RPC 处理: 内部处理 JSON-RPC 2.0 协议的请求、响应和通知的解析与路由。
会话管理: 传输层支持基本的会话管理功能。
能力声明: 服务器在初始化时会向客户端声明其支持的能力（如工具）。

安装步骤

作为 Node.js 或 TypeScript 项目的依赖，可以使用 npm 或 yarn 进行安装：

npm install @zuplo/mcp
# 或
yarn add @zuplo/mcp

服务器配置 (为 MCP 客户端准备)

MCP 服务器通常作为独立进程运行，LLM 客户端需要知道如何启动并连接到它。你需要提供服务器的启动命令和参数给 MCP 客户端。这通常通过一个 JSON 格式的配置对象来完成。

配置信息通常包含以下关键字段：

'name': 字符串，服务器的友好名称。
'command': 字符串，用于启动服务器可执行文件或脚本的命令（例如 'node'）。
'args': 字符串数组，传递给启动命令的参数（例如编译后的服务器入口文件路径 '["dist/index.js"]'）。

请注意: MCP 客户端不需要你提供 MCP 服务器的源代码或编译后的二进制文件。它只需要知道如何启动服务器以及服务器将使用的 传输方式 (例如，如果使用 Stdio 传输，客户端会管理服务器进程的标准输入输出；如果使用 HTTP 传输，客户端会连接到指定的网络地址)。

例如，如果你的 MCP 服务器代码编译后生成 'dist/index.js' 文件，并且你可以通过 'node dist/index.js' 命令启动它，那么提供给客户端的配置可能是：

{
  "name": "我的MCP计算器服务",
  "command": "node",
  "args": ["dist/index.js"]
}

(重要: 上述 JSON 配置仅为示例说明，请勿直接将此代码块复制到客户端配置中，你需要根据你的实际项目和编译/运行方式生成对应的 command 和 args)

基本使用方法

创建 MCP 服务器实例:

import { MCPServer } from "@zuplo/mcp/server";

const server = new MCPServer({
  name: "My MCP Server",
  version: "1.0.0",
  // 可以选择性添加 capabilities 或 instructions
});

添加工具 (Tools): 使用 'server.addTool' 方法注册你的工具逻辑，包括名称、描述、输入参数验证器和处理函数。该 SDK 提供了 'ZodValidator' 和 'CustomValidator'。

import { ZodValidator } from "@zuplo/mcp/tools/zod";
import { z } from "zod";

server.addTool({
  name: "add",
  description: "Adds two numbers",
  validator: new ZodValidator(z.object({ a: z.number(), b: z.number() })),
  handler: async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
    isError: false,
  }),
});

选择并连接传输 (Transport): 实例化一个传输对象，并将其连接到服务器。示例中最常用的是 'HTTPStreamableTransport'。你需要将 HTTP 请求传递给传输对象的 'handleRequest' 方法。

import { HTTPStreamableTransport } from "@zuplo/mcp/transport/httpstreamable";
import { Hono } from "hono"; // 示例使用 Hono

const transport = new HTTPStreamableTransport();
await transport.connect(); // 初始化传输

server.withTransport(transport); // 将服务器逻辑与传输关联

// 示例: 使用 Hono 处理 HTTP 请求并将原始请求传递给 transport
const app = new Hono();
app.post('/mcp', async (c) => {
  const httpRequest = c.req.raw; // 获取原始 Fetch API Request 对象
  return transport.handleRequest(httpRequest); // 让 transport 处理 MCP 请求并返回 HTTP Response
});

// 启动 HTTP 服务器监听 incoming requests
// 例如使用 @hono/node-server 的 serve
// import { serve } from '@hono/node-server';
// serve({ fetch: app.fetch, port: 3000 });

通过以上步骤，你就构建了一个基本的 MCP 服务器，它可以接收 MCP 客户端的请求（如 'initialize', 'ping', 'tools/list', 'tools/call'）并作出响应。对于更高级的功能（如资源、Prompt、订阅等），你需要根据 MCP 协议和 SDK 提供的类型/接口来实现相应的处理逻辑。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (为 MCP 客户端准备)

基本使用方法

信息