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:
- Instalar Ollama: https://ollama.com/download
- Descargar modelo:
ollama pull gpt-oss:20b - Ejecutar servidor Ollama:
ollama serve
TAVILY API (recomendado)
Para búsquedas web mejoradas:
- Registrarse en: https://tavily.com
- Obtener API key gratuita
- Configurar variable de entorno:
set TAVILY_API_KEY=tu_api_key_aqui - Sin API key, usa DuckDuckGo como fallback
Configuración OAuth2 (opcional)
Para habilitar autenticación OAuth2:
-
Configurar variables de entorno (copia
env.examplea.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 -
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úsquedamodel: 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
-
Iniciar servidor:
uv run python src/server.py -
Probar con cliente:
uv run python src/client.py -
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
- Visitar:
http://localhost:8001/login - Seleccionar proveedor (Google, GitHub, Microsoft)
- Autorizar aplicación en el proveedor
- Obtener tokens de acceso y refresco
- 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 OAuth2src/client.py: Cliente HTTP (migrado de STDIO)src/auth_models.py: NUEVO Modelos de datos OAuth2src/auth_service.py: NUEVO Servicio de autenticaciónsrc/auth_middleware.py: NUEVO Middleware de autenticaciónsrc/logger.py: Sistema de logging rotativologs/: Directorio de logs con rotación automática