deepseek-mcp-client 1.0.0

Cliente para conectar modelos DeepSeek con servidores MCP

🚀 DeepSeek MCP Client - Versión Mejorada

Cliente para conectar modelos DeepSeek con servidores MCP

soporte para STDIO, HTTP, in-memory, message handlers y progress monitoring(testing)

---

Características

🔌 Soporte Completo de Transporte

• HTTP/HTTPS: Para servidores remotos y en producción
• STDIO: Para servidores locales con control completo del entorno
• In-Memory: Para testing y desarrollo rápido
• Configuración Mixta: Combina múltiples tipos de transporte

📊 Monitoreo Avanzado

• Progress Monitoring: Seguimiento en tiempo real de operaciones largas
• Message Handlers: Manejo automático de notificaciones del servidor
• Logging Integrado: Sistema de logs estructurado con niveles configurables
• Cache Inteligente: Actualización automática cuando cambian las herramientas

⚙️ Configuración Flexible

• Auto-detección: Identifica automáticamente el tipo de transporte
• Variables de Entorno: Manejo seguro de credenciales y configuración
• Timeout Personalizable: Control fino sobre timeouts de conexión
• Manejo de Errores: Recuperación robusta ante fallos

---

📦 Instalación

# Clonar el repositorio
git clone https://github.com/CarlosMaroRuiz/deepseek-mcp-client.git
cd deepseek-mcp-client

# Instalar dependencias actualizadas
pip install -r requirements.txt

⚙️ Configuración

# Copiar archivo de configuración
cp example.env .env

# Editar con tu API key
DEEPSEEK_API_KEY=tu_api_key_aquí

---

🚀 Uso - Ejemplos Completos

1. 🌐 Configuración HTTP Simple

from deepseek_mcp_client import DeepSeekClient
import asyncio

# Servidores HTTP remotos
agent = DeepSeekClient(
    model='deepseek-chat',
    system_prompt='Eres un asistente especializado en e-commerce.',
    mcp_servers=[
        'http://localhost:8000/mcp/',  # MercadoLibre MCP
        'http://localhost:8001/mcp/'   # LaTeX MCP
    ],
    enable_logging=True,
    enable_progress=True
)

async def main():
    result = await agent.execute('Busca laptops gaming económicas')
    print(f"Resultado: {result.output}")
    print(f"Herramientas usadas: {result.tools_used}")
    print(f"Duración: {result.metadata.get('duration'):.2f}s")

asyncio.run(main())

2. 💻 Configuración STDIO (Servidores Locales)

# Servidores locales con variables de entorno
agent = DeepSeekClient(
    model='deepseek-chat',
    system_prompt='Eres un asistente con herramientas locales.',
    mcp_servers=[
        {
            'command': 'python',
            'args': ['mercadolibre_server.py'],
            'env': {
                'LOG_LEVEL': 'DEBUG',
                'API_TIMEOUT': '30'
            },
            'cwd': './servers/',
            'keep_alive': True
        },
        {
            'command': 'node',
            'args': ['weather_server.js', '--port', '3000'],
            'env': {
                'WEATHER_API_KEY': 'tu_api_key_aquí'
            }
        }
    ],
    enable_logging=True,
    log_level="DEBUG"
)

3. 🔀 Configuración Mixta (Múltiples Transportes)

from fastmcp import FastMCP

# Crear servidor en memoria para testing
test_server = FastMCP("Calculator")

@test_server.tool
def calculate(expression: str) -> str:
    """Calculadora simple"""
    try:
        result = eval(expression)  # Solo para demo - usar math.eval en producción
        return f"Resultado: {result}"
    except Exception as e:
        return f"Error: {str(e)}"

# Cliente con múltiples tipos de transporte
agent = DeepSeekClient(
    model='deepseek-chat',
    system_prompt='Asistente con múltiples herramientas.',
    mcp_servers=[
        'http://localhost:8000/mcp/',     # HTTP: Servidor remoto
        {                                 # STDIO: Servidor local
            'command': 'python',
            'args': ['local_server.py'],
            'env': {'DEBUG': 'true'}
        },
        test_server                       # In-Memory: Calculadora
    ]
)

4. ⚙️ Configuración Avanzada con MCPServerConfig

from deepseek_mcp_client import MCPServerConfig

# Configuración detallada para servidor HTTP
mercadolibre_config = MCPServerConfig(
    url='http://localhost:8000/mcp/',
    headers={
        'Authorization': 'Bearer tu-token-aqui',
        'X-Client-Version': '1.0.0'
    },
    transport_type='http',
    timeout=45.0
)

# Configuración detallada para servidor STDIO
analyzer_config = MCPServerConfig(
    command='python',
    args=['data_analyzer.py', '--mode', 'production'],
    env={
        'DATABASE_URL': 'postgresql://...',
        'LOG_LEVEL': 'INFO'
    },
    cwd='./analytics/',
    keep_alive=True,
    timeout=60.0
)

agent = DeepSeekClient(
    model='deepseek-chat',
    system_prompt='Analista de datos especializado.',
    mcp_servers=[mercadolibre_config, analyzer_config],
    enable_logging=True,
    enable_progress=True
)

