BestReads

BestReads is a remote MCP server built on Cloudflare Workers that provides personalized book recommendations. It uses the Agents SDK to implement the MCP surface, Durable Objects to persist user reading preferences, and Workers AI to generate tailored suggestions. Authentication is integrated via GitHub using Cloudflare's OAuth provider, enabling users to sign in and have their reading history, preferences, and preferences stored securely. The server supports two transport methods for MCP clients: Server-Sent Events (SSE) for real-time updates and the Streamable HTTP (mcp) transport for chunked responses. To try it quickly, you can access the SSE endpoint at https://bestreads.dinas.workers.dev/sse or the Streamable HTTP endpoint at https://bestreads.dinas.workers.dev/mcp if your client supports it.

Prerequisites:

• Node.js and npm installed on your machine
• Wrangler CLI installed and configured for Cloudflare Workers
• A GitHub OAuth App created to enable GitHub login

1. Clone the repository git clone <your-repo-url> cd bestreads-mcp-server

2. Install dependencies npm install

3. Configure OAuth and encryption keys

   • Create a GitHub OAuth App and set the Authorization callback URL to https://your-worker-domain.workers.dev/callback
   • In Wrangler configuration (wrangler.toml), set: GITHUB_CLIENT_ID = your_github_client_id GITHUB_CLIENT_SECRET = your_github_client_secret COOKIE_ENCRYPTION_KEY = a_32_byte_hex_key
   • (Optional) Create a KV namespace and Durable Object bindings as described in the README: [[kv_namespaces]] binding = "OAUTH_KV" id = "your_kv_namespace_id" [[durable_objects.bindings]] name = "MCP_OBJECT" class_name = "MyMCP" [[durable_objects.bindings]] name = "USER_BOOK_PREFERENCES" class_name = "UserBookPreferences"

4. Deploy to Cloudflare Workers wrangler deploy

5. Access the server endpoints

   • SSE: https://your-worker-domain.workers.dev/sse
   • MCP: https://your-worker-domain.workers.dev/mcp

Tips:

• Ensure your Wrangler configuration matches your Cloudflare account and the OAuth app settings.
• If you encounter issues with authentication, verify the OAuth redirect URL and ensure the GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are correctly set.
• The Durable Objects names (e.g., MCP_OBJECT and USER_BOOK_PREFERENCES) must be bound in wrangler.toml as shown in the README to persist user preferences.
• The COOKIE_ENCRYPTION_KEY must be exactly 32 bytes (256 bits) in hex.
• The MCP server supports both SSE and mcp transports. Choose the transport that matches your MCP client capabilities.
• If you are not deploying, you can still test by using the provided example endpoints if the worker is already deployed.