postgres-mcp-tools/docs/ROBUST_TRANSPORT.md

PostgreSQL-based memory system with vector search capabilities for AI applications, including MCP integration for Claude

# Robust MCP Transport Layer

This document explains the robust transport layer implementation for the PostgreSQL MCP tools.

## Overview

The robust transport layer is designed to handle communication between the MCP server and clients, with enhanced error handling and graceful processing of non-JSON messages. This prevents server crashes due to unexpected message formats.

## Key Components

### RobustReadBuffer

`RobustReadBuffer` is a replacement for the standard `ReadBuffer` class from the MCP SDK. It provides the following improvements:

- Gracefully handles non-JSON input by logging it instead of crashing
- Maintains proper buffer management for streaming input
- Preserves the same interface as the original `ReadBuffer` for compatibility

### RobustHttpTransport

`RobustHttpTransport` is a complete implementation of the MCP `Transport` interface that:

- Provides bidirectional communication between the server and clients
- Properly handles client connections and disconnections
- Processes incoming messages safely, preventing JSON parsing crashes
- Maintains session information for the MCP protocol
- Streams responses back to connected clients efficiently

## Implementation Details

### Error Handling

All JSON parsing operations are wrapped in try-catch blocks to prevent unhandled exceptions. When a non-JSON message is received:

1. The message is logged for debugging purposes
2. The error is captured and handled gracefully
3. The server continues operating normally

### Client Management

The transport maintains a list of connected clients, allowing for:

- Broadcasting messages to all connected clients
- Handling individual client disconnections
- Removing stale connections automatically

### HTTP Server

The HTTP server implementation:

- Uses standard Node.js `http` module for maximum compatibility
- Provides proper HTTP response streaming for long-lived connections
- Sets appropriate headers for streaming JSON responses
- Handles errors at all stages of communication

## Usage

The robust transport layer is automatically used by the PostgreSQL MCP server. No additional configuration is required.

## Troubleshooting

If you encounter issues with the MCP server:

1. Check the logs for any error messages
2. Verify that the server is running and listening on the expected port
3. Ensure that clients are connecting to the correct endpoint
4. Verify network connectivity between the server and clients

## Integration with Claude Desktop

The robust transport is specifically designed to work with Claude Desktop, handling the mixed message formats that can occur during startup and operation.