basementstudio/xmcp · 上手攻略

• 仓库：basementstudio/xmcp
• 链接：https://github.com/basementstudio/xmcp
• 分类：MCP 框架 / TypeScript
• 作者：Tom
• 更新：2026-10-10

---

一、是什么

xmcp 是 basement.studio 出品的 TypeScript 框架，专注于快速构建和部署 MCP（Model Context Protocol）服务器。MCP 是 Anthropic 提出的标准化协议，让 AI 助手（如 Claude、ChatGPT）能够调用外部工具和资源；xmcp 的目标是把这一过程变得极度友好——零配置注册、热重载开发、一行命令部署到 Vercel。

v1 于 2026 年发布（采用 MCP SDK v2 / spec 2026-07-28），当前版本 v1.6.0。架构上将编译器（@xmcp-dev/compiler）与运行时（xmcp）分离，开发依赖仅在本地需要，生产构建产物完全自包含。

核心定位：对比直接用 @modelcontextprotocol/typescript-sdk 手工注册所有 tool/prompt/resource，xmcp 用文件系统路由自动完成注册，开发者只需写业务代码。

---

二、解决什么问题

手动创建 MCP 服务器的痛点： - 每个 tool/prompt/resource 都要手工编写注册代码，文件多了难以维护 - 没有热重载，改一行要重启整个服务 - TypeScript 类型安全全靠自己写 Zod schema - 部署时需要自己处理 transport（HTTP/STDIO）

xmcp 解决以上全部：文件路由自动注册、热重载实时反馈、Zod 验证内置、支持 Next.js/Express 适配器、Vercel 零配置部署。

---

三、快速安装

前置要求

• Node.js ≥ 22
• macOS / Windows / Linux

方式一：从零脚手架（新项目）

npx create-xmcp-app@latest

交互式引导会依次询问： 1. 项目名称（生成目录） 2. 模板选择：Default（标准 MCP 服务器）或 MCP App（React 组件嵌入） 3. 包管理器：npm / yarn / pnpm / bun 4. Transport：HTTP（服务端）或 STDIO（本地） 5. 组件注册：Tools / Prompts / Resources（可多选）

方式二：初始化已有项目（Next.js）

cd your-nextjs-project
npx init-xmcp@latest
# 引导指定 tools/prompts/resources/route 目录路径

然后更新 package.json scripts：

{
  "scripts": {
    "dev": "xmcp dev & next dev",
    "build": "xmcp build && next build"
  }
}

Next.js 路由文件（app/mcp/route.ts）：

import { xmcpHandler } from "@xmcp/adapter";
export { xmcpHandler as GET, xmcpHandler as POST };

方式三：初始化已有项目（Express）

// 初始化同上，然后添加路由
import { xmcpHandler } from "path/to/.xmcp/adapter";

app.get("/mcp", xmcpHandler);
app.post("/mcp", xmcpHandler);

手动安装（任意项目）

# npm
npm i xmcp zod@^3.25.76 && npm i -D @xmcp-dev/compiler

# pnpm
pnpm add xmcp zod@^3.25.76 && pnpm add -D @xmcp-dev/compiler

# bun
bun add xmcp zod@^3.25.76 && bun add -D @xmcp-dev/compiler

手动项目需手动配置 xmcp.config.ts 中的 http: true（HTTP transport）或 stdio: true（STDIO transport）。

---

四、核心用法

文件系统路由自动注册

项目创建后，目录结构如下（以 STDIO 模式为例）：

my-xmcp-app/
├── tools/           # 自动注册为 MCP tools
│   └── hello.ts
├── prompts/         # 自动注册为 MCP prompts
│   └── greet.md
├── resources/       # 自动注册为 MCP resources
│   └── config.json
├── xmcp.config.ts
└── package.json

tools 示例（会自动从文件内容推断 schema）：

// tools/hello.ts
import { tool } from "xmcp";

export const hello = tool(
  "hello",
  "Greet a user by name",
  {
    name: z.string().describe("Name of the person to greet"),
    language: z.enum(["en", "zh", "es"]).default("en"),
  },
  async ({ name, language }) => {
    const greetings = { en: `Hello, ${name}!`, zh: `你好，${name}！`, es: `¡Hola, ${name}!` };
    return { message: greetings[language] };
  }
);

⚠️ 注意：schema 必须使用 Zod 定义（v3.25.76+），版本不匹配会导致构建失败。

开发与构建

# 开发模式（热重载）
npm run dev

# 生产构建
npm run build

# STDIO 模式启动
node dist/stdio.js

# HTTP 模式启动
node dist/http.js

构建产物在 dist/ 目录，输出格式由 package.json 的 "type": "module" 决定——有该字段输出 ESM，否则输出 CommonJS。

Vercel 零配置部署

npm i -g vercel
vc deploy

