mcp-http-starter

Servidor/cliente MCP con integración Ollama y TAVILY para búsquedas web inteligentes. Migrado: Ahora usa transporte HTTP requests en lugar de STDIO. NUEVO: Implementación completa de autenticación OAuth2.

Requisitos

• Python >= 3.12
• Dependencias: fastmcp, ollama, requests, tavily-python, fastapi, uvicorn, authlib, python-jose, passlib

Instalación (con uv)

uv sync

Configuración

Ollama (opcional)

Para usar el procesamiento con IA local:

1. Instalar Ollama: https://ollama.com/download
2. Descargar modelo: ollama pull gpt-oss:20b
3. Ejecutar servidor Ollama: ollama serve

TAVILY API (recomendado)

Para búsquedas web mejoradas:

1. Registrarse en: https://tavily.com
2. Obtener API key gratuita
3. Configurar variable de entorno:

   set TAVILY_API_KEY=tu_api_key_aqui
   

4. Sin API key, usa DuckDuckGo como fallback

Configuración OAuth2 (opcional)

Para habilitar autenticación OAuth2:

1. Configurar variables de entorno (copia env.example a .env):

   # JWT
   JWT_SECRET_KEY=tu_clave_secreta_muy_segura_aqui
   
   # Google OAuth2 (opcional)
   GOOGLE_CLIENT_ID=tu_google_client_id
   GOOGLE_CLIENT_SECRET=tu_google_client_secret
   
   # GitHub OAuth2 (opcional)
   GITHUB_CLIENT_ID=tu_github_client_id
   GITHUB_CLIENT_SECRET=tu_github_client_secret
   

2. Obtener credenciales OAuth2:

   • Google: Google Cloud Console
   • GitHub: GitHub Developer Settings
   • Microsoft: Azure Portal

Scripts

Servidor HTTP

• Servidor HTTP: uv run python src/server.py
• Cliente HTTP: uv run python src/client.py

Clientes de prueba

• Prueba OAuth2: uv run python test_oauth_client.py
• Prueba simple: uv run python test_client_simple.py

Herramientas disponibles

1. datetime_now

Devuelve la fecha y hora actuales en formato ISO-8601 (UTC).

2. web_search

Realiza búsquedas web combinando:

• TAVILY (principal): Optimizada para LLMs, mejor para noticias/deportes
• DuckDuckGo (fallback): Para consultas generales
• Ollama (procesamiento): IA local para análisis de resultados

Parámetros:

• query: Consulta de búsqueda
• model: Modelo de Ollama a usar (por defecto: "gpt-oss:20b")

Servidor HTTP

El servidor HTTP permite acceso mediante requests HTTP:

Características HTTP

• Puerto: 8001 (configurable)
• Endpoints MCP: /mcp (endpoint principal)
• Endpoints adicionales:
  • / - Información del servidor
  • /health - Estado del servidor
  • /tools - Lista de herramientas (sin MCP)
  • /docs - Documentación automática de FastAPI

Uso del servidor HTTP

1. Iniciar servidor:

   uv run python src/server.py
   

2. Probar con cliente:

   uv run python src/client.py
   

3. Acceso directo:

   • Documentación: http://localhost:8001/docs
   • Estado: http://localhost:8001/health
   • Herramientas: http://localhost:8001/tools

Protocolo MCP sobre HTTP

El servidor mantiene compatibilidad completa con el protocolo MCP pero usando HTTP POST:

# Ejemplo de petición MCP HTTP
curl -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "datetime_now",
      "arguments": {}
    }
  }'

Autenticación OAuth2

Características de Seguridad

• ✅ Autenticación OAuth2 con múltiples proveedores
• ✅ JWT tokens para acceso seguro
• ✅ Middleware de autenticación automático
• ✅ Roles de usuario (admin, user, readonly)
• ✅ Scopes de permisos (mcp:read, mcp:write)

Endpoints de Autenticación

• /login - Página de login con proveedores disponibles
• /auth/providers - Lista de proveedores OAuth2 configurados
• /auth/{provider} - Iniciar flujo OAuth2
• /auth/callback/{provider} - Callback OAuth2
• /auth/token - Refrescar tokens
• /auth/me - Información del usuario actual
• /auth/logout - Cerrar sesión

Flujo de Autenticación

1. Visitar: http://localhost:8001/login
2. Seleccionar proveedor (Google, GitHub, Microsoft)
3. Autorizar aplicación en el proveedor
4. Obtener tokens de acceso y refresco
5. Usar token en header: Authorization: Bearer <token>

Ejemplo de Uso

# 1. Obtener token (después de OAuth2)
curl -X POST http://localhost:8001/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "refresh_token", "refresh_token": "..."}'

# 2. Usar token para acceder a MCP
curl -X POST http://localhost:8001/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {"name": "datetime_now", "arguments": {}}
  }'

Estructura

• src/server.py: Servidor MCP HTTP con OAuth2
• src/client.py: Cliente HTTP (migrado de STDIO)
• src/auth_models.py: NUEVO Modelos de datos OAuth2
• src/auth_service.py: NUEVO Servicio de autenticación
• src/auth_middleware.py: NUEVO Middleware de autenticación
• src/logger.py: Sistema de logging rotativo
• logs/: Directorio de logs con rotación automática