使用 create-mcp-use-app 的 mcp-server 模板:基于 mcp-use 快速搭建可热重载的 MCP Server

原创2026-09-23 14:07:372,001 阅读
文章标签:人工智能AI AgentAgent 框架MCP 服务MCP Clients工具调用后端CLIWebSocket插件系统

使用 create-mcp-use-app 的 mcp-server 模板:基于 mcp-use 快速搭建可热重载的 MCP Server

本指南围绕 create-mcp-use-app 脚手架内置的 mcp-server 模板展开,讲解如何用它初始化一个基于 mcp-use 框架的 TypeScript MCP Server:从 npm install、npm run dev 启动开发服务器并打开 Inspector 调试界面,到解读模板入口文件中的示例 Tool(fetch-weather)与 Prompt(review-code),再到 build / start / typecheck / deploy 等生产命令的完整用法。读完本文,你将掌握 mcp-use 服务端开发的标准工程结构、CLI 工作流与底层实现原理,可以直接在此基础上添加自己的工具与提示词。

模板定位:一个开箱即用的 MCP Server 工程骨架

create-mcp-use-app 是 mcp-use 官方提供的项目脚手架(源码位于 create-mcp-use-app 目录),它预置了三套模板:blank(最小空工程)、mcp-server(本文主角,聚焦 Tool 与 Prompt)、mcp-apps(面向 OpenAI Apps SDK 的视图集成)。本指南关联的模板 README 位于 mcp-server 模板 README,它是一份随脚手架一起生成的“项目使用说明”,覆盖开发、调试、类型检查与部署全流程。

该模板的核心价值在于:无需从零配置 TypeScript、构建管线、热重载和调试面板,一条命令即可获得一个包含示例代码的、可运行的 MCP Server 工程,非常适合作为学习 mcp-use 服务端 API 的起点,也适合作为正式项目的初始骨架。

快速开始:安装依赖并启动开发服务器

模板 README 给出的启动方式非常直接:进入项目目录后依次执行两条命令:

npm install
npm run dev

npm install 会安装模板声明的全部依赖。从 模板 package.json 可以看到核心依赖只有两个:mcp-use(框架本体,内置 CLI 与 Inspector)和 zod(用于 Tool 输入输出的运行时校验);开发依赖为 typescript 与 @types/node。此外 engines 字段要求 node >= 22.22.2,请在启动前确认本机 Node 版本满足要求(node --version)。

npm run dev 实际执行的是 mcp-use dev,它会启动开发服务器并监听文件变更:

  • 服务默认运行在 http://localhost:3000,MCP 端点位于 /mcp;
  • 浏览器会自动打开 Inspector 调试界面,地址为 http://localhost:3000/mcp/inspector;
  • 修改入口文件后服务器自动重载(hot reload),无需手动重启。

启动后即可在 Inspector 中测试 Tool、查看可用的 Prompt、监控服务器状态与工具执行日志。

脚手架生成的项目结构

mcp-server 模板生成的项目非常精简,核心文件如下(对应模板目录 templates/mcp-server):

my-mcp-server/
├── index.ts            # MCP Server 入口文件,定义工具与提示词
├── package.json        # 依赖与 npm scripts(build/dev/start/deploy/typecheck)
├── tsconfig.json       # TypeScript 编译配置
├── mcp-env.d.ts        # mcp-use 自动生成的类型桥接声明(勿手动编辑)
├── public/             # 静态资源(icon.svg)
└── .gitignore          # 预置的忽略规则

其中几个文件值得展开说明:

  • index.ts:模板的业务核心,包含一个示例 Tool 与一个示例 Prompt(下一节详解);
  • tsconfig.json:预配置为 target: "ES2024"、module: "NodeNext"、strict: true、noEmit: true,include 覆盖 index.ts、mcp-env.d.ts、src/**/*、views/**/*、server.ts 以及 .mcp-use/**/*.d.ts(CLI 生成的文件)——这意味着后续扩展源码目录 src/ 时无需改动配置;
  • mcp-env.d.ts:由 mcp-use 生成(文件头注明 “Generated by mcp-use. Do not edit.”),它通过 declare module "mcp-use/react" 的 Register 接口把 index.ts 中导出的 Tool 类型注册到 React 视图层,是服务端与视图端类型联动的桥梁;
  • .gitignore:已忽略 node_modules/、dist/、.mcp-use/、.vite/、各类 .env 文件与日志、IDE 配置等,克隆后无需额外处理。

入口文件解析:示例 Tool 与 Prompt 的完整写法

模板的 index.ts 是整个工程的精华,它演示了 mcp-use 服务端最核心的两种能力:定义 Tool 与定义 Prompt。

首先创建一个 MCPServer 实例:

import { completable, MCPServer } from "mcp-use";
import { z } from "zod";

const server = new MCPServer({
  name: "{{PROJECT_NAME}}",
  title: "{{PROJECT_NAME}}",
  version: "1.0.0",
  description: "An MCP server built with mcp-use",
});

其中 {{PROJECT_NAME}} 是脚手架模板变量,会在 create-mcp-use-app 创建项目时被替换为你输入的项目名。

示例 Tool:fetch-weather 与结构化输出

模板定义了一个返回城市模拟天气的 Tool:

