README.md•5.43 kB
# 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)
```bash
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:
```bash
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`):
```bash
# 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](https://console.cloud.google.com/)
- **GitHub**: [GitHub Developer Settings](https://github.com/settings/applications/new)
- **Microsoft**: [Azure Portal](https://portal.azure.com/)
## 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**:
```bash
uv run python src/server.py
```
2. **Probar con cliente**:
```bash
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:
```bash
# 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
```bash
# 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