# Roo-Compatible MCP Server Implementation Guide
## Overview
This implementation addresses specific protocol violations and formatting issues identified in research for Roo compatibility. The server provides a production-ready solution that works with Roo's MCP implementation requirements.
## Key Research-Based Fixes
### 1. Message Formatting Issues (CRITICAL)
- **Problem**: Embedded newlines in JSON responses broke Roo's parser
- **Solution**: Messages are validated to ensure no embedded `\n` or `\r` characters
- **Implementation**: [`roo-compatible-mcp-server.js:sendResponse()`](roo-compatible-mcp-server.js:458)
### 2. Initialization Handshake Sequence (CRITICAL)
- **Problem**: Missing proper initialization response and server info notification
- **Solution**: Proper initialization response followed by immediate server info notification
- **Implementation**: [`roo-compatible-mcp-server.js:handleInitialize()`](roo-compatible-mcp-server.js:113)
### 3. Empty Line Handshake Handling (CRITICAL)
- **Problem**: Roo sends empty lines during handshake that caused parsing errors
- **Solution**: Gracefully handle empty line input without errors
- **Implementation**: [`roo-compatible-mcp-server.js:handleInput()`](roo-compatible-mcp-server.js:71)
### 4. Stdout Line-Buffering (CRITICAL)
- **Problem**: Output buffering caused message delivery issues
- **Solution**: Ensure stdout is line-buffered and UTF-8 encoded
- **Implementation**: [`roo-compatible-mcp-server.js:constructor()`](roo-compatible-mcp-server.js:18)
### 5. Error Handling and Crash Prevention (CRITICAL)
- **Problem**: Uncaught exceptions caused connection drops
- **Solution**: Comprehensive error handling with graceful degradation
- **Implementation**: [`roo-compatible-mcp-server.js:setupErrorHandling()`](roo-compatible-mcp-server.js:26)
## Files Created
### Core Implementation
1. **[`roo-compatible-mcp-server.js`](roo-compatible-mcp-server.js)** - Main server implementation
2. **[`openai-service-roo.js`](openai-service-roo.js)** - OpenAI API service with proper error handling
3. **[`roo-config-corrected.json`](roo-config-corrected.json)** - Updated configuration with absolute paths
### Testing and Debugging
4. **[`test-roo-mcp-server.js`](test-roo-mcp-server.js)** - Comprehensive test suite
5. **[`ROO-COMPATIBILITY-GUIDE.md`](ROO-COMPATIBILITY-GUIDE.md)** - This documentation
## Protocol Compliance Features
### JSON-RPC 2.0 Compliance
- ✅ Proper `jsonrpc: "2.0"` field in all messages
- ✅ Correct `id` handling for request/response correlation
- ✅ Standard error codes and message structure
- ✅ UTF-8 encoding with newline delimiters
- ✅ No embedded newlines in messages
### MCP Protocol Compliance
- ✅ Proper initialization handshake sequence
- ✅ Server info notification after initialization
- ✅ All 15 vector store tools implemented
- ✅ Correct tool schema definitions
- ✅ Proper error responses with MCP error codes
### Roo-Specific Requirements
- ✅ Empty line handshake handling
- ✅ Immediate server info notification
- ✅ Stdout line-buffering
- ✅ Crash prevention with error recovery
- ✅ Environment variable validation
## Available Tools (15 Total)
### Vector Store Management
1. `vector-store-create` - Create a new vector store
2. `vector-store-list` - List all vector stores
3. `vector-store-get` - Get details of a specific vector store
4. `vector-store-delete` - Delete a vector store
5. `vector-store-modify` - Modify a vector store
### File Management
6. `vector-store-file-add` - Add an existing file to a vector store
7. `vector-store-file-list` - List files in a vector store
8. `vector-store-file-get` - Get details of a specific file
9. `vector-store-file-content` - Get content of a specific file
10. `vector-store-file-update` - Update metadata of a file
11. `vector-store-file-delete` - Delete a file from a vector store
### Batch Operations
12. `vector-store-file-batch-create` - Create a file batch
13. `vector-store-file-batch-get` - Get status of a file batch
14. `vector-store-file-batch-cancel` - Cancel a file batch
15. `vector-store-file-batch-files` - List files in a file batch
## Installation and Setup
### Prerequisites
- Node.js 18+ installed
- Valid OpenAI API key
- Roo application
### Step 1: Environment Setup
```bash
export OPENAI_API_KEY="sk-your-openai-api-key-here"
export DEBUG="true" # Optional: Enable debug logging
```
### Step 2: Make Server Executable
```bash
chmod +x roo-compatible-mcp-server.js
```
### Step 3: Test Server Functionality
```bash
# Run the test suite
OPENAI_API_KEY="your-key" node test-roo-mcp-server.js
```
### Step 4: Configure Roo
Update your Roo configuration to use the corrected server:
```json
{
"mcpServers": {
"roo-compatible-openai-vector-store": {
"command": "node",
"args": ["/absolute/path/to/roo-compatible-mcp-server.js"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"DEBUG": "true"
}
}
}
}
```
## Debugging and Troubleshooting
### Enable Debug Logging
Set `DEBUG=true` in the environment to enable detailed logging:
```bash
DEBUG=true OPENAI_API_KEY="your-key" node roo-compatible-mcp-server.js
```
### Common Issues and Solutions
#### 1. "OPENAI_API_KEY environment variable is required"
- **Cause**: Missing or invalid API key
- **Solution**: Set valid OpenAI API key in environment
- **Check**: API key should start with `sk-`
#### 2. "Server not initialized"
- **Cause**: Tools called before initialization
- **Solution**: Ensure Roo calls `initialize` method first
- **Debug**: Check initialization sequence in logs
#### 3. "Parse error" responses
- **Cause**: Malformed JSON input
- **Solution**: Verify JSON-RPC 2.0 format compliance
- **Debug**: Check input messages in debug logs
#### 4. Connection drops or timeouts
- **Cause**: Server crashes or hangs
- **Solution**: Check stderr for error messages
- **Debug**: Enable debug logging to trace execution
### Log Locations
- **Server logs**: stderr (does not interfere with MCP protocol on stdout)
- **Debug logs**: stderr with `[DEBUG]` prefix when `DEBUG=true`
- **Error logs**: stderr with `[ERROR]` prefix
### Testing Individual Components
#### Test Server Startup
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"clientInfo":{"name":"test","version":"1.0.0"}}}' | OPENAI_API_KEY="your-key" node roo-compatible-mcp-server.js
```
#### Test Tools List
```bash
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | OPENAI_API_KEY="your-key" node roo-compatible-mcp-server.js
```
## Performance Considerations
### Memory Usage
- Server uses minimal memory footprint
- No persistent state maintained
- Each request is stateless
### Network Optimization
- Direct OpenAI API calls (no proxy overhead)
- Proper timeout handling (30 seconds)
- Connection reuse for multiple requests
### Error Recovery
- Graceful handling of API rate limits
- Automatic retry logic for transient failures
- Proper error code mapping
## Security Considerations
### API Key Protection
- API key passed via environment variables only
- No API key logging or exposure in responses
- Validation of API key format before use
### Input Validation
- JSON-RPC format validation
- Parameter type checking
- Sanitization of user inputs
### Error Information
- Error messages don't expose sensitive information
- Stack traces limited to debug mode only
- Proper error code classification
## Comparison with Previous Implementation
| Feature | Previous Implementation | Roo-Compatible Implementation |
|---------|------------------------|------------------------------|
| Message Format | Custom HTTP | JSON-RPC 2.0 over stdio |
| Newline Handling | Not addressed | Strict validation and removal |
| Initialization | Basic response | Full handshake + notification |
| Error Handling | Basic try/catch | Comprehensive crash prevention |
| Empty Line Support | Not handled | Graceful handling |
| Stdout Buffering | Default | Line-buffered for compatibility |
| Debug Logging | None | Comprehensive stderr logging |
| Environment Validation | None | Full validation with helpful errors |
## Future Enhancements
### Potential Improvements
1. **Configuration File Support**: Allow server configuration via JSON file
2. **Plugin Architecture**: Support for additional tool providers
3. **Metrics Collection**: Performance and usage metrics
4. **Health Checks**: Built-in health check endpoints
5. **Rate Limiting**: Client-side rate limiting for API protection
### Compatibility Extensions
1. **SSE Transport**: Add Server-Sent Events support as fallback
2. **WebSocket Transport**: Real-time bidirectional communication
3. **HTTP Transport**: REST API compatibility layer
4. **Authentication**: Support for multiple authentication methods
## Support and Maintenance
### Version Information
- **Current Version**: 1.0.0
- **Protocol Version**: 2024-11-05
- **Node.js Compatibility**: 18+
- **OpenAI API Version**: v1 with assistants=v2 beta
### Known Limitations
1. Requires valid OpenAI API key for all operations
2. No offline mode or caching
3. Single-threaded execution model
4. No built-in rate limiting (relies on OpenAI's limits)
### Reporting Issues
When reporting issues, please include:
1. Full error messages from stderr
2. Debug logs (with `DEBUG=true`)
3. Input messages that caused the issue
4. Environment information (Node.js version, OS)
5. OpenAI API key status (valid/invalid, but not the key itself)
This implementation provides a robust, production-ready MCP server that addresses all identified compatibility issues with Roo while maintaining full functionality of the original vector store operations.
