# DP-MCP Client Guide
This guide covers how to use the DP-MCP client to interact with your DP-MCP server using the official Model Context Protocol (MCP).
## Table of Contents
- [Overview](#overview)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Interactive Mode](#interactive-mode)
- [Command Line Usage](#command-line-usage)
- [Tool Examples](#tool-examples)
- [Advanced Usage](#advanced-usage)
- [Integration Examples](#integration-examples)
- [Troubleshooting](#troubleshooting)
## Overview
The DP-MCP client is a comprehensive testing and interaction tool that communicates with the DP-MCP server using the official MCP (Model Context Protocol) over HTTP with Server-Sent Events (SSE). It provides both interactive and programmatic access to all server tools.
### Key Features
- ✅ **Full MCP Protocol Support**: JSON-RPC 2.0 over HTTP with SSE
- ✅ **Interactive Mode**: Command-line interface for real-time interaction
- ✅ **Batch Operations**: Script-friendly command-line interface
- ✅ **Tool Discovery**: Automatic discovery and documentation of available tools
- ✅ **Error Handling**: Comprehensive error reporting and debugging
- ✅ **Colored Output**: Beautiful terminal output with syntax highlighting
## Installation
The MCP client is included with your DP-MCP server installation.
### Prerequisites
1. **DP-MCP Server Running**: Make sure your server is running
```bash
# Start your server first
uv run python src/dp_mcp/server.py --debug
```
2. **Dependencies**: Install client dependencies
```bash
# Dependencies are already included in pyproject.toml
uv sync
```
## Quick Start
### 1. Verify Server Connection
```bash
# Test server connectivity
uv run python mcp_client.py --ping
```
Expected output:
```
ℹ️ Pinging server...
✅ Server responded to ping
```
### 2. List Available Tools
```bash
# See all available tools
uv run python mcp_client.py --list-tools
```
### 3. Start Interactive Mode
```bash
# Launch interactive client
uv run python mcp_client.py --interactive
```
## Interactive Mode
Interactive mode provides a command-line interface for real-time interaction with the MCP server.
### Starting Interactive Mode
```bash
uv run python mcp_client.py --interactive
```
You'll see:
```
🔌 DP-MCP Interactive Client
============================
ℹ️ Initializing MCP connection...
✅ MCP connection initialized
ℹ️ Connected to server: http://127.0.0.1:8888/mcp
ℹ️ Available tools: 11
ℹ️ Type 'help' for available commands, 'quit' to exit
mcp>
```
### Interactive Commands
| Command | Description | Example |
|---------|-------------|---------|
| `help` | Show available commands | `help` |
| `tools` | List all available tools | `tools` |
| `describe <tool>` | Describe a specific tool | `describe list_db_tables` |
| `ping` | Test server connectivity | `ping` |
| `call <tool> [args]` | Call a tool with arguments | `call list_db_tables` |
| `quit` | Exit the client | `quit` |
### Interactive Examples
```bash
# List all available tools
mcp> tools
# Describe a specific tool
mcp> describe describe_db_table
# Call tools with various arguments
mcp> call list_db_tables
mcp> call describe_db_table table_name=users
mcp> call execute_sql_query query="SELECT * FROM users LIMIT 5"
mcp> call list_minio_buckets
mcp> call upload_to_minio bucket_name=default-bucket object_name=test.txt data="Hello World"
```
## Command Line Usage
### Basic Syntax
```bash
uv run python mcp_client.py [options]
```
### Available Options
| Option | Description | Example |
|--------|-------------|---------|
| `--server URL` | Specify server URL | `--server http://localhost:9000/mcp` |
| `--interactive` | Start interactive mode | `--interactive` |
| `--list-tools` | List available tools | `--list-tools` |
| `--call TOOL` | Call a specific tool | `--call list_db_tables` |
| `--args JSON` | Tool arguments as JSON | `--args '{"table_name": "users"}'` |
| `--test-all` | Test all available tools | `--test-all` |
| `--ping` | Ping the server | `--ping` |
### Command Line Examples
```bash
# List tools
uv run python mcp_client.py --list-tools
# Call tool without arguments
uv run python mcp_client.py --call list_db_tables
# Call tool with arguments
uv run python mcp_client.py --call describe_db_table --args '{"table_name": "users"}'
# Test all tools
uv run python mcp_client.py --test-all
# Use custom server URL
uv run python mcp_client.py --server http://localhost:9000/mcp --ping
```
## Tool Examples
### PostgreSQL Tools
#### List Database Tables
```bash
# Interactive
mcp> call list_db_tables
# Command line
uv run python mcp_client.py --call list_db_tables
# With specific schema
mcp> call list_db_tables schema=analytics
```
#### Describe Table Structure
```bash
# Interactive
mcp> call describe_db_table table_name=users
# Command line
uv run python mcp_client.py --call describe_db_table --args '{"table_name": "users"}'
# With schema
mcp> call describe_db_table table_name=sales schema=analytics
```
#### Execute SQL Queries
```bash
# Simple query
mcp> call execute_sql_query query="SELECT COUNT(*) FROM users"
# Complex query with limit
mcp> call execute_sql_query query="SELECT username, email FROM users WHERE is_active = true" limit=10
# Command line
uv run python mcp_client.py --call execute_sql_query --args '{"query": "SELECT * FROM products LIMIT 5"}'
```
#### Export Table to CSV
```bash
# Export entire table
mcp> call export_table_csv table_name=users
# Export with limit
mcp> call export_table_csv table_name=orders limit=100
# Export with filtering
mcp> call export_table_csv table_name=orders where_clause="order_date >= '2025-01-01'" limit=500
```
### MinIO Tools
#### List Buckets
```bash
# Interactive
mcp> call list_minio_buckets
# Command line
uv run python mcp_client.py --call list_minio_buckets
```
#### List Objects in Bucket
```bash
# List all objects
mcp> call list_bucket_objects bucket_name=default-bucket
# List with prefix filter
mcp> call list_bucket_objects bucket_name=backups prefix="2025/01/" max_keys=50
# Command line
uv run python mcp_client.py --call list_bucket_objects --args '{"bucket_name": "default-bucket"}'
```
#### Upload Data
```bash
# Upload text data
mcp> call upload_to_minio bucket_name=default-bucket object_name=hello.txt data="Hello from MCP!"
# Upload with custom content type
mcp> call upload_to_minio bucket_name=data-lake object_name=config.json data='{"key":"value"}' content_type="application/json"
```
#### Download Objects
```bash
# Download object
mcp> call download_from_minio bucket_name=default-bucket object_name=hello.txt
# Command line
uv run python mcp_client.py --call download_from_minio --args '{"bucket_name": "default-bucket", "object_name": "hello.txt"}'
```
#### Create Buckets
```bash
# Create simple bucket
mcp> call create_minio_bucket bucket_name=my-new-bucket
# Create with region
mcp> call create_minio_bucket bucket_name=analytics-data region=us-west-2
```
#### Delete Objects
```bash
# Delete object
mcp> call delete_minio_object bucket_name=default-bucket object_name=old-file.txt
```
### Combined Operations
#### Backup Table to MinIO
```bash
# Simple backup
mcp> call backup_table_to_minio table_name=users
# Backup to specific bucket
mcp> call backup_table_to_minio table_name=orders bucket_name=daily-backups schema=public limit=10000
# Backup with filtering
mcp> call backup_table_to_minio table_name=orders bucket_name=monthly-archives where_clause="order_date >= '2025-01-01'"
```
## Advanced Usage
### Testing All Tools
The client includes a comprehensive test suite:
```bash
# Test all available tools
uv run python mcp_client.py --test-all
```
This will:
- Connect to the server
- Discover all available tools
- Execute predefined test cases for each tool
- Report success/failure for each tool
- Provide a summary of results
Example output:
```
🔌 Testing All Tools
====================
ℹ️ Testing 11 tools...
ℹ️ Testing list_db_tables...
✅ ✓ list_db_tables
ℹ️ Testing describe_db_table...
✅ ✓ describe_db_table
...
🔌 Test Results Summary
=======================
Total tools: 11
Successful: 10
Failed: 1
✅ list_db_tables
✅ describe_db_table
✅ execute_sql_query
...
❌ some_tool: Connection timeout
```
### Custom Server URLs
```bash
# Connect to different server
uv run python mcp_client.py --server http://production.example.com:8888/mcp --interactive
# Test remote server
uv run python mcp_client.py --server https://mcp.mycompany.com/api/mcp --ping
```
### Scripting with MCP Client
Create bash scripts that use the MCP client:
```bash
#!/bin/bash
# backup_script.sh
echo "Starting daily backup..."
# Create timestamped bucket
BUCKET="backup-$(date +%Y%m%d)"
uv run python mcp_client.py --call create_minio_bucket --args "{\"bucket_name\": \"$BUCKET\"}"
# Backup critical tables
for table in users products orders; do
echo "Backing up $table..."
uv run python mcp_client.py --call backup_table_to_minio --args "{\"table_name\": \"$table\", \"bucket_name\": \"$BUCKET\"}"
done
echo "Backup completed to bucket: $BUCKET"
```
### Error Handling
The client provides detailed error information:
```bash
# Tool call with invalid arguments
mcp> call describe_db_table table_name=nonexistent_table
❌ Tool call failed: Query execution failed: relation "nonexistent_table" does not exist
Details: {'tool': 'describe_db_table', 'error': 'Table not found', 'parameters': {'table_name': 'nonexistent_table'}}
```
## Integration Examples
### Python Integration
You can import and use the MCPClient class in your own Python scripts:
```python
#!/usr/bin/env python3
import asyncio
from mcp_client import MCPClient
async def main():
client = MCPClient("http://127.0.0.1:8888/mcp")
# Initialize connection
await client.initialize()
# List tables
result = await client.call_tool("list_db_tables", {})
print("Available tables:", result)
# Query data
result = await client.call_tool("execute_sql_query", {
"query": "SELECT COUNT(*) FROM users",
"limit": 1
})
print("User count:", result)
if __name__ == "__main__":
asyncio.run(main())
```
### CI/CD Integration
Use the MCP client in your CI/CD pipelines:
```yaml
# .github/workflows/test-mcp.yml
name: Test MCP Server
on: [push, pull_request]
jobs:
test-mcp:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Start services
run: docker-compose up -d
- name: Start MCP server
run: uv run python src/dp_mcp/server.py &
- name: Wait for server
run: sleep 10
- name: Test MCP tools
run: uv run python mcp_client.py --test-all
- name: Test specific functionality
run: |
uv run python mcp_client.py --call list_db_tables
uv run python mcp_client.py --call list_minio_buckets
```
### Monitoring Integration
Use the client for health checks and monitoring:
```bash
#!/bin/bash
# health_check_mcp.sh
# Test MCP server health
if uv run python mcp_client.py --ping; then
echo "MCP server is healthy"
exit 0
else
echo "MCP server is unhealthy"
# Send alert to monitoring system
curl -X POST https://monitoring.example.com/alert \
-H "Content-Type: application/json" \
-d '{"service": "mcp-server", "status": "down"}'
exit 1
fi
```
## Troubleshooting
### Common Issues
#### Connection Refused
```
❌ Client error: Connection error: Cannot connect to host 127.0.0.1:8888
```
**Solution:**
1. Make sure the MCP server is running
2. Check the server URL and port
3. Verify firewall settings
```bash
# Check if server is running
ps aux | grep dp_mcp
# Start server if not running
uv run python src/dp_mcp/server.py --debug
```
#### Server Not Responding
```
❌ Failed to initialize: Request timeout
```
**Solution:**
1. Check server logs for errors
2. Verify server configuration
3. Test with ping first
```bash
# Check server status
curl -v http://127.0.0.1:8888/mcp/
# Test with ping
uv run python mcp_client.py --ping
```
#### Tool Call Failures
```
❌ Tool call failed: Tool execution failed: Database connection error
```
**Solution:**
1. Check if backend services (PostgreSQL, MinIO) are running
2. Verify configuration in `.env` file
3. Test individual services
```bash
# Check Docker services
docker-compose ps
# Test database connection
psql -h localhost -U dp_mcp_user -d dp_mcp_dev
# Test MinIO connection
curl http://localhost:9000/minio/health/live
```
#### Invalid JSON Arguments
```
❌ Invalid JSON in --args: Expecting ',' delimiter
```
**Solution:**
Make sure JSON arguments are properly formatted:
```bash
# Wrong
--args '{table_name: "users"}'
# Correct
--args '{"table_name": "users"}'
```
### Debug Mode
Enable detailed debugging:
```bash
# Run client with Python debugging
PYTHONPATH=. python -u mcp_client.py --interactive
# Check server logs
uv run python src/dp_mcp/server.py --debug
# Capture network traffic
uv run python mcp_client.py --call list_db_tables 2>&1 | tee debug.log
```
### Network Issues
Test connectivity step by step:
```bash
# Test basic HTTP connectivity
curl -v http://127.0.0.1:8888/mcp/
# Test with proper MCP headers
curl -X POST http://127.0.0.1:8888/mcp/ \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{"jsonrpc":"2.0","id":"1","method":"ping"}'
# Use MCP client ping
uv run python mcp_client.py --ping
```
### Performance Issues
For slow responses:
```bash
# Use timeout settings
uv run python mcp_client.py --call execute_sql_query --args '{"query": "SELECT * FROM large_table LIMIT 10"}'
# Monitor server resource usage
docker stats dp-mcp-postgres dp-mcp-minio
# Check server logs for slow queries
docker-compose logs postgres | grep "slow"
```
For more help, see the main [README.md](../README.md) and [API Reference](API_REFERENCE.md).
