Xava Labs Typescript MCP 模板

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

开始使用

设置仓库

选项 A: 使用此模板

1. 点击此仓库顶部的“使用此模板”按钮
2. 克隆你的新仓库

选项 B: 使用 wrangler init

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

npx wrangler init my-mcp-project --git https://github.com/xava-labs/mcp-template
cd my-mcp-project

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

yarn install
yarn 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/等）进行全面集成测试，无需模拟即可轻松测试功能。

可用脚本

• yarn dev：同时运行 MCP 检查器（端口 6274）和 Cloudflare Worker（端口 8787）
• yarn start：仅运行 Cloudflare Worker（端口 8787）
• yarn test：使用 Vitest 运行测试
• yarn deploy：将你的 MCP 部署到 Cloudflare Workers
• yarn cf-typegen：为 Cloudflare Workers 生成 TypeScript 类型（每次修改 wrangler.jsonc 时都需要运行）

开发

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

McpHonoServerDO 实现

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

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

主服务器实现在 src/server.ts 中，并扩展了 McpHonoServerDO：

export class ExampleMcpServer extends McpHonoServerDO {
  // Required abstract method implementation
  getImplementation(): Implementation {
    return {
      name: 'ExampleMcpServer',
      version: '1.0.0',
    };
  }

  // Configure server by adding tools, resources, and prompts
  configureServer(server: McpServer): void {
    setupServerTools(server);
    setupServerResources(server);
    setupServerPrompts(server);
  }
}

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

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

export function setupServerTools(server: McpServer) {
  server.tool(
    'tool_name',           // Name of the tool
    'Tool description',    // Description
    {                      // Parameters schema using zod
      param1: z.string().describe('Parameter description'),
    },       
    async ({ param1 }) => {
      // Tool implementation
      return {
        content: [
          {
            type: "text",
            text: `Result: ${param1}`
          }
        ]
      };
    }
  );
}

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

export function setupServerResources(server: McpServer) {
  server.resource(
    'resource_name',
    'resource://path/{id}',
    async (uri: URL) => {
      // Resource implementation
      return {
        contents: [
          {
            text: `Resource data`,
            uri: uri.href
          }
        ]
      };
    }
  );
}

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

export function setupServerPrompts(server: McpServer) {
  server.prompt(
    'prompt_name',
    'Prompt description',
    () => ({
      messages: [{
        role: 'assistant',
        content: {
          type: 'text',
          text: `Your prompt text here`
        }
      }]
    })
  );
}

使用 Hono 自定义路由

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

export class ExampleMcpServer extends McpHonoServerDO {
  // Other methods...

  protected setupRoutes(app: Hono<{ Bindings: Env }>): void {
    // Call the parent implementation to set up MCP routes
    super.setupRoutes(app);
    
    // Add your custom routes
    app.get('/api/status', (c) => {
      return c.json({ status: 'ok' });
    });
    
    app.post('/api/data', async (c) => {
      const body = await c.req.json();
      // Process data
      return c.json({ success: true });
    });
  }
}

McpServerDO 实现（原生 Cloudflare 路由）

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

export class CustomMcpServer extends McpServerDO {
  // Required abstract method implementations
  getImplementation(): Implementation {
    return {
      name: 'CustomMcpServer',
      version: '1.0.0',
    };
  }
  
  configureServer(server: McpServer): void {
    setupServerTools(server);
    setupServerResources(server);
    setupServerPrompts(server);
  }
  
  // Override the fetch method for complete control over routing
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname;
    
    // Handle custom routes
    if (path === '/api/custom') {
      return new Response(JSON.stringify({ custom: true }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }
    
    // Pass through MCP-related requests to the parent implementation
    return super.fetch(request);
  }
}

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

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

示例

CRUD 待办事项列表示例

对于一个完整的可运行示例，请查看 CRUD 待办事项列表 MCP 示例，该示例展示了：

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

相关资源

核心包

• MCP 包：具有高级特性和测试工具的核心 MCP 实现
• TypeScript 代理框架：使用代理框架构建基于 LLM 的智能代理

文档

• 文档：即将推出！

社区

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

• Discord：加入 #mcp 频道，提出功能请求、获得支持并参与讨论

贡献

我们欢迎改进此模板的贡献！以下是您如何贡献的方法：

1. 分叉仓库：创建一个分叉来进行您的更改

2. 创建分支：在新分支中进行您的更改

   git checkout -b feature/your-feature-name
   

3. 提交您的更改：进行有意义的提交

   git commit -m "Add feature: brief description"
   

4. 推送到您的分叉：将您的更改推送到您的分叉

   git push origin feature/your-feature-name
   

5. 创建拉取请求：打开一个 PR，并详细描述您的更改

拉取请求指南

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

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

部署

要将您的 MCP 部署到 Cloudflare Workers，请运行：

yarn deploy

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

许可证

MIT