1. 项目概述快速构建云端AI工具平台如果你和我一样每天都在和 Cursor、Claude 这类 AI 编程助手打交道那你肯定也遇到过这样的痛点想让它帮你查个数据库、调个第三方 API或者执行一些特定的自动化任务却发现它“能力有限”很多想法无法直接实现。传统的解决方案要么是写一堆复杂的本地脚本让 AI 去调用过程繁琐且难以维护要么就是等待官方或社区推出对应的插件遥遥无期。最近Model Context Protocol 的出现为这个问题提供了一个优雅的解法。简单来说MCP 就像一套标准的“插座”和“插头”规范它允许你将自己的工具比如一个查询天气的 API、一个操作数据库的函数封装成标准化的“工具”然后让 Claude、Cursor 这类支持 MCP 的 AI 助手直接“插上”使用。这意味着你可以为你的 AI 伙伴定制专属的超能力。然而构建一个 MCP 服务器本身涉及服务端开发、部署、配置等一系列工作对于只想快速验证一个工具想法的开发者来说门槛依然不低。这正是create-mcp这个 CLI 工具要解决的问题。它不是一个复杂的框架而是一个极致的“脚手架”目标只有一个让你在几分钟内从一个简单的 TypeScript 函数想法到一个运行在云端、可被 Cursor Agent 直接调用的 MCP 工具。它的核心哲学是“写函数得工具”将开发体验简化到了极致。2. 核心思路与方案选型解析2.1 为什么选择 MCP 与 Cloudflare Workers 的组合在决定使用create-mcp之前我们需要理解其背后的技术选型逻辑。这决定了整个方案的适用场景和优势边界。首先是 MCP 协议本身。在 MCP 出现之前为 AI 助手扩展功能通常有两种方式一是针对特定 AI 产品如 Cursor开发私有插件这种方式绑定性强迁移成本高二是使用 OpenAI 的 Function Calling 等方案但这通常需要将工具逻辑和提示词深度耦合在应用代码中。MCP 的突破性在于它定义了一个与 AI 模型和客户端均无关的、标准化的工具协议。一个按照 MCP 规范实现的服务器理论上可以被任何兼容 MCP 的客户端如 Claude Desktop、Cursor、未来可能更多的 AI 应用使用。这带来了真正的“一次编写多处运行”的可能性极大地保护了开发者的投资。其次是 Cloudflare Workers 作为部署平台。create-mcp坚定地选择了 Workers这并非偶然而是经过深思熟虑的“最佳实践”选择。我们可以从几个维度来对比开发体验与速度Workers 采用无服务器架构你无需关心服务器运维。wranglerCLI 工具链成熟部署命令一条搞定从代码到全球网络边缘节点通常只需几十秒。这种“瞬发”体验对于需要快速迭代工具功能的场景至关重要。成本与性能Workers 拥有非常慷慨的免费额度对于个人或小规模使用的 MCP 工具来说几乎可以做到零成本运行。同时得益于 Cloudflare 的全球边缘网络你的工具无论在哪里被调用都能获得极低的延迟这对于需要与 AI 进行实时交互的工具来说体验提升明显。安全性将工具逻辑部署在云端Workers而非在用户本地运行带来一个隐性的安全好处。你可以将敏感的 API Keys、数据库连接凭证等安全地存储在 Workers 的环境变量中避免它们随着代码被分发或在用户本地环境泄露。AI 客户端只需通过一个安全的 HTTPS 端点与你的工具通信。“无进程”体验这是原作者强调的“Vibes”。本地运行 MCP 服务器意味着你需要常驻一个 Node.js 进程管理它的启动、停止、日志和资源占用。而云端部署彻底消除了这一切你和使用你的工具的人都无需关心后台发生了什么工具就像一项随时可用的公共服务。基于以上分析create-mcp的定位非常清晰它为希望快速为 AI 助手构建轻量级、云端化、标准化工具的开发者提供了一条阻力最小的路径。你不需要是后端专家甚至不需要知道 HTTP 服务器如何搭建你只需要会写 TypeScript 函数。2.2 工具链与前置条件剖析工欲善其事必先利其器。create-mcp对工具链的选择也体现了其追求简洁高效的思路。Bun 作为运行时与包管理器项目推荐使用bun create命令来初始化。Bun 是一个新兴的 JavaScript 运行时它集成了包管理、打包、测试等功能其启动速度和安装依赖的速度通常显著快于传统的 npm。对于create-mcp这种需要快速克隆、安装、构建的项目来说Bun 能提供更流畅的体验。当然如果你习惯使用npm或yarn理论上也可以适配但官方脚本和文档都是围绕 Bun 优化的。Wrangler CLI 的必要性这是与 Cloudflare Workers 交互的官方命令行工具。它负责了从项目初始化、本地开发、到最终部署的全生命周期管理。create-mcp本质上是在 Wrangler 提供的基础能力之上封装了针对 MCP 服务器的模板和自动化流程。因此安装并登录 Wrangler (wrangler login) 是硬性前提这相当于获取了部署到 Cloudflare 平台的“通行证”。对 Claude Desktop 的依赖是暂时的文档中提到需要 Claude Desktop是因为目前它作为一个 MCP 客户端被用于在部署后自动添加服务器配置实现“开箱即用”。这是一个临时的用户体验优化步骤。未来随着 Cursor 等 IDE 对 MCP 的原生支持更加完善这一步可能会被移除或改变。即使没有 Claude Desktop你依然可以手动将从 Workers 获取的 MCP 服务器连接信息配置到 Cursor 中。注意虽然工具链力求简洁但请确保你的开发环境已安装 Node.js (或 Bun) 和 Git。因为整个流程涉及从 GitHub 克隆模板、安装 npm 包等操作。3. 从零到一完整实操流程拆解让我们抛开概念直接上手看看如何从一个空文件夹到一个可用的 MCP 工具。我会以创建一个“网络文章摘要生成器”工具为例演示全流程。3.1 环境准备与项目初始化首先确保你的系统满足基础要求安装 Bun访问 bun.sh 根据指引安装。安装 Wrangler 并登录npm install -g wrangler wrangler login执行wrangler login会打开浏览器引导你授权 Wrangler 访问你的 Cloudflare 账户。请确保你拥有一个 Cloudflare 账号并且有权限创建 Workers。完成上述步骤后初始化项目就变得极其简单。打开终端进入你希望创建项目的目录然后执行bun create mcp article-summarizer这里article-summarizer是你自定义的项目也是最终的 Worker名称。如果不指定名称CLI 会交互式地询问你。执行后发生了什么在后台CLI 执行了一系列原子操作理解它们有助于排查可能的问题克隆模板它从预设的 GitHub 仓库克隆一个预先配置好的 MCP Worker 模板到./article-summarizer目录。安装依赖进入新目录运行bun install安装所有必要的 npm 包包括modelcontextprotocol/sdkMCP 官方 SDK和wrangler等。初始化 Git在新目录中执行git init为你后续的版本管理做好准备。部署与配置这是最关键的一步。它调用wrangler deploy将模板中的“Hello World”示例代码部署到你的 Cloudflare 账户。部署成功后你会获得一个唯一的*.workers.dev子域名例如article-summarizer.your-username.workers.dev。紧接着CLI 会尝试调用本地 Claude Desktop 应用将这个部署好的 Worker 地址作为 MCP 服务器添加进去。复制连接命令最后它将生成一条形如npx modelcontextprotocol/server-cli http://article-summarizer.your-username.workers.dev的命令复制到你的剪贴板。这条命令就是 Cursor 等客户端连接此 MCP 服务器所需的信息。整个过程如果顺利终端会输出部署成功的 URL并且你可以直接在 Cursor 中粘贴命令来连接了。3.2 核心开发将函数转化为 AI 工具项目初始化后核心的开发工作全部集中在src/index.ts文件中的MyWorker类里。这是“写函数得工具”理念的体现。让我们打开src/index.ts你会看到一个初始的sayHello示例。我们现在要把它改造成我们的文章摘要工具。假设我们调用一个外部摘要 API这里以 Hypothetical API 为例。首先我们需要在wrangler.toml配置文件中添加我们的 API 密钥作为环境变量确保安全name article-summarizer compatibility_date 2024-01-01 [vars] HYPOTHETICAL_SUMMARY_API_KEY your_api_key_here # 在此处填入你的真实API密钥然后重写src/index.tsimport { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; export interface Env { HYPOTHETICAL_SUMMARY_API_KEY: string; } // 一个模拟的摘要函数实际项目中你会替换为真实的API调用 async function fetchSummaryFromAPI(url: string, apiKey: string): Promisestring { // 这里模拟一个网络请求 // 实际实现可能使用 fetch、axios 等 console.log([Mock API] Summarizing article at ${url} with key: ${apiKey.substring(0, 5)}...); // 模拟延迟 await new Promise(resolve setTimeout(resolve, 500)); return 这是一篇关于人工智能最新进展的文章摘要。文章讨论了多模态模型的发展并展望了未来的应用前景。 (模拟结果源自: ${url}); } export default class MyWorker { private server: McpServer; constructor(private env: Env) { this.server new McpServer({ name: article-summarizer, version: 1.0.0, }); this.setupTools(); } private setupTools() { // 工具1文章摘要 this.server.tool( summarize_article, // 工具名称在AI调用时会用到 获取指定URL的网络文章内容并生成简洁摘要。适用于快速了解长文核心内容。, // 工具描述AI根据此决定是否及如何调用 { url: z.string().url().describe(需要摘要的文章的完整URL地址。), // 定义参数及其验证规则 }, async ({ url }) { // 这里是工具的核心逻辑 console.log([Worker] Starting summary for: ${url}); try { const summary await fetchSummaryFromAPI(url, this.env.HYPOTHETICAL_SUMMARY_API_KEY); return { content: [ { type: text, text: ## 文章摘要\n**原文链接**: ${url}\n\n**摘要**: ${summary}, }, ], }; } catch (error) { console.error([Worker] Summary failed:, error); return { content: [ { type: text, text: 抱歉处理文章摘要时出现错误${error instanceof Error ? error.message : 未知错误}, }, ], }; } } ); // 工具2你可以继续添加更多工具例如翻译摘要、提取关键词等 this.server.tool( get_server_info, 获取当前MCP服务器的基本信息如名称和版本。, {}, async () { return { content: [{ type: text, text: 服务器: article-summarizer v1.0.0\n状态: 运行正常\n已注册工具: summarize_article, get_server_info, }], }; } ); } async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { // 这个fetch方法是Cloudflare Worker的入口点 // 对于MCP over HTTP我们需要在这里处理来自客户端的请求 // 模板已处理好这部分我们通常无需修改 // ... (模板原有代码) } }代码解析与关键点工具注册 (this.server.tool)这是 MCP SDK 的核心方法。它接收四个参数工具名、描述、参数模式Schema和异步处理函数。工具名应使用蛇形命名snake_case描述应清晰具体这直接决定了 AI 理解和使用工具的能力。参数模式与验证我们使用zod库来定义参数的类型和约束。例如z.string().url()确保了传入的url参数必须是一个合法的 URL 字符串。describe方法中的文本会作为参数说明传递给 AI。严格的参数验证是构建健壮工具的关键能有效防止无效调用。环境变量 (this.env)在构造函数中注入的env对象包含了我们在wrangler.toml中定义的所有变量。这样我们可以在工具逻辑中安全地使用 API 密钥而无需将其硬编码在源码中。返回值格式MCP 工具要求返回一个特定格式的对象其中content数组包含要返回给 AI 的内容。目前主要支持text类型。返回结构化的文本如使用 Markdown可以帮助 AI 更好地理解和利用结果。错误处理在工具函数内部使用try...catch进行错误捕获非常重要。即使调用失败也应该返回一个友好的错误信息给 AI而不是让整个请求崩溃。这提升了工具的可靠性。3.3 部署更新与客户端连接开发完成后我们需要将更新部署到云端并让 Cursor Agent 感知到新工具。部署更改cd article-summarizer bun run deploy这条命令会触发构建和部署流程。wrangler会将你的 TypeScript 代码编译、打包并推送到 Cloudflare 网络。控制台会输出成功的部署版本和 URL。在 Cursor 中连接 MCP 服务器如果初始化时 CLI 已通过 Claude Desktop 完成配置并且你使用的是 Cursor 的最新版本已内置 MCP 客户端支持理论上重启 Cursor 后 Agent 就能看到新工具。如果需要手动配置或者你想在另一个 Cursor 实例中使用可以这样做在 Cursor 中打开命令面板 (Cmd/Ctrl Shift P)。搜索并选择 “Cursor: Manage MCP Servers”。点击 “Add New MCP Server”。在 “Server Command” 输入框中粘贴之前 CLI 复制到剪贴板的命令或者手动输入npx modelcontextprotocol/server-cli http://article-summarizer.your-username.workers.dev。保存后重启 Cursor 的 Agent 会话通常关闭并重新打开 Agent 聊天窗口即可。测试工具 在 Cursor 的 Agent 聊天窗口中你现在可以直接询问“请用 summarize_article 工具帮我总结一下这篇文章https://example.com/some-long-article”。 Cursor Agent 会识别到可用的工具自动填充参数调用你的云端 Worker并将返回的摘要呈现给你。4. 进阶技巧与架构探讨4.1 工具设计的最佳实践仅仅能让 AI 调用工具还不够设计出“好用”的工具才能最大化价值。以下是我从实践中总结的几个原则单一职责与原子性一个工具最好只做一件事。不要设计一个“获取用户信息并发送邮件并更新数据库”的庞然大物。将其拆分为get_user_info、send_email、update_user_record等多个原子工具。这样 AI 更容易理解和组合使用也便于你单独调试和更新。描述即契约工具的名称和描述是 AI 理解其功能的唯一依据。描述应精确、无歧义并包含典型使用场景。例如“转换货币”就不如“根据实时汇率将一种货币金额转换为另一种货币金额”来得清晰。善用参数约束充分利用zod的验证能力。除了类型还可以用.min(),.max(),.regex()等来限制输入范围用.describe()提供更详细的参数说明。这能减少无效请求并引导 AI 提供正确的输入。结构化输出虽然目前主要返回文本但尽量返回结构清晰的内容。使用 Markdown 标题、列表、代码块等可以帮助 AI 更好地解析和利用返回的信息。例如一个查询数据库的工具可以返回 Markdown 表格形式的数据。4.2 性能、安全与错误处理将工具部署在云端就需要以生产级的标准来考量。性能优化Cloudflare Workers 有 CPU 时间限制通常为 10-30 毫秒的“CPU 时间”注意不是现实时间。如果你的工具逻辑复杂或涉及长时间的网络 I/O如调用慢速 API需要考虑使用缓存对于不常变的数据可以利用 Workers 的 Cache API 或外部 KV 存储来缓存结果。异步与非阻塞确保你的代码是异步的避免同步的繁忙循环。优化依赖检查package.json移除未使用的依赖保持部署包体积小巧。安全性加固环境变量所有密钥、令牌都必须通过wrangler.toml或 Cloudflare 仪表板的环境变量管理绝不入库。输入验证这是第一道防线。zod模式必须严格。对于 URL 参数要警惕 SSRF 攻击对于字符串注意注入攻击。访问控制可选如果你的工具比较敏感可以考虑在 Worker 入口点 (fetch方法) 添加简单的认证例如验证一个预共享的令牌。但注意MCP over HTTP 标准本身不包含认证这需要客户端配合。速率限制利用 Workers 的 Durable Objects 或外部服务如 Cloudflare自身速率限制为你的工具添加调用频率限制防止滥用。全面的错误处理工具函数内部的try...catch应捕获所有可能异常并返回对 AI 友好的错误信息。同时考虑在 Worker 的顶层fetch函数中也添加全局错误处理防止未预料的错误导致整个 Worker 响应失败。4.3 复用与扩展克隆现有服务器create-mcp生态的一个强大特性是项目的可克隆性。如果你在 GitHub 上看到了一个别人用此模板构建的优秀 MCP 服务器如官方示例中的 Neon、Vercel API 等你可以直接将其部署到自己的账户下并在此基础上修改。bun create mcp --clone https://github.com/zueai/vercel-api-mcp my-vercel-tools这个命令会克隆指定的 GitHub 仓库到./my-vercel-tools。运行bun install。尝试部署到你的 Cloudflare 账户可能需要你根据原项目的README配置相应的环境变量。这为你提供了极高的起点。你可以学习他人的工具设计快速获得一个具备成熟功能的服务端然后只修改或添加你需要的部分。这极大地促进了 MCP 工具生态的共享和协作。5. 常见问题与排查实录在实际使用中你可能会遇到一些障碍。以下是我遇到过的典型问题及其解决方案。5.1 部署与连接问题问题现象可能原因排查步骤与解决方案bun create mcp命令失败或卡住1. 网络问题无法访问 GitHub 或 npm 仓库。2. Bun 未正确安装。3. Wrangler 未登录。1. 检查网络连接尝试使用镜像源。2. 运行bun --version确认安装。重装 Bun。3. 运行wrangler whoami确认登录状态。重新执行wrangler login。部署成功但 Cursor Agent 无法连接或找不到工具。1. Cursor 版本过旧不支持 MCP。2. MCP 服务器命令未正确配置到 Cursor。3. Worker 代码存在运行时错误导致 MCP 服务器初始化失败。4. Claude Desktop 配置未同步到 Cursor。1. 确保 Cursor 更新到最新版本通常要求 0.37。2. 在 Cursor 中手动检查 “Manage MCP Servers” 列表确认服务器命令npx ...正确无误。特别注意命令中的 URL 必须是https://开头。3. 查看 Cloudflare Worker 的日志在 Cloudflare 仪表板 Workers Pages 你的 Worker Logs。检查是否有未捕获的异常导致MyWorker类初始化失败。4. Cursor 和 Claude Desktop 的 MCP 配置通常是独立的。需要分别在各自客户端中添加服务器。工具调用后AI 收到“内部错误”或超时。1. 工具函数内部抛出未捕获的异常。2. Worker 执行超时默认50秒但CPU时间限制很严。3. 调用的外部 API 失败或超时。1.查看 Worker 日志。这是最重要的调试手段。所有console.log和未捕获的错误都会在这里显示。2. 在工具函数内部添加更详细的try-catch并返回明确的错误信息。3. 优化工具逻辑避免长时间同步操作。对于慢速 API考虑是否真的适合在 Worker 中同步调用。修改代码并重新部署后Cursor 中的工具行为未更新。1. Cursor 客户端缓存了旧的工具列表。2. 部署未成功或版本未切换。1.重启 Cursor 的 Agent 会话。最简单的方法是关闭当前的 Agent 聊天窗口再重新打开一个新的。2. 在 Cloudflare 仪表板中确认 Worker 的最新部署是否处于“Active”状态。5.2 开发与调试技巧本地开发虽然create-mcp强调云端部署但本地调试对于复杂工具开发至关重要。你可以使用wrangler dev命令在本地启动一个开发服务器它会模拟 Cloudflare Workers 环境。然后你可以使用npx modelcontextprotocol/server-cli http://localhost:8787来让本地的 MCP 客户端或配置 Cursor 使用本地地址进行连接测试。这能极大提升开发效率。日志是生命线养成在工具关键步骤添加console.log的习惯。在 Cloudflare Worker 仪表板的“Logs”标签页下你可以实时看到这些日志这对于追踪调用流程和定位错误不可或缺。逐步构建不要一开始就试图构建一个功能完备的工具。先从最简单的“Hello World”工具开始确保部署、连接、调用整个链路畅通。然后再逐步添加参数验证、外部 API 调用、错误处理等复杂逻辑。理解 MCP 协议当遇到深层次问题时翻阅一下 MCP 官方协议文档 会很有帮助。了解工具调用tools/call、列表tools/list等核心接口的定义能帮你更好地理解 SDK 的行为和调试网络请求。5.3 关于成本与限制的考量Cloudflare Workers 免费套餐提供每日 10 万次请求和 10 毫秒 CPU 时间/请求的额度对于个人开发者和中等频率的工具调用完全足够。但如果你构建的工具可能被广泛使用或调用非常频繁需要关注用量仪表板并考虑升级到付费计划。主要的限制在于 CPU 时间。如果你的工具涉及密集计算如大型文本处理、图像处理很容易触发超时限制。对于这类需求可能需要将计算密集型部分卸载到其他服务Worker 仅作为轻量的协调层。最后记住create-mcp是一个追求极致开发速度的脚手架。对于非常复杂、需要复杂状态管理或数据库持久化的 MCP 服务器你可能需要基于其模板进行更大幅度的改造或者考虑使用更传统的服务器框架如 Express.js Node.js来构建 MCP 服务器然后部署到其他平台。但对于绝大多数“将想法快速变成 AI 可用的工具”这一场景它无疑是当前最优雅、最高效的解决方案之一。