Merge pull request #270 from deploystackio/feat/sdk-typescript

Feat/sdk typescript

Author: Lasim

development/satellite/architecture.mdx

@@ -24,29 +24,29 @@ Satellites operate as edge workers similar to GitHub Actions runners, providing:
 
 ## Current Implementation Architecture
 
-### Phase 1: MCP Transport Layer
+### MCP SDK Transport Layer
 
-The current satellite implementation provides complete MCP client interface support:
+The satellite uses the official `@modelcontextprotocol/sdk` for all MCP client communication:
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────────┐
-│                        MCP Transport Implementation                             │
+│                        Official MCP SDK Implementation                         │
 │                                                                                 │
-│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐           │
-│  │  SSE Transport  │    │ SSE Messaging   │    │ Streamable HTTP │           │
-│  │                 │    │                 │    │                 │           │
-│  │ • GET /sse      │    │ • POST /message │    │ • GET/POST /mcp │           │
-│  │ • Session Mgmt  │    │ • JSON-RPC 2.0  │    │ • Optional SSE  │           │
-│  │ • 30min timeout │    │ • Session-based │    │ • CORS Support  │           │
-│  └─────────────────┘    └─────────────────┘    └─────────────────┘           │
+│  ┌─────────────────────────────────────────────────────────────────────────┐   │
+│  │                        MCP SDK Server                                   │   │
+│  │                                                                         │   │
+│  │  • StreamableHTTPServerTransport    • Standard JSON-RPC handling       │   │
+│  │  • Automatic session management     • Built-in error responses         │   │
+│  │  • Protocol 2025-03-26 compliance   • SSE streaming support            │   │
+│  └─────────────────────────────────────────────────────────────────────────┘   │
 │                                                                                 │
-│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐           │
-│  │ Session Manager │    │   SSE Handler   │    │ Streamable HTTP │           │
-│  │                 │    │                 │    │    Handler      │           │
-│  │ • 32-byte IDs   │    │ • Connection    │    │ • Dual Response │           │
-│  │ • Activity      │    │   Management    │    │ • Session Aware │           │
-│  │ • Auto Cleanup  │    │ • Message Send  │    │ • Error Handle  │           │
-│  └─────────────────┘    └─────────────────┘    └─────────────────┘           │
+│  ┌─────────────────────────────────────────────────────────────────────────┐   │
+│  │                     MCP Client Integration                              │   │
+│  │                                                                         │   │
+│  │  • StreamableHTTPClientTransport    • External server discovery        │   │
+│  │  • Automatic connection cleanup     • Tool discovery caching           │   │
+│  │  • Standard MCP method support      • Process communication            │   │
+│  └─────────────────────────────────────────────────────────────────────────┘   │
 │                                                                                 │
 │  ┌─────────────────────────────────────────────────────────────────────────┐   │
 │  │                    Foundation Infrastructure                            │   │
@@ -59,66 +59,58 @@ The current satellite implementation provides complete MCP client interface supp
 └─────────────────────────────────────────────────────────────────────────────────┘
 ```
 
-### Current MCP Transport Endpoints
+### MCP Transport Endpoints
 
-**Implemented Endpoints:**
-- `GET /sse` - Establish SSE connection with session management
-- `POST /message?session={id}` - Send JSON-RPC messages via SSE sessions
-- `GET /mcp` - Establish SSE stream for Streamable HTTP transport
-- `POST /mcp` - Send JSON-RPC messages via Streamable HTTP
-- `OPTIONS /mcp` - CORS preflight handling
+**Active Endpoints:**
+- `GET /mcp` - Establish SSE stream via MCP SDK
+- `POST /mcp` - Send JSON-RPC messages via MCP SDK  
+- `DELETE /mcp` - Session termination via MCP SDK
 
 **Transport Protocol Support:**
 ```
-MCP Client                    Satellite
+MCP Client                    Satellite (MCP SDK)
     │                            │
-    │──── GET /sse ─────────────▶│  (Establish SSE session)
+    │──── POST /mcp ────────────▶│  (Initialize connection)
     │                            │
-    │◀─── Session URL ──────────│  (Return session endpoint)
+    │◀─── Session headers ──────│  (Session established)
     │                            │
-    │──── POST /message ────────▶│  (Send JSON-RPC via session)
+    │──── POST /mcp ────────────▶│  (JSON-RPC tools/list)
     │                            │
