MIGRATION.md•7.49 kB
# Migration Guide: Python to TypeScript/Cloudflare Workers
This document outlines the differences between the original Python implementation and the new TypeScript/Cloudflare Workers implementation.
## Key Improvements
### 1. Language & Runtime
**Before (Python)**
- Python 3.8+
- FastMCP framework
- Local execution only
- Single-threaded async
**After (TypeScript)**
- TypeScript with full type safety
- Cloudflare Workers with edge deployment
- Global low-latency via CDN
- Durable Objects for state management
### 2. Authentication
**Before (Python)**
- No authentication
- Public access
- User ID passed as parameter
**After (TypeScript)**
- Google OAuth 2.0 authentication
- Email-based access control
- HMAC-signed cookies
- User ID still passed as parameter
### 3. Deployment
**Before (Python)**
```bash
python main.py # Local only
```
**After (TypeScript)**
```bash
npm run dev # Local development
npm run deploy # Deploy to Cloudflare Workers globally
```
### 4. Configuration
**Before (Python)**
- `.env` file for configuration
- Environment variables only
**After (TypeScript)**
- `wrangler.toml` for Worker config
- Secrets managed via `wrangler secret`
- `.dev.vars` for local development
- Type-safe environment access
### 5. Code Organization
**Before (Python)**
```
get-simbrief-flight-plan/
├── main.py # Everything in one file
├── requirements.txt
└── README.md
```
**After (TypeScript)**
```
simbrief-mcp/
├── src/
│ ├── auth/ # Authentication logic
│ ├── config/ # Configuration
│ ├── tools/ # API client & tools
│ ├── types/ # TypeScript types
│ └── index.ts # Main entry
├── wrangler.toml
├── tsconfig.json
└── package.json
```
### 6. Type Safety
**Before (Python)**
```python
def get_latest_flight_plan(user_id: str) -> Dict[str, Any]:
# Runtime type checking only
pass
```
**After (TypeScript)**
```typescript
async function getLatestFlightPlan(params: {
userId: string;
}): Promise<ToolResponse> {
// Compile-time type checking
// Zod runtime validation
}
```
### 7. Error Handling
**Before (Python)**
```python
try:
response = await client.get(url)
except Exception as e:
return {"error": str(e), "isError": True}
```
**After (TypeScript)**
```typescript
try {
const response = await fetch(url);
// Handle response
} catch (error) {
// Sentry integration
Sentry.captureException(error);
return {
content: [{
type: "text",
text: `**Error**\n\n${formatError(error)}`,
isError: true
}]
};
}
```
### 8. Monitoring & Observability
**Before (Python)**
- Console logs only
- No error tracking
- No performance monitoring
**After (TypeScript)**
- Cloudflare Analytics built-in
- Optional Sentry integration
- Performance tracing
- Error tracking with event IDs
- User context in errors
### 9. API Integration
**Before (Python)**
```python
import httpx
import ssl
import certifi
def get_ssl_context():
return ssl.create_default_context(cafile=certifi.where())
async with httpx.AsyncClient(verify=get_ssl_context()) as client:
response = await client.get(url, params=params, timeout=30.0)
```
**After (TypeScript)**
```typescript
// Built-in fetch API
const response = await fetch(url.toString(), {
method: "GET",
headers: { "Accept": "application/json" }
});
```
### 10. Tool Registration
**Before (Python)**
```python
@mcp.tool()
async def get_latest_flight_plan(user_id: str) -> Dict[str, Any]:
"""Get latest flight plan"""
pass
```
**After (TypeScript)**
```typescript
server.tool(
"getLatestFlightPlan",
"Get the complete JSON data for the latest SimBrief flight plan",
GetLatestFlightPlanSchema, // Zod schema for validation
wrapWithSentry("getLatestFlightPlan", async ({ userId }) => {
// Implementation with Sentry tracking
})
);
```
## Breaking Changes
### Tool Names
Python (snake_case) → TypeScript (camelCase)
- `get_latest_flight_plan` → `getLatestFlightPlan`
- `get_latest_flight_plan_full` → `getLatestFlightPlan`
- `get_flight_plan_by_id` → `getFlightPlanByIdSummary`
- `get_flight_plan_by_id_full` → `getFlightPlanById`
- `get_dispatch_briefing` → `getDispatchBriefing`
### Configuration
**Before:**
```env
SIMBRIEF_API_KEY=your-key
```
**After:**
```bash
wrangler secret put SIMBRIEF_API_KEY
wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY
```
### Access Control
**Before:**
- No authentication required
- Anyone can use the server
**After:**
- Google OAuth required
- Email-based allowlist in `src/config/allowed-users.ts`
## Migration Steps
### 1. Set Up Cloudflare Account
```bash
# Install Wrangler CLI
npm install -g wrangler
# Login to Cloudflare
wrangler login
```
### 2. Create KV Namespace
```bash
wrangler kv:namespace create OAUTH_KV
# Copy the namespace ID to wrangler.toml
```
### 3. Set Up Google OAuth
1. Go to Google Cloud Console
2. Create OAuth 2.0 credentials
3. Add authorized redirect URIs:
- `http://localhost:8792/callback` (development)
- `https://your-worker.workers.dev/callback` (production)
### 4. Configure Secrets
```bash
wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY
wrangler secret put SIMBRIEF_API_KEY # Optional
```
### 5. Configure Allowed Users
Edit `src/config/allowed-users.ts`:
```typescript
const ALLOWED_USERNAMES = new Set<string>([
'your-email-username', // Part before @ in email
]);
```
### 6. Deploy
```bash
npm run deploy
```
### 7. Update Claude Desktop Config
**Before:**
```json
{
"mcpServers": {
"simbrief": {
"command": "python",
"args": ["/path/to/main.py"]
}
}
}
```
**After:**
```json
{
"mcpServers": {
"simbrief": {
"command": "npx",
"args": ["mcp-remote", "https://your-worker.workers.dev/mcp"]
}
}
}
```
## Performance Comparison
| Metric | Python (Local) | TypeScript (Cloudflare) |
|--------|---------------|------------------------|
| Cold Start | ~500ms | ~50ms |
| Latency (US) | ~10ms | ~5ms |
| Latency (EU) | ~150ms | ~5ms |
| Latency (APAC) | ~300ms | ~5ms |
| Scalability | Single machine | Global CDN |
| Availability | Single point | 99.99% SLA |
## Feature Comparison
| Feature | Python | TypeScript |
|---------|--------|-----------|
| Authentication | ❌ | ✅ Google OAuth |
| Type Safety | Partial | ✅ Full |
| Error Tracking | ❌ | ✅ Sentry |
| Analytics | ❌ | ✅ Cloudflare |
| Global Deploy | ❌ | ✅ Edge network |
| Access Control | ❌ | ✅ Email-based |
| Rate Limits | Standard | ✅ API key support |
| Monitoring | Logs only | ✅ Full observability |
## Backward Compatibility
The new implementation maintains compatibility with the SimBrief API but requires:
1. **Authentication**: Users must authenticate via Google OAuth
2. **Tool Names**: Use camelCase instead of snake_case
3. **Configuration**: Use Cloudflare secrets instead of .env
## Rollback Strategy
To rollback to Python version:
1. Keep the old `get-simbrief-flight-plan` directory
2. Update Claude Desktop config to point to Python version
3. No changes needed on SimBrief side
## Support
For migration assistance:
- Review the README.md for setup instructions
- Check CLAUDE.md for implementation details
- Review Cloudflare Workers logs for debugging