geelen_workers-mcp-server

🚀 工作者 MCP 项目

本项目是用于连接和管理 Cloudflare Workers 的 MCP（Model Context Protocol）项目，可将 Cloudflare Workers 集成到 Claude Desktop 中，实现工具和服务的动态加载。

🚀 快速开始

安装依赖

pnpm install

配置环境变量

在 package.json 中添加以下脚本：

{
  "scripts": {
    "generate:docs": "ts-mdx src/index.ts -o docs.json",
    "watch-docs": "watchexec npm run generate:docs"
  }
}

✨ 主要特性

工作原理

1. 文档生成：通过扫描 src/index.ts 中的 JSDoc 注释，生成工具和服务列表 (docs.json)。
2. HTTP 处理器：在 /rpc 接口处理来自 Claude 的调用请求。
3. 本地代理：将 MCP 请求转发到远程工作者。

核心组件

• WorkerEntrypoint：定义了 workers 中的接口和方法。
• RPC：提供 RPC 调用接口，支持同步和异步操作。
• LocalMCPProxy：处理工具列表请求 (tools/list) 和调用请求 (tools/call)。

📦 安装指南

安装依赖

pnpm install

配置环境变量

在 package.json 中添加以下脚本：

{
  "scripts": {
    "generate:docs": "ts-mdx src/index.ts -o docs.json",
    "watch-docs": "watchexec npm run generate:docs"
  }
}

💻 使用示例

基础用法

文档生成

import type { WorkerEntrypoint } from '@modelcontextprotocol/types'

export class MyWorker implements WorkerEntrypoint {
  async greet(name: string) {
    return `Hello, ${name}!`
  }
}

生成的文档：

{
  "MyWorker": {
    "methods": [
      {
        "name": "greet",
        "params": [
          {
            "type": "string",
            "name": "name"
          }
        ],
        "returns": {
          "type": "Promise.<string>",
          "description": "问候消息"
        }
      }
    ]
  }
}

HTTP 处理器

lib/WorkerMCP.ts 提供 /rpc 接口：

export default function workerMcp() {
  return new Response(`Hello from WorkerMCP!`, {
    headers: { 'content-type': 'application/json' },
  });
}

本地代理

scripts/local-proxy.ts 启动本地代理服务器，处理 Claude 的请求：

import { MCPProxy } from '@modelcontextprotocol/sdk'

const proxy = new MCPProxy({
  entrypoint: 'my-worker',
  workerUrl: 'https://your.worker.url'
});

proxy.listen(3001)

📚 详细文档

目录结构

worker-mcp/
  ├── src/                 # 工作者入口文件
  |    └── index.ts        # 主要工作者逻辑
  ├── lib/                # 公共 HTTP 处理器
  |    └── WorkerMCP.ts   # 提供 `/rpc` 接口
  ├── scripts/           # 脚本和工具
  |    ├── local-proxy.ts # 本地 MCP 代理
  |    └── generate-docs.ts # 文档生成工具
  └── package.json       # 项目依赖和脚本配置

🔧 技术细节

文档生成

目前仅支持从 src/index.ts 生成文档，通过扫描该文件中的 JSDoc 注释，生成工具和服务列表 (docs.json)。示例代码如下：

import type { WorkerEntrypoint } from '@modelcontextprotocol/types'

export class MyWorker implements WorkerEntrypoint {
  async greet(name: string) {
    return `Hello, ${name}!`
  }
}

生成的文档：

{
  "MyWorker": {
    "methods": [
      {
        "name": "greet",
        "params": [
          {
            "type": "string",
            "name": "name"
          }
        ],
        "returns": {
          "type": "Promise.<string>",
          "description": "问候消息"
        }
      }
    ]
  }
}

HTTP 处理器

lib/WorkerMCP.ts 提供 /rpc 接口，用于处理来自 Claude 的调用请求，示例代码如下：

export default function workerMcp() {
  return new Response(`Hello from WorkerMCP!`, {
    headers: { 'content-type': 'application/json' },
  });
}

本地代理

scripts/local-proxy.ts 启动本地代理服务器，将 MCP 请求转发到远程工作者，处理 Claude 的请求，示例代码如下：

import { MCPProxy } from '@modelcontextprotocol/sdk'

const proxy = new MCPProxy({
  entrypoint: 'my-worker',
  workerUrl: 'https://your.worker.url'
});

proxy.listen(3001)

⚠️ 限制与不足

1. 文档生成：目前仅支持从 src/index.ts 生成文档。
2. HTTP 请求：仅支持同步请求，不支持流式响应。
3. 错误处理：尚未完善错误处理机制。

🚀 未来规划

• 支持远程开发模式：允许在不重新部署的情况下进行调试。
• 改进文档生成工具：支持从 d.ts 文件和 Zod 类型中提取信息。
• 实现通知机制：响应工具列表变化的通知，减少 Claude 的重启次数。

🤝 反馈与贡献

欢迎尝试本项目！如果有任何问题或建议，请通过 GitHub 提交问题或拉取请求。我们期待你的反馈和贡献！