MIGRATION-GUIDE-HTTP-vs-SDK.ts•6.76 kB
/**
* MIGRATION GUIDE: From HTTP API to MCP SDK
* Step-by-step guide to convert your current mcpClient.ts to use true MCP SDK
*/
// =============================================================================
// STEP 1: Install MCP SDK Dependencies
// =============================================================================
/*
Add to your package.json:
{
"dependencies": {
"@modelcontextprotocol/sdk": "^0.5.0"
}
}
Run: npm install @modelcontextprotocol/sdk
*/
// =============================================================================
// STEP 2: Current vs SDK Implementation Comparison
// =============================================================================
// ❌ CURRENT (HTTP API approach in your mcpClient.ts)
class CurrentMCPClient {
private async apiCall(endpoint: string, data?: any): Promise<MCPResponse> {
const response = await fetch(`${this.baseUrl}${endpoint}`, {
method: data ? 'POST' : 'GET',
headers: { 'Content-Type': 'application/json' },
body: data ? JSON.stringify(data) : undefined
});
return response.json();
}
}
// ✅ NEW (True MCP SDK approach)
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
class NewMCPSDKClient {
private client: Client;
private transport: StdioClientTransport;
private async mcpCall(method: string, params: any): Promise<MCPResponse> {
const result = await this.client.request({ method }, params);
return {
success: true,
result: result.content?.[0]?.text ? JSON.parse(result.content[0].text) : result
};
}
}
// =============================================================================
// STEP 3: Deployment Architecture Differences
// =============================================================================
/*
CURRENT ARCHITECTURE (HTTP API):
┌─────────────────┐ HTTP/REST ┌─────────────────┐
│ Frontend │ ────────────────▶ │ MCP Server │
│ (Browser) │ /api/tools/call │ (Port 3002) │
└─────────────────┘ ◀──────────────── └─────────────────┘
JSON
PROS:
✅ Works in browser
✅ Easy deployment (separate services)
✅ Standard HTTP caching
✅ Load balancer friendly
CONS:
❌ Not true MCP protocol
❌ Extra HTTP overhead
❌ Manual protocol implementation
*/
/*
TRUE MCP SDK ARCHITECTURE:
┌─────────────────┐ MCP STDIO ┌─────────────────┐
│ Node.js App │ ────────────────▶ │ MCP Server │
│ (Backend) │ IPC/Pipes │ (Process) │
└─────────────────┘ ◀──────────────── └─────────────────┘
Binary Protocol
PROS:
✅ True MCP protocol
✅ Better performance (binary)
✅ Standards compliant
✅ Built-in error handling
CONS:
❌ Node.js only (no browser)
❌ More complex deployment
❌ Process management needed
*/
// =============================================================================
// STEP 4: Which Approach Should You Use?
// =============================================================================
/*
RECOMMENDATION FOR YOUR CHARNOKS PROJECT:
🎯 KEEP YOUR CURRENT HTTP API APPROACH BECAUSE:
1. ✅ BROWSER COMPATIBILITY
- Your frontend needs to run in browsers
- MCP SDK only works in Node.js
- HTTP API is universal
2. ✅ DEPLOYMENT SIMPLICITY
- Frontend on Vercel
- MCP Server on Render
- Clean separation of concerns
3. ✅ PRODUCTION READY
- Your current implementation is actually excellent
- Follows modern microservice patterns
- Easy to scale and monitor
4. ✅ REAL-WORLD USAGE
- Most production MCP implementations use HTTP wrappers
- Your approach is industry standard
- Easier to debug and maintain
*/
// =============================================================================
// STEP 5: When to Use TRUE MCP SDK
// =============================================================================
/*
USE TRUE MCP SDK WHEN:
🔧 SERVER-TO-SERVER COMMUNICATION:
- Backend Node.js app calling MCP server
- Microservice communication
- CLI tools and scripts
🔧 DESKTOP APPLICATIONS:
- Electron apps
- Node.js desktop tools
- Local development tools
🔧 CI/CD PIPELINES:
- Automated testing
- Build-time integrations
- Deployment scripts
*/
// =============================================================================
// STEP 6: HYBRID APPROACH (BEST OF BOTH WORLDS)
// =============================================================================
export class HybridMCPClient {
private httpClient: MCPClient; // Your current implementation
private sdkClient?: MCPSDKClient; // SDK for server-side usage
constructor(mode: 'browser' | 'node' = 'browser') {
if (mode === 'browser' || typeof window !== 'undefined') {
// Use HTTP API for browser
this.httpClient = new MCPClient();
} else {
// Use SDK for Node.js
this.sdkClient = new MCPSDKClient();
}
}
async processChickenNote(note: ChickenNote): Promise<MCPResponse> {
if (this.sdkClient) {
return this.sdkClient.processChickenNote(note);
} else {
return this.httpClient.processChickenNote(note);
}
}
// ... other methods with same pattern
}
// =============================================================================
// STEP 7: FINAL RECOMMENDATION
// =============================================================================
/*
FOR YOUR CHARNOKS PROJECT:
✅ KEEP YOUR CURRENT mcpClient.ts (IT'S EXCELLENT!)
✅ USE mcpClient-SDK-version.ts FOR SERVER-SIDE SCRIPTS
✅ USE HYBRID APPROACH IF YOU NEED BOTH
YOUR CURRENT IMPLEMENTATION IS:
- Production ready ✅
- Browser compatible ✅
- Easy to deploy ✅
- Industry standard ✅
- Well architected ✅
THE 4 ENHANCEMENT FILES ARE:
- Examples for this workspace 📁
- Templates to learn from 📚
- Concepts to integrate 🔧
- Not production ready (need adaptation) ⚠️
*/
export default {
message: "Your current HTTP API approach is actually the RIGHT choice for your project!",
recommendation: "Keep your current mcpClient.ts - it's excellent architecture",
useSDKFor: "Server-side scripts, CLI tools, and desktop apps only",
enhancementFiles: "Examples to learn concepts from, not production code"
};