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)

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:

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

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