feat: Add TCP server support for external AI services

- Implement dual transport mode (stdio/TCP) for MCP server
- Add StreamableHTTPServerTransport for network accessibility
- Support command-line arguments for host and port configuration
- Update CLI with --host and --port options for TCP mode
- Add comprehensive TCP server documentation and examples
- Create test script for TCP server validation
- Maintain backward compatibility with stdio mode
- Add security considerations and best practices

This enables integration with ChatGPT and other AI services that
require HTTP-based MCP server connections rather than subprocess
spawning. The server can now run on network ports while preserving
the original stdio functionality for traditional MCP clients.

Closes #70

Author: devraj

docs/docs/mcp.md

@@ -37,9 +37,12 @@ export GACC_API_KEY="your-gallagher-api-key-here"
 #### Via CLI
 
 ```bash
-# Start the MCP server
+# Start the MCP server (stdio mode)
 gala mcp serve
 
+# Start the MCP server (TCP mode)
+gala mcp serve --port 8080 --host 0.0.0.0
+
 # Show configuration information
 gala mcp config
 
@@ -50,9 +53,33 @@ gala mcp test
 #### Direct Module Execution
 
 ```bash
+# Stdio mode (default)
 python -m gallagher.mcp
+
+# TCP mode
+python -m gallagher.mcp.server --port 8080 --host 0.0.0.0
 ```
 
+### Transport Modes
+
+The MCP server supports two transport modes:
+
+#### Stdio Mode (Default)
+
+- Runs on standard input/output
+- Used by MCP clients that spawn subprocesses
+- Secure for local use
+- No network exposure
+
+#### TCP Mode
+
+- Runs on a network port
+- Accessible via HTTP
+- Suitable for external AI services like ChatGPT
+- Requires network security considerations
+
+For detailed TCP server documentation, see [TCP Server Guide](tcp-server.md).
+
 ### Claude Desktop Configuration
 
 Add the following to your Claude Desktop MCP configuration:
@@ -71,6 +98,20 @@ Add the following to your Claude Desktop MCP configuration:
 }
 ```
 
+### ChatGPT and External AI Services
+
+For services that don't support subprocess-based MCP servers:
+
+```bash
+# Start TCP server
+gala mcp serve --port 8080 --host 0.0.0.0
+```
+
+Then configure your AI service to connect to:
+
+- **URL**: `http://your-server-ip:8080`
+- **Protocol**: MCP over HTTP
+
 ### Other MCP Clients
 
 For other MCP clients, you can run the server directly:

docs/docs/tcp-server.md

