Xava Labs Typescript MCP 模板

这是一个用于启动 xava-labs/typescript-agent-framework 的 MCP（Model Context Protocol）的模板仓库。

开始使用

设置仓库

选项 A: 使用此模板

点击此仓库顶部的“使用此模板”按钮
克隆您的新仓库

选项 B: 使用部署到 Cloudflare 按钮

以下按钮将在您的组织中创建一个新的仓库，并使用 Cloudflare 设置 CI/CD：

注意：配置仅需要 npm run deploy 作为部署命令即可工作

选项 C: 使用 Cloudflare 创建

您可以使用 wrangler 基于此模板创建一个新项目：

复制以下文本以便使用

xava-labs/mcp-template

运行以下命令，按照交互提示选择名称，然后从 "Template from GitHub repo" 开始，并粘贴上述文本以使用所需的模板。 bash npm create cloudflare@latest --git https://github.com/xava-labs/mcp-template

完成上述任一方法后，在终端中运行以下命令以开始：

npm install npm run dev

以上操作将启动一个与 Cloudflare 兼容的无服务器 MCP 服务器，具有以下 URL：

/ws - WebSocket 连接端点
/sse - SSE 连接端点

功能

WebSocket 客户端支持：包括官方 WebSocket 客户端用于实时双向通信
SSE 客户端支持：包括 Server-Sent Events 客户端用于服务器到客户端的流式传输
MCP 检查器：在开发过程中调试和监控您的 MCP
Cloudflare Workers 集成：基于 Cloudflare Workers 构建，提供边缘计算能力
集成测试套件：WebSocket 和 SSE 测试工具，可以与本地 miniflare 服务（D1/KV等）进行完整的集成测试，方便测试功能而无需模拟。

可用脚本

npm run dev: 同时运行 MCP 检查器（端口 6274）和 Cloudflare Worker（端口 8787）
npm start: 仅运行 Cloudflare Worker（端口 8787）
npm test: 使用 Vitest 运行测试
npm run deploy: 将您的 MCP 部署到 Cloudflare Workers
npm run cf-typegen: 为 Cloudflare Workers 生成 TypeScript 类型（每次向 wrangler.jsonc 添加新更改时都应运行）

开发

此模板使用 Durable Objects 实现状态连接的 MCP 服务器。基础项目结构提供了两种主要的方法来扩展功能：

McpHonoServerDO 实现

默认情况下，模板使用 McpHonoServerDO，它将 MCP 服务器与 Hono 结合在一起，Hono 是一个快速且轻量级的 Web 框架。这提供了一个干净的路由系统和中间件功能。

通过工具、资源和提示扩展

主服务器实现位于 src/server.ts 并扩展了 McpHonoServerDO：

typescript export class ExampleMcpServer extends McpHonoServerDO { // 必须实现的抽象方法 getImplementation(): Implementation { return { name: ExampleMcpServer , version: 1.0.0 , }; }

// 通过添加工具、资源和提示来配置服务器 configureServer(server: McpServer): void { setupServerTools(server); setupServerResources(server); setupServerPrompts(server); } }

要添加功能，请使用以下模块：

工具 (src/tools.ts)：定义客户端可以调用的函数

typescript export function setupServerTools(server: McpServer) { server.tool( tool_name , // 工具名称 Tool description , // 工具描述### 1. 工具 (src/tools.ts): 定义客户端可以调用的工具

typescript server.tool( tool_name, { param1: z.string().describe("参数描述"), }, async ({ param1 }) => { // 工具实现 return { content: [ { type: "text", text: 结果: ${param1} } ] }; } );

资源 (src/resources.ts): 定义客户端可以访问的持久化资源

typescript export function setupServerResources(server: McpServer) { server.resource( resource_name, "resource://path/{id}", async (uri: URL) => { // 资源实现 return { contents: [ { text: 资源数据, uri: uri.href } ] }; } ); }

提示 (src/prompts.ts): 定义提示模板

typescript export function setupServerPrompts(server: McpServer) { server.prompt( prompt_name, "提示描述", () => ({ messages: [{ role: "assistant", content: { type: "text", text: 您的提示文本在这里 } }] }) ); }

使用 Hono 自定义路由

要使用 McpHonoServerDO 添加自定义 HTTP 端点，请扩展 setupRoutes 方法：

typescript export class ExampleMcpServer extends McpHonoServerDO { // 其他方法...

protected setupRoutes(app: Hono<{ Bindings: Env }>): void { // 调用父类实现以设置 MCP 路由 super.setupRoutes(app);

// 添加自定义路由
app.get("/api/status", (c) => {
  return c.json({ status: "ok" });
});

app.post("/api/data", async (c) => {
  const body = await c.req.json();
  // 处理数据
  return c.json({ success: true });
});

} }

McpServerDO 实现（原生 Cloudflare 路由）

如果您需要对 HTTP 请求处理有更多控制，可以直接扩展 McpServerDO。这将使您完全控制 fetch 方法：

typescript export class CustomMcpServer extends McpServerDO { // 必须实现的抽象方法 getImplementation(): Implementation { return { name: "CustomMcpServer", version: "1.0.0", }; }

configureServer(server: McpServer): void { setupServerTools(server); setupServerResources(server); setupServerPrompts(server); }

// 重写 fetch 方法以完全控制路由 async fetch(request: Request): Promise { const url = new URL(request.url); const path = url.pathname;

// 处理自定义路由
if (path === "/api/custom") {
  return new Response(JSON.stringify({ custom: true }), {
    headers: { "Content-Type": "application/json" }
  });
}

// 将与 MCP 相关的请求传递给父类实现
return super.fetch(request);

} }

这种方法在以下情况下非常有用：

使用自定义逻辑处理特定路由
实现复杂的中间件或身份验证
在请求到达 MCP 处理程序之前拦截或修改请求
添加超出标准 MCP 实现的自定义 WebSocket 或 SSE 端点

示例

CRUD 待办事项列表示例

有关完整的示例，请参阅 CRUD 待办事项列表 MCP 示例，该示例展示了：

使用 MCP 工具进行完整的 CRUD 操作
集成 SQLite 数据库以实现持久化
通过 WebSocket/SSE 实现实时更新
全面的错误处理
高级过滤和排序功能
丰富的提示和资源

社区

加入我们的社区以获取帮助、分享想法并为项目做出贡献：

Discord：加入 #mcp 频道以提出功能请求、支持和讨论

贡献

我们欢迎贡献来改进此模板！以下是您可以贡献的方式：

分叉仓库：创建一个分叉以进行更改
创建分支：在新分支中进行更改bash git checkout -b feature/your-feature-name
提交你的更改：进行有意义的提交 bash git commit -m "添加功能: 简要描述"
推送到你的分支：将你的更改推送到你的分支 bash git push origin feature/your-feature-name
创建拉取请求：打开一个PR，并详细描述你的更改

拉取请求指南

为你的PR提供清晰、描述性的标题
包含详细的描述，说明你的PR做了什么
引用任何相关的issues
如果适用，包含截图或示例
确保所有测试通过
保持PR专注于单一功能或修复

对于较大的更改或功能，我们建议先在我们的Discord频道中讨论，以确保与项目方向一致。

或者使用上方的“部署到Cloudflare”按钮直接从GitHub部署。

许可证

MIT

来源

来源：github
链接：https://github.com/Disturbing/mcp-live-code

Disturbing