---

📊 Monitoreo y Logging

Progress Monitoring en Tiempo Real

# El cliente automáticamente muestra progreso de operaciones largas
agent = DeepSeekClient(
    model='deepseek-chat',
    system_prompt='Asistente con operaciones largas.',
    mcp_servers=['http://localhost:8000/mcp/'],
    enable_progress=True,  # Habilitar monitoreo de progreso
    enable_logging=True,   # Habilitar logging detallado
    log_level="INFO"       # Nivel de logging
)

# Durante la ejecución verás logs como:
# 📊 Progreso: 25.0% - Procesando datos...
# 🔧 tool_name: 50.0% - Analizando resultados...
# 📊 Progreso: 100.0% - Completado

Message Handlers Automáticos

# El cliente automáticamente maneja:
# - Cambios en listas de herramientas
# - Actualizaciones de recursos
# - Notificaciones de progreso
# - Mensajes de log del servidor

# Logs automáticos:
# 🔄 Lista de herramientas actualizada
# 🔄 Lista de recursos actualizada
# 🔄 Refrescando cache de herramientas...

---

🛠️ Casos de Uso Avanzados

1. E-commerce con Análisis Local

agent = DeepSeekClient(
    model='deepseek-chat',
    system_prompt='Analista de e-commerce con herramientas web y locales.',
    mcp_servers=[
        'http://localhost:8000/mcp/',  # Búsqueda en MercadoLibre
        {                              # Análisis de datos local
            'command': 'python',
            'args': ['analytics_server.py'],
            'env': {'DATABASE_URL': 'sqlite:///products.db'}
        }
    ]
)

result = await agent.execute('''
Busca las 10 laptops más vendidas en MercadoLibre,
analiza sus precios históricamente en mi base de datos local,
y genera un reporte de tendencias.
''')

2. Generación de Documentos Científicos

agent = DeepSeekClient(
    model='deepseek-chat',
    system_prompt='Asistente para investigación científica.',
    mcp_servers=[
        'http://localhost:8001/mcp/',  # LaTeX MCP
        {                              # Procesador de datos científicos
            'command': 'python',
            'args': ['scientific_processor.py'],
            'env': {
                'PYTHON_PATH': './scientific_libs/',
                'MATPLOTLIB_BACKEND': 'Agg'
            }
        }
    ]
)

result = await agent.execute('''
Analiza los datos del archivo experimental.csv,
genera gráficos estadísticos,
y crea un paper en LaTeX con los resultados.
''')

3. Sistema de Trading Automatizado

trading_config = MCPServerConfig(
    command='python',
    args=['trading_server.py', '--mode', 'live'],
    env={
        'BROKER_API_KEY': os.environ.get('BROKER_API_KEY'),
        'RISK_LEVEL': 'conservative',
        'MAX_POSITION_SIZE': '1000'
    },
    timeout=30.0
)

agent = DeepSeekClient(
    model='deepseek-chat',
    system_prompt='Asistente de trading con gestión de riesgo.',
    mcp_servers=[
        'http://localhost:8002/mcp/',  # Datos de mercado
        trading_config                 # Servidor de trading local seguro
    ]
)

---

🛡️ Manejo de Errores y Recuperación

async def ejemplo_robusto():
    agent = DeepSeekClient(
        model='deepseek-chat',
        system_prompt='Asistente resiliente.',
        mcp_servers=[
            'http://localhost:8000/mcp/',      # Servidor que funciona
            'http://localhost:9999/mcp/',      # Servidor inexistente
            {'command': 'python', 'args': ['bad_server.py']}  # Archivo inexistente
        ]
    )
    
    try:
        result = await agent.execute('Hola')
        
        if result.success:
            print(f"✅ Respuesta: {result.output}")
            print(f"🔧 Servidores conectados: {result.metadata.get('servers_connected')}")
        else:
            print(f"❌ Error: {result.error}")
    
    except Exception as e:
        print(f"💥 Error crítico: {e}")
    
    finally:
        await agent.close()  # Limpieza automática

---

📈 Análisis de Rendimiento

# Metadata detallada en cada resultado
result = await agent.execute('Tu consulta')

print(f"Duración total: {result.metadata.get('duration'):.2f}s")
print(f"Herramientas ejecutadas: {result.metadata.get('tools_executed')}")
print(f"Servidores conectados: {result.metadata.get('servers_connected')}")
print(f"Tipos de transporte: {result.metadata.get('transport_types')}")
print(f"ID de ejecución: {result.execution_id}")

---

🔧 Servidores MCP Compatibles

Servidores de Producción

• MercadoLibre MCP: Búsqueda y análisis de productos
• LaTeX MCP: Generación de documentos PDF
• Brave Search MCP: Búsqueda web con API de Brave
• Weather MCP: Datos meteorológicos

Servidores de Desarrollo

• FastMCP Test Servers: Servidores en memoria para testing
• Local File MCP: Procesamiento de archivos locales
• Database MCP: Conexión a bases de datos