使用 create-mcp-use-app 的 mcp-server 模板:基于 mcp-use 快速搭建可热重载的 MCP Server
使用 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/reactRegister 类型随你新增的工具而变化,必须先由 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 的团队或个人,它都是一个可直接起步的工程基线。