-    │◀─── Response via SSE ─────│  (Stream response back)
+    │◀─── Tools response ───────│  (Cached tools returned)
 ```
 
-### Core Components
-
-**Session Manager:**
-- Cryptographically secure 32-byte base64url session IDs
-- 30-minute session timeout with automatic cleanup
-- Activity tracking and session state management
-- Client info storage and MCP initialization tracking
+### Core SDK Components
 
-**SSE Handler:**
-- Server-Sent Events connection establishment
-- Message sending with error handling
-- Heartbeat and endpoint event management
-- Connection lifecycle management
+**MCP Server Wrapper:**
+- Official SDK Server integration with Fastify
+- Standard MCP protocol method handlers
+- Automatic session and transport management
+- Integration with existing tool discovery and process management
 
-**Streamable HTTP Handler:**
-- Dual response mode (JSON and SSE streaming)
-- Optional session-based communication
-- CORS preflight handling
-- Error counting and session management
+**Client Communication:**
+- StreamableHTTPClientTransport for external server communication
+- Automatic connection establishment and cleanup
+- Standard MCP method execution (listTools, callTool)
+- Built-in error handling and retry logic
 
-### JSON-RPC 2.0 Protocol Implementation
+### MCP Protocol Implementation
 
 **Supported MCP Methods:**
-- `initialize` - MCP session initialization
+- `initialize` - MCP session initialization (SDK automatic)
 - `notifications/initialized` - Client initialization complete
-- `tools/list` - List available tools from remote MCP servers
-- `tools/call` - Execute tools on remote MCP servers
+- `tools/list` - List cached tools from discovered servers
+- `tools/call` - Execute tools routed to appropriate servers
 - `resources/list` - List available resources (returns empty array)
 - `resources/templates/list` - List resource templates (returns empty array)
 - `prompts/list` - List available prompts (returns empty array)
 
 For detailed information about tool discovery and execution, see [Tool Discovery Implementation](/development/satellite/tool-discovery).
 
 **Error Handling:**
-- JSON-RPC 2.0 compliant error responses
-- HTTP status code mapping
-- Structured error logging
-- Session validation and error reporting
+- Standard JSON-RPC 2.0 compliant error responses via SDK
+- Automatic HTTP status code mapping
+- Structured error logging with operation tracking
+- Built-in session validation and error reporting
 
 ## Planned Full Architecture
 
@@ -414,18 +406,18 @@ npm run dev
 
 **Test MCP Transport:**
 ```bash
-# Test SSE connection
-curl -N -H "Accept: text/event-stream" http://localhost:3001/sse
-
-# Send JSON-RPC message (replace SESSION_ID)
-curl -X POST "http://localhost:3001/message?session=SESSION_ID" \
+# Test MCP connection
+curl -X POST "http://localhost:3001/mcp" \
   -H "Content-Type: application/json" \
   -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'
 
-# Direct HTTP transport
-curl -X POST http://localhost:3001/mcp \
+# Test tool discovery
+curl -X POST "http://localhost:3001/mcp" \
   -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'
+  -d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}'
+
+# Test SSE streaming
+curl -N -H "Accept: text/event-stream" "http://localhost:3001/mcp"
 ```
 
 **MCP Client Configuration:**
@@ -436,7 +428,7 @@ curl -X POST http://localhost:3001/mcp \
       "command": "npx",
       "args": ["@modelcontextprotocol/server-fetch"],
       "env": {
-        "MCP_SERVER_URL": "http://localhost:3001/sse"
+        "MCP_SERVER_URL": "http://localhost:3001/mcp"
       }
     }
   }

development/satellite/mcp-transport.mdx

@@ -1,93 +1,41 @@
 ---
 title: MCP Transport Protocols
-description: External communication endpoints for MCP client integration
+description: Official MCP SDK transport implementation for external client integration
 ---
 
 # MCP Transport Protocols
 
-Satellite implements three MCP transport protocols for external client communication. Each protocol serves different use cases and client requirements.
+Satellite uses the official `@modelcontextprotocol/sdk` to provide MCP client communication. This ensures full protocol compliance and seamless compatibility with all MCP clients including VS Code, Claude, and MCP Inspector.
 
 ## Transport Overview
 
-| Protocol | Endpoint | Method | Use Case |
-|----------|----------|--------|---------|
-| SSE Transport | `/sse` | GET | Persistent connections with session management |
-| SSE Messaging | `/message` | POST | JSON-RPC message sending via established sessions |
-| Streamable HTTP | `/mcp` | GET/POST | Direct HTTP communication with optional streaming |
+| Protocol | Endpoint | Method | Use Case | Implementation |
+|----------|----------|--------|----------|---------------|
+| Streamable HTTP | `/mcp` | POST | Standard JSON-RPC communication | Official MCP SDK |
+| SSE Streaming | `/mcp` | GET | Server-sent events for real-time updates | Official MCP SDK |
+| Session Management | `/mcp` | DELETE | Session termination | Official MCP SDK |
 
-## SSE Transport
+## MCP SDK Implementation
 
-### Connection Establishment
+Satellite leverages the official MCP TypeScript SDK for all transport operations:
 
-**Endpoint:** `GET /sse`
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
-**Headers:**
-- `Accept: text/event-stream` (required)
-- `Cache-Control: no-cache`
-- `Connection: keep-alive`
-
-**Response:**
-- Content-Type: `text/event-stream`
-- Session ID and endpoint URL sent as SSE events
-- 30-minute session timeout with automatic cleanup
-
-**Example:**
-```bash
-curl -N -H "Accept: text/event-stream" http://localhost:3001/sse
-```
-
-**SSE Events:**
-```
-event: endpoint
-data: {"url": "http://localhost:3001/message?session=abc123..."}
-
-event: heartbeat
-data: {"timestamp": "2025-01-09T13:30:00.000Z"}
+const server = new Server({
+  name: 'deploystack-satellite',
+  version: '1.0.0'
+});
 ```
 
 ### Session Management
 
-- **Session ID:** 32-byte cryptographically secure base64url identifier
-- **Timeout:** 30 minutes of inactivity
-- **Activity Tracking:** Updated on each message received
-- **Cleanup:** Automatic removal of expired sessions
-
-## SSE Messaging
-
-**Endpoint:** `POST /message?session={sessionId}`
-
-**Headers:**
-- `Content-Type: application/json` (required)
-
-**Request Body:** JSON-RPC 2.0 message
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "req-1",
-  "method": "initialize",
-  "params": {
-    "clientInfo": {
-      "name": "my-client",
-      "version": "1.0.0"
-    }
-  }
-}
-```
-
-**Response:** Message processing status
-```json
-{
-  "status": "sent",
-  "messageId": "req-1"
-}
-```
-
-**Status Codes:**
-- `200` - Message sent successfully
-- `202` - Message accepted (for notifications)
-- `400` - Invalid JSON-RPC or missing session
-- `404` - Session not found
-- `500` - Internal server error
+The SDK provides automatic session management with:
+- **Session ID:** Cryptographically secure identifiers
+- **Timeout:** Configurable session timeouts  
+- **Activity Tracking:** Automatic session activity updates
+- **Cleanup:** Built-in session cleanup and resource management
 
 ## Streamable HTTP Transport
 