export const fetchWeather = server.tool(
  {
    name: "fetch-weather",
    description: "Return demo weather for a city",
    inputSchema: z.object({ city: z.string() }),
    outputSchema: z.object({
      city: z.string(),
      conditions: z.string(),
      temperature: z.string(),
    }),
    annotations: { readOnlyHint: true, openWorldHint: false },
  },
  async ({ city }) => {
    const weather = { city, conditions: "sunny", temperature: "22°C" };
    return {
      content: [{ type: "text", text: JSON.stringify(weather) }],
      structuredContent: weather,
    };
  }
);

这段代码展示了 mcp-use 工具定义的关键约定:

  • inputSchema / outputSchema 均使用 zod 声明,既提供运行时校验,也为客户端生成 JSON Schema;
  • annotations 中的 readOnlyHint: true 向客户端声明该工具只读、无副作用,openWorldHint: false 表示它不访问外部世界,帮助 AI 客户端合理编排调用;
  • 返回值同时包含 MCP 协议要求的 content(人类可读文本)与 structuredContent(机器可读结构化数据),供视图组件或 Agent 直接消费;
  • server.tool() 的返回值是一个具名导出,这一导出会被 mcp-env.d.ts 中的 Register 接口拾取,从而让客户端获得完整的类型信息。

示例 Prompt:review-code 与 completable 补全

模板还定义了一个代码评审 Prompt,展示了参数自动补全(completion)能力:

server.prompt(
  {
    name: "review-code",
    description: "Review code for correctness and maintainability",
    schema: z.object({
      language: completable(z.string(), [
        "typescript",
        "javascript",
        "python",
        "go",
      ]),
      code: z.string(),
    }),
  },
  async ({ language, code }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Review this ${language} code:\n\n${code}`,
        },
      },
    ],
  })
);

这里的 completable 是 mcp-use 对 MCP completion/complete 能力的封装。从源码 server/src/completable.ts 可以看到它的两种形态:

  • 静态候选值:传入字符串数组时,框架会用 createPrefixCompletion(completable.ts 第 26-36 行)生成一个大小写不敏感的前缀匹配器,当客户端在输入框键入 "t" 时即可提示 typescript 等候选;
  • 动态回调:传入函数时,回调会收到当前输入值与同 Prompt 的其他参数(CompletionContext.arguments),可基于上下文返回动态建议。

源码还特别提醒了两个使用细节:像 .describe() 这类会克隆 schema 的 refinement 应作用于 completable 的参数上而不是其结果上(否则会静默丢失补全标记);而 .optional() 是例外,SDK 在查找补全时会自动解包 optional 字段。

npm scripts 与 mcp-use CLI 工作流

模板 package.json 预置了五个脚本,全部委托给 mcp-use CLI:

命令 底层调用 作用
npm run dev mcp-use dev 启动开发服务器,开启热重载并自动打开 Inspector
npm run build mcp-use build 产出生产构建(输出到 dist/)
npm run start mcp-use start 以生产模式运行构建产物
npm run typecheck mcp-use typecheck 先刷新 MCP 视图类型(.mcp-use/**/*.d.ts),再用本地 TypeScript 做全量检查
npm run deploy mcp-use deploy 部署项目(模板 README 标注为 Manufact Cloud 部署)

其中 dev 与 typecheck 最值得注意:

  • dev 的热重载意味着你只需修改 index.ts 并保存,服务器即自动重启,新 Tool / 新 Prompt 立即可用;
  • typecheck 之所以要“先刷新类型”,是因为 mcp-env.d.ts 引用的 mcp-use/react Register 类型随你新增的工具而变化,必须先由 CLI 重新生成声明,tsc 才能拿到最新类型做检查。

在 Inspector 中调试你的 Server

开发模式下打开 http://localhost:3000/mcp/inspector,即可获得完整的可视化调试面板:

  • 交互式测试 Tool:填写 fetch-weather 的 city 参数并执行,实时查看返回的 content 与 structuredContent;
  • 查看 Prompt:浏览 review-code 的参数 schema 与补全候选;
  • 监控执行日志:查看每次工具调用的请求/响应细节,便于定位问题。

Inspector 是 mcp-use 内置组件(相关文档见 Inspector 指南),无需单独安装。这意味着从“新建项目”到“调试第一个 Tool”,全程只需要一个浏览器标签页。

从模板到生产:构建、部署与扩展

完成开发后,按以下顺序进入生产环节:

npm run typecheck   # 刷新视图类型并做全量类型检查
npm run build       # 生成生产构建到 dist/
npm run start       # 本地运行生产构建
npm run deploy      # 部署(模板 README 说明为 Manufact Cloud)

扩展项目时,推荐的做法是沿用模板的模块化思路:在 src/ 下组织工具与提示词,并在 index.ts 中统一注册(tsconfig.json 已把 src/**/* 纳入编译范围)。更完整的服务端 API(资源、中间件、会话、鉴权、采样等)可继续阅读仓库内文档:

若需了解其他模板(mcp-apps、mcp-ui)与 create-mcp-use-app 的交互式/命令行选项(如 --template、--npm/--pnpm/--bun、--install/--no-install、--list-templates 等),可查阅 create-mcp-use-app README 及 CLI 参数解析源码。

小结

mcp-server 模板用极少的文件覆盖了 mcp-use 服务端开发的全链路:npm install + npm run dev 一键进入带热重载的开发环境,Inspector 提供可视化调试,index.ts 中的示例代码演示了 Tool(含结构化输出与 annotations)和 Prompt(含 completable 补全)的规范写法,typecheck / build / start / deploy 则补齐了从类型检查到生产部署的完整工作流。对于任何想基于 mcp-use 快速交付 MCP Server 的团队或个人,它都是一个可直接起步的工程基线。

登录后查看全文
mcp-use