ds_mcp_template/MCP_CLIENT_README.md

# MCP OpenAI Client with Flexible Transport

A powerful Python client that integrates OpenAI models with MCP (Model Context Protocol) servers, supporting both SSE and stdio transport methods.

## 🌟 Features

- **Flexible Transport**: Choose between SSE and stdio transport methods
- **OpenAI Integration**: Seamlessly use GPT models with MCP tools
- **Interactive Mode**: Command-line interface for natural conversation
- **Tool Execution**: Automatic tool calling based on user queries
- **Resource Support**: Access to MCP resources and prompts
- **Error Handling**: Robust error handling and connection management

## 🚀 Quick Start

### Prerequisites

1. **OpenAI API Key**: Set your OpenAI API key as an environment variable:
   ```bash
   export OPENAI_API_KEY="your-api-key-here"
   ```

2. **MCP Server Running**: Make sure your MCP server is running:
   ```bash
   # For SSE transport (recommended)
   python run_mcp_server.py --transport sse

   # For stdio transport
   python run_mcp_server.py --transport stdio
   ```

### Basic Usage

#### Interactive Mode (Recommended)
```bash
# Default: SSE transport, GPT-4o model
python mcp_openai_client.py

# Stdio transport
python mcp_openai_client.py --transport stdio

# Different model
python mcp_openai_client.py --model gpt-3.5-turbo
```

#### Single Query Mode
```bash
# Process a single query and exit
python mcp_openai_client.py --query "Calculate 15 + 27"

# With different transport
python mcp_openai_client.py --transport stdio --query "What's the square root of 144?"
```

#### Examples and Demos
```bash
# Run example scripts
python example_usage.py
```

## 📖 Usage Examples

### SSE Transport (Default)
```bash
python mcp_openai_client.py
```
This will connect to `http://localhost:8050/sse` by default.

### Custom Server URL
```bash
python mcp_openai_client.py --server-url http://localhost:3000/sse
```

### Stdio Transport
```bash
python mcp_openai_client.py --transport stdio --server-script run_mcp_server.py
```

### Different OpenAI Models
```bash
# GPT-3.5 Turbo (faster, cheaper)
python mcp_openai_client.py --model gpt-3.5-turbo

# GPT-4 (more capable)
python mcp_openai_client.py --model gpt-4

# GPT-4o (recommended default)
python mcp_openai_client.py --model gpt-4o
```

## 🔧 Available Tools

The client automatically discovers and uses all available MCP tools. Current tools include:

### Math Tools
- `add` - Add two numbers
- `subtract` - Subtract numbers
- `multiply` - Multiply numbers
- `divide` - Divide numbers
- `power` - Calculate power
- `square_root` - Calculate square root
- `calculate_bmi` - Calculate BMI

### Text Tools
- `count_words` - Count words in text
- `search_text` - Search for patterns
- `replace_text` - Replace text patterns
- `to_uppercase` - Convert to uppercase
- `to_lowercase` - Convert to lowercase
- `text_length` - Get text length

### System Tools
- `get_system_info` - Get system information
- `get_current_time` - Get current time
- `list_directory` - List directory contents
- `get_file_info` - Get file information
- `get_environment_variable` - Get environment variables

### Web Tools
- `url_encode` - URL encode strings
- `url_decode` - URL decode strings
- `parse_url` - Parse URLs
- `validate_email` - Validate email addresses
- `extract_domain` - Extract domains

### Utility Tools
- `generate_greeting` - Generate personalized greetings

## 📋 Available Resources

- `config://settings` - Server configuration
- `dynamic://greeting` - Dynamic greeting resource

## 💬 Example Queries

Try these example queries to see the system in action:

1. **Math**: "What is 123 multiplied by 456?"
2. **Text**: "Count the words in this sentence and convert it to uppercase"
3. **System**: "What time is it right now?"
4. **File**: "List the contents of the current directory"
5. **Web**: "Validate if 'user@example.com' is a valid email address"
6. **Combined**: "Calculate the BMI for someone who is 5'10\" tall and weighs 160 pounds, then tell me what time it is"

## 🏗️ Architecture

The client follows this workflow:

1. **Connection**: Connects to MCP server using chosen transport (SSE/stdio)
2. **Discovery**: Discovers available tools, prompts, and resources
3. **Query Processing**: Sends user query to OpenAI with tool descriptions
4. **Tool Execution**: If OpenAI requests tool use, executes tools via MCP
5. **Response**: Returns final response incorporating tool results

## 🔧 Configuration

### Environment Variables
- `OPENAI_API_KEY` - Your OpenAI API key (required)

### Command Line Options
- `--transport` - Transport type: `sse` (default) or `stdio`
- `--model` - OpenAI model: `gpt-4o` (default), `gpt-4`, `gpt-3.5-turbo`
- `--server-url` - Server URL for SSE transport
- `--server-script` - Server script path for stdio transport
- `--query` - Single query to process
- `--verbose` - Enable verbose output

## 🚨 Troubleshooting

### Connection Issues
- **SSE Connection Failed**: Make sure the MCP server is running with SSE transport
- **Stdio Connection Failed**: Check that the server script path is correct
- **Port Issues**: Ensure the server is running on the expected port (8050)

### API Key Issues
- **Missing API Key**: Set the `OPENAI_API_KEY` environment variable
- **Invalid API Key**: Check that your OpenAI API key is valid and has credits

### Tool Execution Issues
- **Tool Not Found**: The requested tool might not be available on the server
- **Tool Execution Failed**: Check the server logs for detailed error information

## 📝 Development

### Adding New Tools
1. Add your tool to the appropriate tool file in `src/mcp_template/tools/`
2. Follow the existing pattern with proper error handling
3. Test the tool individually before integration

### Modifying Transport Logic
The client supports both SSE and stdio transports. To add new transports:
1. Add the transport type to the `TransportType` enum
2. Implement the connection method in `MCPOpenAIClient`
3. Update the `connect_to_server` method

## 📄 License

This project is part of the MCP Template system. See the main README for licensing information.

---

## 🎯 Next Steps

1. **Start the MCP Server**:
   ```bash
   python run_mcp_server.py --transport sse
   ```

2. **Set your OpenAI API Key**:
   ```bash
   export OPENAI_API_KEY="your-key-here"
   ```

3. **Run the Client**:
   ```bash
   python mcp_openai_client.py
   ```

4. **Ask Questions**: Try queries like "Calculate 25 * 16" or "What tools do you have available?"

Enjoy using your MCP-powered OpenAI assistant! 🤖✨