Xava Labs MCP Template

Xava Labs打字MCP模板

用于为xava labs/typescript代理框架引导MCP（模型上下文协议）的模板存储库。

入门指南

设置存储库

选项A：使用此模板

1. 单击此存储库顶部的“使用此模板”按钮
2. 克隆您的新存储库

选项B：使用部署到cloudflare按钮

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

*注意：配置只需要 npm run deploy 使Deploy命令工作*

选项C：使用cloudflare创建

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

1. 为方便起见，请复制以下文本

xava-labs/mcp-template

1. 运行以下命令，按照交互式提示选择名称，然后从“Template from GitHub repo”开始，然后为要使用的模板粘贴上述文本。

npm create cloudflare@latest  --git https://github.com/xava-labs/mcp-template

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

npm install
npm run dev

以上内容将使用以下网址来增强与无服务器cloudflare兼容的MCP服务器：

• /ws-Websocket连接端点
• SSE 连接终端

特性

• WebSocket客户端支持：包括官方 WebSocket客户端 用于实时双向通信
• SSE客户支持：包括 服务器发送事件客户端 用于服务器到客户端流式传输
• MCP检查员：在开发过程中调试和监控MCP
• Cloudflare员工集成：基于Cloudflare Workers构建边缘计算功能
• 集成测试套件：Websocket和SSE测试工具，用于与本地微眩光服务（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.json添加新更改时都运行此操作）

发展

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

McpHonoServerDO实现

默认情况下，模板使用 McpHonoServerDO 它将MCP服务器与 你好，一个快速轻量级的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自定义路线

使用添加自定义HTTP端点 McpHonoServerDO，延长 setupRoutes 方法：

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

  protected setupRoutes(app: Hono): 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 {
    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. 分叉存储库：创建一个fork来进行更改

1. 创建分支：在新分支中进行更改

   git checkout -b feature/your-feature-name

1. 提交您的更改：做出有意义的承诺

   git commit -m "Add feature: brief description"

1. 推你的叉子：将更改推到叉子上

   git push origin feature/your-feature-name

1. 创建pull请求：打开一个PR，详细描述您的更改

拉取请求指南

• 为你的公关提供一个清晰、描述性的标题
• 包括你的公关工作的详细描述
• 参考任何相关问题
• 包括截图或示例（如适用）
• 确保所有测试通过
• 让PR专注于单个功能或修复

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

或者使用上面的Deploy to Cloudflare按钮直接从GitHub进行部署。

许可证

麻省理工学院