@@ -167,33 +115,31 @@ For detailed information about tool discovery and execution, see [Tool Discovery
 
 ### MCP Client Configuration
 
-**SSE Transport Example:**
+**Standard Configuration:**
 ```json
 {
   "mcpServers": {
     "satellite": {
       "command": "npx",
       "args": ["@modelcontextprotocol/server-fetch"],
       "env": {
-        "MCP_SERVER_URL": "http://localhost:3001/sse"
+        "MCP_SERVER_URL": "http://localhost:3001/mcp"
       }
     }
   }
 }
 ```
 
-**Direct HTTP Example:**
+**VS Code Configuration:**
 ```json
 {
-  "mcpServers": {
-    "satellite": {
-      "command": "npx",
-      "args": ["@modelcontextprotocol/server-fetch"],
-      "env": {
-        "MCP_SERVER_URL": "http://localhost:3001/mcp"
-      }
+  "servers": {
+    "deploystack-satellite": {
+      "url": "http://localhost:3001/mcp",
+      "type": "http"
     }
-  }
+  },
+  "inputs": []
 }
 ```
 
@@ -207,29 +153,27 @@ For detailed information about tool discovery and execution, see [Tool Discovery
    npm run dev
    ```
 
-2. **Test SSE Connection:**
+2. **Test MCP Connection:**
    ```bash
-   curl -N -H "Accept: text/event-stream" http://localhost:3001/sse
+   curl -X POST "http://localhost:3001/mcp" \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'
    ```
 
-3. **Send JSON-RPC Message:**
+3. **Test Tools Discovery:**
    ```bash
-   curl -X POST "http://localhost:3001/message?session=YOUR_SESSION_ID" \
+   curl -X POST "http://localhost:3001/mcp" \
      -H "Content-Type: application/json" \
-     -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'
+     -d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}'
    ```
 
-### Protocol Selection
-
-**Use SSE Transport when:**
-- Long-lived connections needed
-- Session state management required
-- Real-time bidirectional communication
+### Protocol Features
 
-**Use Streamable HTTP when:**
-- Stateless request/response patterns
-- Standard HTTP client libraries
-- Optional streaming responses
+The official MCP SDK provides:
+- **Automatic Session Management:** Sessions created and managed transparently
+- **Standard Protocol Compliance:** Full MCP specification 2025-03-26 support
+- **Flexible Transport Options:** JSON and SSE streaming responses
+- **Built-in Error Handling:** Standard JSON-RPC error responses
 
 ## Security Considerations
 

docs.json

@@ -17,6 +17,7 @@
             "group": "Essentials",
             "pages": [
               "index",
+              "general/quick-start",
               "general/architecture",
               "general/teams",
               "general/roles",