espocrm-graphql-server/deploy/cloudflare/README.md

A modern GraphQL server for EspoCRM with TypeScript, MCP integration, and AI-optimized dynamic schema generation

# Deploy EspoCRM MCP Server to Cloudflare Workers

This guide explains how to deploy the EspoCRM MCP server as a remote, internet-accessible service on Cloudflare Workers.

## Prerequisites

1. **Cloudflare Account**: Sign up at [cloudflare.com](https://cloudflare.com)
2. **Wrangler CLI**: Install Cloudflare's CLI tool
   ```bash
   npm install -g wrangler
   ```
3. **GraphQL Server**: Your EspoCRM GraphQL server must be accessible from the internet

## Setup Instructions

### 1. Initialize Project

```bash
# Clone or create project directory
mkdir espocrm-mcp-cloudflare
cd espocrm-mcp-cloudflare

# Copy the deployment files
cp -r /path/to/espocrm-graphql-server/deploy/cloudflare/* .

# Install dependencies
npm init -y
npm install @cloudflare/mcp-agent
```

### 2. Configure Wrangler

Edit `wrangler.toml` with your settings:

```toml
name = "espocrm-mcp-server"
main = "src/index.ts"
compatibility_date = "2024-12-01"

[vars]
MCP_GRAPHQL_ENDPOINT = "https://your-graphql-server.com/graphql"
```

### 3. Create KV Namespace

Create a KV namespace for caching:

```bash
wrangler kv:namespace create "MCP_CACHE"
```

Add the generated ID to `wrangler.toml`:

```toml
[[kv_namespaces]]
binding = "MCP_CACHE"
id = "your-generated-kv-id"
```

### 4. Set API Key Secret

```bash
wrangler secret put MCP_API_KEY
# Enter your GraphQL API key when prompted
```

### 5. Deploy to Cloudflare

```bash
# Deploy to production
wrangler deploy

# Or deploy to preview
wrangler deploy --env preview
```

Your MCP server will be available at:
```
https://espocrm-mcp-server.<your-subdomain>.workers.dev
```

## Authentication Options

### Option 1: Simple API Key (Default)

The basic template uses API key authentication passed via the MCP client.

### Option 2: OAuth Integration

For production use with multiple users, implement OAuth:

```typescript
import { workersOAuthProvider } from 'workers-oauth-provider';

// Wrap your agent with OAuth
export default workersOAuthProvider(EspoCRMMcpAgent, {
  clientId: env.OAUTH_CLIENT_ID,
  clientSecret: env.OAUTH_CLIENT_SECRET,
  redirectUri: 'https://your-worker.workers.dev/oauth/callback',
});
```

## Testing the Deployment

### 1. Test with MCP Inspector

```bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector

# Enter your Worker URL: https://espocrm-mcp-server.workers.dev/mcp
```

### 2. Test with curl

```bash
# Test health endpoint
curl https://espocrm-mcp-server.workers.dev/

# Test with MCP client
curl -X POST https://espocrm-mcp-server.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "list_tools"}'
```

## Connect from Claude Desktop

### For Remote MCP Server

1. Install the MCP remote adapter:
   ```bash
   npm install -g mcp-remote
   ```

2. Configure Claude Desktop:
   ```json
   {
     "mcpServers": {
       "espocrm-remote": {
         "command": "mcp-remote",
         "args": ["https://espocrm-mcp-server.workers.dev/mcp"],
         "env": {
           "MCP_API_KEY": "your-api-key"
         }
       }
     }
   }
   ```

## Transport Options

The Cloudflare Worker supports two transport methods:

### 1. Streamable HTTP (Recommended)
- Endpoint: `/mcp`
- Single HTTP endpoint for bidirectional messaging
- Better performance and simpler implementation

### 2. Server-Sent Events (SSE)
- Endpoint: `/sse`
- Legacy transport for backward compatibility
- Will be deprecated in future versions

## Performance Optimization

### Caching Strategy

The Worker implements KV caching:
- Tool results cached for 5 minutes
- Schema information cached for 30 minutes
- Automatic cache invalidation on updates

### Edge Locations

Cloudflare Workers run at edge locations worldwide, providing:
- Low latency for global users
- Automatic scaling
- DDoS protection

## Monitoring

### Cloudflare Analytics

Monitor your MCP server performance:
1. Go to Cloudflare Dashboard
2. Select your Worker
3. View metrics:
   - Request count
   - CPU time
   - Errors
   - Response times

### Custom Logging

Add logging with Wrangler:

```bash
# View real-time logs
wrangler tail

# View logs for specific deployment
wrangler tail --env production
```

## Security Best Practices

1. **API Key Rotation**: Regularly rotate API keys
2. **Rate Limiting**: Configure Cloudflare rate limiting rules
3. **IP Allowlisting**: Restrict access to known AI assistant IPs
4. **CORS Headers**: Configure appropriate CORS policies
5. **Request Validation**: Validate all incoming requests

## Troubleshooting

### Worker Not Responding
- Check deployment status: `wrangler deployments list`
- View logs: `wrangler tail`
- Verify KV namespace binding

### Authentication Failures
- Verify API key is set: `wrangler secret list`
- Check GraphQL endpoint accessibility
- Validate CORS headers

### Performance Issues
- Monitor CPU time in Cloudflare Dashboard
- Increase cache TTL for frequently accessed data
- Consider upgrading to Cloudflare Workers Paid plan

## Cost Considerations

### Free Tier Limits
- 100,000 requests/day
- 10ms CPU time per request
- 1MB worker size

### Paid Plan Benefits
- Unlimited requests
- 50ms CPU time per request
- 10MB worker size
- Advanced analytics

## Advanced Configuration

### Multi-Region Deployment

Deploy to specific regions for compliance:

```toml
[env.eu]
vars = { REGION = "EU" }
routes = [
  { pattern = "eu.espocrm-mcp.com/*", zone_name = "espocrm-mcp.com" }
]

[env.us]
vars = { REGION = "US" }
routes = [
  { pattern = "us.espocrm-mcp.com/*", zone_name = "espocrm-mcp.com" }
]
```

### Custom Domain

Add a custom domain:

```bash
# Add route to worker
wrangler routes add mcp.yourdomain.com/* --zone yourdomain.com
```

## Support

- [Cloudflare Workers Documentation](https://developers.cloudflare.com/workers/)
- [MCP Documentation](https://modelcontextprotocol.io)
- [GitHub Issues](https://github.com/your-org/espocrm-graphql-server/issues)