Jira-GitLab MCP Server

# WebSocket MCP Server Implementation This document describes the WebSocket implementation for the Jira-GitLab MCP Server, which allows the server to run in WebSocket mode instead of the default stdio mode. ## Overview The MCP server now supports two modes of operation: - **stdio mode** (default): Traditional MCP server using standard input/output - **websocket mode**: WebSocket-based server for network connectivity ## Configuration ### Server Mode Configuration Update your `config.json` to specify the server mode: ```json { "server": { "mode": "websocket", "websocket": { "host": "0.0.0.0", "port": 8765, "max_connections": 100, "ping_interval": 20, "ping_timeout": 10 } }, "jira": { "base_url": "https://yourcompany.atlassian.net", "email": "your-email@example.com", "api_token": "your-jira-api-token" }, "gitlab": { "base_url": "https://gitlab.com", "access_token": "your-gitlab-personal-access-token" }, "ai": { "provider": "openai", "api_key": "your-openai-api-key", "model": "gpt-4-turbo-preview" } } ``` ### Configuration Options #### Server Configuration - `mode`: Server mode (`"stdio"` or `"websocket"`) - `websocket.host`: Host to bind the WebSocket server (default: `"0.0.0.0"`) - `websocket.port`: Port for the WebSocket server (default: `8765`) - `websocket.max_connections`: Maximum concurrent connections (default: `100`) - `websocket.ping_interval`: WebSocket ping interval in seconds (default: `20`) - `websocket.ping_timeout`: WebSocket ping timeout in seconds (default: `10`) ## Running the Server ### WebSocket Mode ```bash # Set server mode to websocket in config.json python mcp_server.py ``` ### stdio Mode (Default) ```bash # Set server mode to stdio in config.json or omit server configuration python mcp_server.py ``` ### Direct WebSocket Server ```bash # Run WebSocket server directly python websocket_server.py ``` ## WebSocket Protocol ### Message Format All WebSocket messages use JSON format with the following structure: #### Request Message ```json { "request_id": "unique-request-id", "type": "message_type", "name": "tool_name", "arguments": {}, "uri": "resource_uri" } ``` #### Response Message ```json { "request_id": "unique-request-id", "type": "response", "success": true, "data": {} } ``` #### Error Response ```json { "request_id": "unique-request-id", "type": "error", "success": false, "error": "error_message" } ``` ### Message Types #### 1. Welcome Message (Server → Client) Sent automatically when a client connects: ```json { "type": "welcome", "server": "jira-gitlab-mcp-ws", "version": "1.0.0", "capabilities": { "tools": true, "resources": true } } ``` #### 2. List Tools (Client → Server) ```json { "request_id": "req-1", "type": "list_tools" } ``` #### 3. List Resources (Client → Server) ```json { "request_id": "req-2", "type": "list_resources" } ``` #### 4. Read Resource (Client → Server) ```json { "request_id": "req-3", "type": "read_resource", "uri": "jira://issues" } ``` #### 5. Call Tool (Client → Server) ```json { "request_id": "req-4", "type": "call_tool", "name": "get_jira_issues", "arguments": { "jql": "project = DEMO", "max_results": 10 } } ``` ## Available Tools and Resources ### Tools - `create_branch_for_issue`: Create a GitLab branch for a Jira issue - `get_jira_issues`: Fetch Jira issues using JQL query - `comment_on_issue`: Add a comment to a Jira issue - `get_issues_by_tags`: Fetch Jira issues by project and tags - `analyze_and_fix_issue`: Use AI to analyze and generate fixes for issues ### Resources - `jira://issues`: Access to Jira issues in the configured project - `github://projects`: Access to GitHub repositories and branches ## Testing ### Using the Test Script ```bash # Install websockets if not already installed pip install websockets # Run the test script python test_websocket.py ``` ### Manual Testing with wscat ```bash # Install wscat npm install -g wscat # Connect to the server wscat -c ws://localhost:8765 # Send a test message {"request_id": "test-1", "type": "list_tools"} ``` ### Using Python websockets ```python import asyncio import json import websockets async def test_connection(): uri = "ws://localhost:8765" async with websockets.connect(uri) as websocket: # Send list tools request message = { "request_id": "test-1", "type": "list_tools" } await websocket.send(json.dumps(message)) # Receive response response = await websocket.recv() print(json.loads(response)) asyncio.run(test_connection()) ``` ## Error Handling The WebSocket server includes comprehensive error handling: - **Connection errors**: Logged and cleaned up automatically - **Message parsing errors**: Return error response to client - **Tool execution errors**: Wrapped in error response format - **Client disconnections**: Gracefully handled with cleanup ## Security Considerations - The server binds to `0.0.0.0` by default for development - For production, consider: - Binding to specific interfaces - Adding authentication/authorization - Using WSS (WebSocket Secure) with TLS - Implementing rate limiting - Adding input validation ## Performance - Supports multiple concurrent connections - Configurable ping/pong for connection health - Efficient JSON message handling - Async/await throughout for non-blocking operations ## Troubleshooting ### Common Issues 1. **Connection Refused** - Check if server is running - Verify port is not in use - Check firewall settings 2. **WebSocket Handshake Failed** - Verify WebSocket URL format (`ws://` or `wss://`) - Check server logs for errors 3. **Tool Execution Errors** - Verify API credentials in config - Check network connectivity to Jira/GitLab - Review server logs for detailed error messages ### Debugging Enable debug logging: ```python import logging logging.basicConfig(level=logging.DEBUG) ``` Check server logs for detailed error information and connection status. ## Migration from stdio Mode To migrate from stdio mode to WebSocket mode: 1. Update `config.json` to set `server.mode` to `"websocket"` 2. Add WebSocket configuration section 3. Update client code to use WebSocket protocol instead of stdio 4. Test thoroughly with the provided test script ## Future Enhancements Potential improvements for the WebSocket implementation: - Authentication and authorization - SSL/TLS support (WSS) - Message compression - Rate limiting - Connection pooling - Health check endpoints - Metrics and monitoring