README.md•4.48 kB
# Streamable HTTP MCP Server with Azure OpenAI GPT-4o
This project implements a **Streamable HTTP MCP (Model Context Protocol) Server** using FastAPI and integrates it with **Azure OpenAI GPT-4o** for intelligent tool usage.
## 🚀 Features
- **MCP Server**: Streamable HTTP server with SSE support
- **Azure OpenAI Integration**: GPT-4o with tool calling capabilities
- **Simple Tools**: Calculator, Weather (mock), and Time tools
- **Docker Setup**: Easy deployment with docker-compose
- **Real-time Communication**: Server-Sent Events (SSE) for streaming responses
## 📋 Prerequisites
- Docker and Docker Compose
- Azure OpenAI account with GPT-4o deployment
- Python 3.11+ (for local development)
## 🛠️ Quick Setup
1. **Clone and setup**:
```bash
# Copy environment file
cp .env.example .env
# Edit .env with your Azure OpenAI credentials
nano .env
```
2. **Configure Azure OpenAI**:
```env
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
AZURE_OPENAI_API_VERSION=2024-02-01
```
3. **Start the MCP server**:
```bash
./setup.sh start
```
4. **Run the GPT-4o client**:
```bash
./setup.sh client
```
## 📖 Usage Examples
### Basic Tool Usage
The client automatically demonstrates various tool interactions:
```
Query: What's the current time?
Response: The current time is 2024-01-15T14:30:45.123456
Query: Calculate 15 * 42 + 33
Response: The result is 663
Query: What's the weather like in New York?
Response: The weather in New York is currently sunny with a temperature of 22°C...
```
### Complex Multi-tool Usage
```
Query: Can you get the weather for London and then calculate the percentage if the temperature was 20 degrees and now it's 25 degrees?
Response: The weather in London is currently 22°C and sunny...
The percentage increase from 20°C to 25°C is 25%.
```
## 🔧 Available Tools
1. **Calculator**: Evaluate mathematical expressions
2. **Weather**: Get mock weather data for any location
3. **Time**: Get current timestamp
## 🏗️ Architecture
```
[GPT-4o Client] <--HTTP--> [MCP Server] <--SSE--> [Tools]
| |
| [Calculator]
| [Weather]
| [Time]
```
## 🌐 API Endpoints
- `POST /sse` - Main MCP communication endpoint
- `GET /health` - Health check
- `GET /tools` - List available tools
## 📝 Manual Testing
Test the MCP server directly:
```bash
# Health check
curl http://localhost:8000/health
# List tools
curl http://localhost:8000/tools
# Test SSE endpoint
curl -X POST http://localhost:8000/sse \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}}'
```
## 🐳 Docker Commands
```bash
# Start MCP server only
docker-compose up -d mcp-server
# Run client once
docker-compose run --rm client
# View logs
docker-compose logs -f mcp-server
# Stop everything
docker-compose down
```
## 🧪 Development
### Local Development
```bash
# Install dependencies
pip install -r requirements.txt
# Run server locally
python mcp_server.py
# Run client locally (in another terminal)
source .env
python client.py
```
### Adding New Tools
1. Create a new tool class in `mcp_server.py`
2. Add tool definition to `TOOLS` dictionary
3. Add handler in `MCPHandler.handle_tools_call`
Example:
```python
class NewTool:
@staticmethod
def do_something(param: str) -> Dict[str, Any]:
return {"result": f"Processed: {param}"}
# Add to TOOLS dictionary
TOOLS["new_tool"] = {
"name": "new_tool",
"description": "Does something useful",
"inputSchema": {
"type": "object",
"properties": {
"param": {"type": "string", "description": "Input parameter"}
},
"required": ["param"]
}
}
```
## 🐛 Troubleshooting
### Common Issues
1. **Connection refused**: Make sure MCP server is running on port 8000
2. **Authentication errors**: Check your Azure OpenAI credentials in `.env`
3. **Tool call failures**: Check MCP server logs for detailed error messages
### Debug Mode
Enable debug logging:
```bash
docker-compose logs -f mcp-server
```
## 🔒 Security Notes
- Never commit your `.env` file with real credentials
- Use environment variables in production
- Consider adding authentication for production deployments
## 📄 License
MIT License - feel free to use and modify as needed.