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:

   export OPENAI_API_KEY="your-api-key-here"
   

2. MCP Server Running: Make sure your MCP server is running:

   # 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)

# 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

# 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

# Run example scripts
python example_usage.py

📖 Usage Examples

SSE Transport (Default)

python mcp_openai_client.py

This will connect to http://localhost:8050/sse by default.

Custom Server URL

python mcp_openai_client.py --server-url http://localhost:3000/sse

Stdio Transport

python mcp_openai_client.py --transport stdio --server-script run_mcp_server.py

Different OpenAI Models

# 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:

   python run_mcp_server.py --transport sse
   

2. Set your OpenAI API Key:

   export OPENAI_API_KEY="your-key-here"
   

3. Run the Client:

   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! 🤖✨