Geelen Workers MCP Server

🚀 Worker MCP Project

This is an MCP (Model Context Protocol) project designed to connect and manage Cloudflare Workers. Through this project, we can integrate Cloudflare Workers into Claude Desktop, enabling the dynamic loading of tools and services.

🚀 Quick Start

Installation

pnpm install

Configuration

Add the following scripts to package.json:

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

✨ Features

Working Principle

1. Documentation Generation: Scan JSDoc comments in src/index.ts to generate a list of tools and services (docs.json).
2. HTTP Handler: Handle calls from Claude at the /rpc endpoint.
3. Local Proxy: Forward MCP requests to remote workers.

Core Components

• WorkerEntrypoint: Defines interfaces and methods within workers.
• RPC: Provides an RPC call interface, supporting both synchronous and asynchronous operations.
• LocalMCPProxy: Handles tool list requests (tools/list) and call requests (tools/call).

📦 Installation

Install Dependencies

pnpm install

Configure Environment Variables

Add the following scripts to package.json:

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

💻 Usage Examples

Basic Usage

Documentation Generation

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

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

Generated documentation:

{
  "MyWorker": {
    "methods": [
      {
        "name": "greet",
        "params": [
          {
            "type": "string",
            "name": "name"
          }
        ],
        "returns": {
          "type": "Promise.<string>",
          "description": "Greeting message"
        }
      }
    ]
  }
}

HTTP Handler

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

Local Proxy

import { MCPProxy } from '@modelcontextprotocol/sdk'

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

proxy.listen(3001)

🔧 Technical Details

Documentation Generation

The documentation is generated by scanning JSDoc comments in src/index.ts.

HTTP Handler

The /rpc endpoint in lib/WorkerMCP.ts handles calls from Claude.

Local Proxy

scripts/local-proxy.ts starts a local proxy server to handle requests from Claude.

📚 Limitations and Deficiencies

1. Documentation Generation: Currently, it only supports generating documentation from src/index.ts.
2. HTTP Requests: Only synchronous requests are supported, and streaming responses are not supported.
3. Error Handling: The error handling mechanism is not yet fully developed.

📈 Future Plans

• Support Remote Development Mode: Allow debugging without redeployment.
• Improve Documentation Generation Tool: Support extracting information from d.ts files and Zod types.
• Implement Notification Mechanism: Respond to notifications of tool list changes to reduce Claude restarts.

🤝 Feedback and Contribution

We welcome you to try out this project! If you have any questions or suggestions, please submit issues or pull requests via GitHub. We look forward to your feedback and contributions!