initial mcp server setup
This commit is contained in:
OwusuBlessing
@@ -0,0 +1,221 @@
|
||||
# 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! 🤖✨
|
||||
Reference in New Issue
Block a user