# OPTA API Documentation MCP Server
Un servidor MCP (Model Context Protocol) para consultar la documentación de la API de fútbol de OPTA.
## Características
- 🔐 **Autenticación automática** con las credenciales de OPTA
- 🔍 **Búsqueda inteligente** en toda la documentación
- 📚 **Cache de documentación** para mejorar el rendimiento
- 🛠️ **Herramientas MCP** para consultar endpoints específicos
- 🔄 **Actualización automática** del cache cada 24 horas
- 🚀 **Listo para despliegue** en Render con configuración automática
- 📖 **Documentación completa** de endpoints con ejemplos
## Instalación
1. Clona el repositorio:
```bash
git clone https://github.com/sportsanalytics-world/OPTA_api_docs.git
cd OPTA_api_docs
```
2. Instala las dependencias:
```bash
npm install
```
3. Configura las variables de entorno:
```bash
cp env.example .env
```
Edita el archivo `.env` con tus credenciales de OPTA:
```env
OPTA_USERNAME=tu_usuario_aqui
OPTA_PASSWORD=tu_password_aqui
OPTA_DOCS_BASE_URL=https://docs.performgroup.com
```
## Uso
### Desarrollo
```bash
npm run dev
```
### Producción
```bash
npm run build
npm start
```
### Procesar Endpoints
```bash
npm run process:endpoints
```
## Herramientas MCP Disponibles
### `get_endpoint_documentation`
Obtiene la documentación HTML de un endpoint específico de OPTA y responde preguntas sobre ella.
**Parámetros:**
- `endpoint_code` (string): Código del endpoint (ej: MA13, MA1, PE2, etc.)
- `question` (string): Pregunta sobre la documentación del endpoint
**Ejemplo:**
```json
{
"endpoint_code": "MA13",
"question": "What is the overview of this endpoint?"
}
```
## Configuración en Cursor
Para usar este servidor MCP en Cursor, agrega la siguiente configuración a tu `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"opta-api-docs": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"OPTA_USERNAME": "tu_usuario",
"OPTA_PASSWORD": "tu_password"
}
}
}
}
```
## Despliegue en Render
El proyecto incluye configuración automática para despliegue en Render:
1. **Conecta tu repositorio** a Render
2. **Render detectará automáticamente** el `render.yaml`
3. **Configura las variables de entorno** en Render:
- `OPTA_USERNAME`: Tu usuario de OPTA
- `OPTA_PASSWORD`: Tu contraseña de OPTA
- `OPTA_DOCS_BASE_URL`: Ya configurado
### Configuración de Render (`render.yaml`)
```yaml
services:
- type: web
name: opta-api-docs-mcp
env: node
buildCommand: npm install && npm run build
startCommand: npm start
envVars:
- key: NODE_ENV
value: production
- key: OPTA_USERNAME
sync: false
- key: OPTA_PASSWORD
sync: false
- key: OPTA_DOCS_BASE_URL
value: https://docs.performgroup.com/docs/rh/sdapi
autoDeploy: true
```
## Estructura del Proyecto
```
src/
├── index.ts # Punto de entrada
├── mcpServer.ts # Servidor MCP principal
├── types/
│ └── index.ts # Definiciones de tipos TypeScript
├── services/
│ ├── optaScraper.ts # Servicio para scrapear OPTA
│ └── documentationManager.ts # Gestor de documentación y cache
└── scripts/
├── processOptaEndpoints.ts # Procesamiento de endpoints
└── discoverEndpoints.ts # Descubrimiento de endpoints
```
## Endpoints Conocidos
El servidor incluye los siguientes endpoints de OPTA:
- **MA13 - Soccer API Possession Events**: Eventos de posesión en fútbol
- **MA3 - Soccer API Match Events**: Eventos de partidos de fútbol
- **MA12 - Soccer API Match Expected Goals**: Expected Goals de partidos
- **MA6 - Soccer API Commentary**: Comentarios automáticos y manuales
- **MA1 - Soccer API Fixtures and Results**: Fixtures y resultados
## Ejemplos de Uso
### Consultar Documentación de un Endpoint
```bash
# Obtener overview de MA13
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "get_endpoint_documentation",
"arguments": {
"endpoint_code": "MA13",
"question": "What is the overview of this endpoint?"
}
}
}'
```
## Desarrollo
### Agregar Nuevos Endpoints
Para agregar nuevos endpoints, edita el archivo `src/services/optaScraper.ts` y agrega las URLs en el array `knownEndpoints`.
### Personalizar Búsqueda
Puedes modificar la lógica de búsqueda en `src/services/documentationManager.ts` para ajustar los pesos de relevancia.
### Scripts Disponibles
- `npm run build`: Compila el proyecto TypeScript
- `npm run dev`: Ejecuta en modo desarrollo
- `npm start`: Ejecuta en modo producción
- `npm run process:endpoints`: Procesa y actualiza los endpoints
## Troubleshooting
### Error de Autenticación
- Verifica que las credenciales en `.env` sean correctas
- Asegúrate de que tu cuenta tenga acceso a la documentación de OPTA
### Error de Conexión
- Verifica tu conexión a internet
- Comprueba que la URL base sea accesible
### Cache No Se Actualiza
- Usa la herramienta `refresh_documentation_cache` para forzar una actualización
- Verifica el estado del cache con `get_cache_status`
### Error de MCP Server
- Verifica que el servidor esté corriendo: `npm start`
- Comprueba los logs del servidor
- Asegúrate de que las dependencias estén actualizadas: `npm install`
## Tecnologías Utilizadas
- **Node.js**: Runtime de JavaScript
- **TypeScript**: Lenguaje de programación tipado
- **@modelcontextprotocol/sdk**: SDK para servidores MCP
- **Axios**: Cliente HTTP
- **Cheerio**: Parser HTML
- **Zod**: Validación de esquemas
## Licencia
MIT
