Disturbing
服务介绍
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 Workersnpm 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 实现实时更新
- 全面的错误处理
- 高级过滤和排序功能
- 丰富的提示和资源
相关资源
核心包
- MCP 包：具有高级功能和测试工具的核心 MCP 实现
- TypeScript 代理框架：使用 LLM 构建智能代理
文档
- 文档：即将推出！
社区
加入我们的社区以获取帮助、分享想法并为项目做出贡献：
- 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部署。
