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 提交問題或拉取請求。我們期待你的反饋和貢獻！