xmcp 与 Vercel 无缝集成，一条命令完成构建和上线。

认证中间件（HTTP 模式）

import { xmcpHandler, withAuth, VerifyToken } from "@xmcp/adapter";

const verifyToken: VerifyToken = async (req, bearerToken) => {
  if (!bearerToken) return undefined;
  const isValid = bearerToken.startsWith("__TEST_VALUE__"); // 替换为真实验证
  if (!isValid) return undefined;
  return {
    token: bearerToken,
    scopes: ["read:messages", "write:messages"],
    clientId: "example-client",
    extra: { userId: "user-123" },
  };
};

const handler = withAuth(xmcpHandler, {
  verifyToken,
  required: true,
  requiredScopes: ["read:messages"],
  resourceMetadataPath: "/.well-known/oauth-protected-resource",
});

export { handler as GET, handler as POST };

⚠️ 注意：middleware.ts 和 xmcp/headers 在 Next.js 适配器中不支持（Next.js 本身已有这些功能）；Express 适配器不支持 middleware.ts。

Next.js 的 tsconfig 路径映射

构建后需要手动配置路径映射（这是目前 DX 上的一个小坑）：

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@xmcp/*": ["./.xmcp/*"]
    }
  }
}

---

五、典型适用场景

场景	说明
AI 助手工具扩展	为 Claude/ChatGPT 等 AI 提供自定义 MCP 工具，让 AI 能够调用内部 API、数据库、文件系统等
多工具 MCP 服务器	需要同时暴露数十个工具的场景，文件路由自动管理避免注册代码膨胀
Next.js/Express 应用扩展	已有 Web 应用，想在其上叠加 MCP 接口，供 AI 调用
Vercel 托管 MCP 服务	不想运维服务器，用 Vercel 零配置部署 MCP 服务
内部 AI 工作流	企业内部工具链（审批、查询、报表）通过 MCP 对接 AI 助手

---

六、坑与注意

1. Node.js 版本：必须 ≥ 22，老版本不兼容 ESM 模块格式（xmcp 默认输出 ESM）。
2. Zod 版本锁定：生产环境建议锁定 zod@^3.25.76，过高或过低版本可能出现 schema 解析差异。
3. 编译器版本同步：@xmcp-dev/compiler 必须与 xmcp 主包版本一致；运行 xmcp dev 报 "compiler missing" 时执行 npm i -D @xmcp-dev/compiler。
4. Next.js 路径映射：初次集成 Next.js 时，xmcp build 生成 .xmcp/adapter 后，TypeScript 不会自动解析 @xmcp/* 路径，需手动添加 tsconfig 映射（如上节）。
5. Transport 配置匹配：xmcp.config.ts 中配置的 transport 必须与 package.json 中 start 脚本的文件名一致（dist/stdio.js vs dist/http.js）。
6. 认证仅 HTTP 模式：STDIO 模式不支持 withAuth，因为 STDIO 是进程间通信而非 HTTP。
7. 热重载不触发构建：修改 xmcp.config.ts 等配置文件后需要手动 xmcp build，仅重启 dev server 无效。

---

七、与同类对比

特性	xmcp	@modelcontextprotocol/typescript-sdk	mcp-framework
上手难度	⭐ 极低（脚手架+路由）	⭐⭐⭐⭐（手写注册）	⭐⭐⭐（类结构）
文件系统路由	✅ 原生	❌ 手动	✅ 目录扫描
热重载	✅ 内置	❌ 需自己配	部分
Next.js/Express 适配器	✅ 原生	❌	❌
Vercel 零配置部署	✅	❌	❌
MCP spec 版本	2026-07-28（SDK v2）	跟随官方	2025-11-25
适合场景	快速原型/生产部署	深度定制/SDK 研究	中等复杂度

⚠️ 版本说明：xmcp 的 MCP spec 版本为"2026-07-28"，来自 GitHub 搜索结果和官方文档（xmcp.dev 首页标注 v1 采用 MCP SDK v2）；mcp-framework.com 标注 2025-11-25。两个框架各自引用的 spec 版本可能存在差异，建议以各自官方文档实时版本为准。

---

八、一句话推荐结论

如果你想快速把业务工具暴露为 MCP 服务，尤其已有 Next.js/Express 项目或打算部署到 Vercel，xmcp 是目前 TypeScript 生态里最低门槛的选择。

---

来源

• GitHub README：https://github.com/basementstudio/xmcp
• 官方文档（Getting Started）：https://xmcp.dev/docs/getting-started/installation
• Next.js 适配器文档：https://xmcp.dev/docs/adapters/nextjs
• Express 适配器文档：https://xmcp.dev/docs/adapters/express
• xmcp.dev 首页（v1 发布信息）：https://xmcp.dev
• 搜索补充：Tavily web search（xmcp v1 版本、mcp-framework 对比）