@@ -0,0 +1,239 @@
+# TCP Server for AI Services
+
+The Gallagher MCP server now supports running as a TCP server, making it accessible to AI services like ChatGPT, Claude, and other external applications that can connect via HTTP.
+
+## Overview
+
+The TCP server mode allows the Gallagher MCP server to:
+
+- Run on a network port instead of stdio
+- Accept connections from external AI services
+- Provide the same cardholder querying functionality over HTTP
+- Work with services that don't support subprocess-based MCP servers
+
+## Quick Start
+
+### 1. Set your API key
+
+```bash
+export GACC_API_KEY="your-gallagher-api-key-here"
+```
+
+### 2. Start the TCP server
+
+```bash
+# Using the CLI
+gala mcp serve --port 8080 --host 0.0.0.0
+
+# Or directly with Python
+python -m gallagher.mcp.server --port 8080 --host 0.0.0.0
+```
+
+### 3. Connect from your AI service
+
+Configure your AI service to connect to:
+
+- **URL**: `http://your-server-ip:8080`
+- **Protocol**: MCP over HTTP
+
+## Configuration Options
+
+### Host Binding
+
+- `--host localhost` (default): Only accessible from the local machine
+- `--host 0.0.0.0`: Accessible from any network interface
+- `--host 192.168.1.100`: Bind to a specific IP address
+
+### Port Selection
+
+- Choose any available port (e.g., 8080, 3000, 5000)
+- Avoid using privileged ports (below 1024)
+- Ensure the port is not already in use
+
+## Usage Examples
+
+### Local Development
+
+```bash
+# Start server for local testing
+gala mcp serve --port 8080 --host localhost
+```
+
+### Production Deployment
+
+```bash
+# Start server accessible from network
+gala mcp serve --port 8080 --host 0.0.0.0
+```
+
+### Docker Deployment
+
+```dockerfile
+FROM python:3.10-slim
+
+RUN pip install gallagher
+
+EXPOSE 8080
+
+CMD ["python", "-m", "gallagher.mcp.server", "--port", "8080", "--host", "0.0.0.0"]
+```
+
+## Available Tools
+
+The TCP server provides the same tools as the stdio server:
+
+- **list_cardholders** - List all cardholders in the system
+- **search_cardholders** - Search for cardholders by name or criteria
+- **get_cardholder** - Get detailed information about a specific cardholder
+- **get_cardholder_cards** - Get all cards assigned to a cardholder
+- **get_cardholder_access_groups** - Get all access groups assigned to a cardholder
+
+## Testing the Server
+
+### Using curl
+
+```bash
+# Test server connectivity
+curl http://localhost:8080/health
+
+# List available tools
+curl -X POST http://localhost:8080/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/list",
+    "params": {}
+  }'
+```
+
+### Using the test script
+
+```bash
+python examples/tcp_server_test.py
+```
+
+## Security Considerations
+
+### Network Security
+
+- **Firewall**: Restrict access to the server port
+- **Localhost only**: Use `--host localhost` for local-only access
+- **VPN**: Use VPN for remote access
+- **Reverse proxy**: Use nginx/apache with SSL termination
+
+### Authentication
+
+The current implementation relies on network-level security. For production use, consider:
+
+- Implementing API key authentication
+- Using HTTPS/TLS
+- Adding rate limiting
+- Implementing request validation
+
+### Environment Variables
+
+- Keep your `GACC_API_KEY` secure
+- Use environment-specific configuration
+- Consider using a secrets manager
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Port already in use**
+
+   ```bash
+   # Check what's using the port
+   lsof -i :8080
+
+   # Use a different port
+   gala mcp serve --port 8081
+   ```
+
+2. **Connection refused**
+
+   - Check if the server is running
+   - Verify the host and port settings
+   - Check firewall settings
+
+3. **Authentication errors**
+   - Verify `GACC_API_KEY` is set correctly
+   - Check Gallagher Command Centre connectivity
+   - Test with the stdio server first
+
+### Debug Mode
+
+```bash
+# Run with verbose logging
+python -m gallagher.mcp.server --port 8080 --host localhost
+```
+
+## Integration Examples
+
+### ChatGPT Plugin
+
+```json
+{
+  "name": "gallagher-mcp",
+  "description": "Gallagher Command Centre integration",
+  "endpoint": "http://localhost:8080",
+  "protocol": "mcp"
+}
+```
+
+### Custom AI Service
+
+```python
+import requests
+
+# Connect to Gallagher MCP server
+response = requests.post(
+    "http://localhost:8080/",
+    json={
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": "list_cardholders",
+            "arguments": {"limit": 10}
+        }
+    },
+    headers={"Content-Type": "application/json"}
+)
+
+print(response.json())
+```
+
+## Performance Considerations
+
+- The server handles one request at a time by default
+- For high-load scenarios, consider running multiple instances
+- Monitor memory usage with large cardholder datasets
+- Use connection pooling for external Gallagher API calls
+
+## Monitoring
+
+### Health Check
+
+```bash
+curl http://localhost:8080/health
+```
+
+### Logs
+
+Monitor server logs for:
+
+- Connection attempts
+- API call results
+- Error messages
+- Performance metrics
+
+## Support
+
+For issues with the TCP server:
+
+1. Check the troubleshooting section above
+2. Test with the stdio server first
+3. Review the main MCP documentation
+4. Check Gallagher Command Centre connectivity