389 líneas
9.1 KiB
Markdown
389 líneas
9.1 KiB
Markdown
# MCP INE Server
|
|
|
|
Servidor MCP (Model Context Protocol) para consultar la API del Instituto Nacional de Estadística (INE) de España. Implementa soporte completo para JSON-RPC sobre HTTP y SSE (Server-Sent Events), optimizado para su uso con VS Code AI Toolkit.
|
|
|
|
## ⚠️ Importante: Datos Disponibles
|
|
|
|
**Este servidor solo proporciona acceso a las estadísticas del INE.** El INE NO incluye datos de criminalidad.
|
|
|
|
**Tipos de datos disponibles:**
|
|
- 📊 Demografía y población
|
|
- 💰 Economía (IPC, PIB, mercado laboral)
|
|
- 🏢 Empresas y comercio
|
|
- 🏘️ Vivienda y construcción
|
|
- 📚 Educación y sociedad
|
|
- 🌾 Agricultura y medio ambiente
|
|
|
|
Para estadísticas de criminalidad en España, consulta el [Portal Estadístico de Criminalidad del Ministerio del Interior](https://estadisticasdecriminalidad.ses.mir.es/).
|
|
|
|
Ver la [guía completa de datos disponibles](./DATOS_DISPONIBLES.md) para más información.
|
|
|
|
## 🌟 Características
|
|
|
|
- ✅ **Protocolo MCP completo**: Soporte para JSON-RPC y SSE
|
|
- ✅ **24 herramientas MCP**: Acceso a todos los endpoints de la API del INE
|
|
- ✅ **Documentación Swagger**: API REST documentada con OpenAPI 3.0
|
|
- ✅ **TypeScript**: Código completamente tipado
|
|
- ✅ **VS Code AI Toolkit**: Configuración lista para usar
|
|
- ✅ **Múltiples transportes**: HTTP JSON-RPC, SSE y stdio
|
|
|
|
## 📋 Requisitos
|
|
|
|
- Node.js 18 o superior
|
|
- npm o yarn
|
|
|
|
## 🚀 Instalación
|
|
|
|
### Instalación rápida
|
|
|
|
```bash
|
|
chmod +x install.sh
|
|
./install.sh
|
|
```
|
|
|
|
### Instalación manual
|
|
|
|
```bash
|
|
# Instalar dependencias
|
|
npm install
|
|
|
|
# Compilar TypeScript
|
|
npm run build
|
|
```
|
|
|
|
## 🎮 Uso
|
|
|
|
### Modo HTTP JSON-RPC (Principal)
|
|
|
|
Este es el modo recomendado para AI Toolkit:
|
|
|
|
```bash
|
|
npm start
|
|
# o
|
|
./start-server.sh
|
|
```
|
|
|
|
El servidor estará disponible en:
|
|
- **Endpoint MCP**: `http://localhost:3000/mcp/v1`
|
|
- **Swagger UI**: `http://localhost:3000/api-docs`
|
|
- **Health Check**: `http://localhost:3000/health`
|
|
|
|
### Modo SSE (Server-Sent Events)
|
|
|
|
Para streaming de eventos:
|
|
|
|
```bash
|
|
npm run start:sse
|
|
# o
|
|
./start-sse.sh
|
|
```
|
|
|
|
El servidor SSE estará en:
|
|
- **Endpoint SSE**: `http://localhost:3001/sse`
|
|
- **Health Check**: `http://localhost:3001/health`
|
|
|
|
### Modo stdio
|
|
|
|
Para integración directa:
|
|
|
|
```bash
|
|
node dist/index.js --stdio
|
|
```
|
|
|
|
## 🔧 Configuración en VS Code AI Toolkit
|
|
|
|
### Opción 1: HTTP JSON-RPC (Recomendado)
|
|
|
|
1. Abre VS Code
|
|
2. Instala la extensión **AI Toolkit**
|
|
3. Inicia el servidor: `npm start`
|
|
4. En AI Toolkit, configura el servidor MCP:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ine-server": {
|
|
"url": "http://localhost:3000/mcp/v1",
|
|
"transport": "http",
|
|
"description": "API del INE España"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Opción 2: SSE
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ine-server-sse": {
|
|
"url": "http://localhost:3001/sse",
|
|
"transport": "sse",
|
|
"description": "API del INE España (SSE)"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Opción 3: stdio
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ine-server-stdio": {
|
|
"command": "node",
|
|
"args": ["dist/index.js", "--stdio"],
|
|
"cwd": "/ruta/a/mcp-ine",
|
|
"description": "API del INE España (stdio)"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🛠️ Herramientas MCP Disponibles
|
|
|
|
El servidor proporciona 24 herramientas MCP para interactuar con la API del INE:
|
|
|
|
### Datos Estadísticos
|
|
|
|
- **`ine_datos_tabla`**: Obtiene datos de una tabla específica
|
|
- **`ine_datos_serie`**: Obtiene datos de una serie temporal
|
|
- **`ine_datos_metadata_operacion`**: Datos con filtros de metadata
|
|
|
|
### Operaciones
|
|
|
|
- **`ine_operaciones_disponibles`**: Lista todas las operaciones estadísticas
|
|
- **`ine_operacion`**: Información de una operación específica
|
|
|
|
### Variables y Valores
|
|
|
|
- **`ine_variables`**: Lista todas las variables disponibles
|
|
- **`ine_variables_operacion`**: Variables de una operación
|
|
- **`ine_valores_variable`**: Valores de una variable
|
|
- **`ine_valores_variable_operacion`**: Valores en contexto de operación
|
|
- **`ine_valores_hijos`**: Valores jerárquicos (ej: provincias de una CA)
|
|
|
|
### Series Temporales
|
|
|
|
- **`ine_serie`**: Información de una serie
|
|
- **`ine_series_operacion`**: Series de una operación
|
|
- **`ine_series_tabla`**: Series de una tabla
|
|
- **`ine_serie_metadata_operacion`**: Búsqueda con filtros
|
|
- **`ine_valores_serie`**: Variables que definen una serie
|
|
|
|
### Tablas
|
|
|
|
- **`ine_tablas_operacion`**: Tablas de una operación
|
|
- **`ine_grupos_tabla`**: Grupos de una tabla
|
|
- **`ine_valores_grupos_tabla`**: Valores de un grupo
|
|
|
|
### Metadatos
|
|
|
|
- **`ine_periodicidades`**: Periodicidades disponibles
|
|
- **`ine_publicaciones`**: Lista de publicaciones
|
|
- **`ine_publicaciones_operacion`**: Publicaciones de una operación
|
|
- **`ine_publicacion_fecha_publicacion`**: Fechas de publicación
|
|
- **`ine_clasificaciones`**: Clasificaciones disponibles
|
|
- **`ine_clasificaciones_operacion`**: Clasificaciones de una operación
|
|
|
|
## 📖 Ejemplos de Uso
|
|
|
|
### Ejemplo 1: Obtener datos del IPC
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "tools/call",
|
|
"params": {
|
|
"name": "ine_datos_serie",
|
|
"arguments": {
|
|
"idSerie": "IPC251856",
|
|
"nult": 12,
|
|
"tip": "A"
|
|
}
|
|
},
|
|
"id": 1
|
|
}
|
|
```
|
|
|
|
### Ejemplo 2: Listar operaciones disponibles
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "tools/call",
|
|
"params": {
|
|
"name": "ine_operaciones_disponibles",
|
|
"arguments": {
|
|
"idioma": "ES",
|
|
"geo": 0
|
|
}
|
|
},
|
|
"id": 2
|
|
}
|
|
```
|
|
|
|
### Ejemplo 3: Obtener variables del IPC
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "tools/call",
|
|
"params": {
|
|
"name": "ine_variables_operacion",
|
|
"arguments": {
|
|
"idOperacion": "IPC"
|
|
}
|
|
},
|
|
"id": 3
|
|
}
|
|
```
|
|
|
|
### Desde AI Toolkit (Chat)
|
|
|
|
Una vez configurado en AI Toolkit, puedes hacer preguntas como:
|
|
|
|
```
|
|
¿Cuál es el último valor del IPC en España?
|
|
|
|
¿Qué operaciones estadísticas tiene el INE sobre población?
|
|
|
|
Dame los datos de la tabla 50902 de los últimos 5 períodos
|
|
|
|
¿Cuáles son las variables disponibles para la operación IPC?
|
|
```
|
|
|
|
## 🌐 API REST
|
|
|
|
Además del protocolo MCP, el servidor expone endpoints REST:
|
|
|
|
- `GET /api/datos-tabla/:idTabla` - Datos de tabla
|
|
- `GET /api/datos-serie/:idSerie` - Datos de serie
|
|
- `GET /api/operaciones-disponibles` - Listar operaciones
|
|
- `GET /api/operacion/:idOperacion` - Info de operación
|
|
- `GET /api/variables` - Listar variables
|
|
- `GET /api/variables-operacion/:idOperacion` - Variables de operación
|
|
- `GET /api/series-operacion/:idOperacion` - Series de operación
|
|
- `GET /api/tablas-operacion/:idOperacion` - Tablas de operación
|
|
|
|
Documentación completa en: `http://localhost:3000/api-docs`
|
|
|
|
## 📝 Parámetros Comunes
|
|
|
|
### Idioma
|
|
- `ES`: Español (por defecto)
|
|
- `EN`: Inglés
|
|
|
|
### Nivel de Detalle (det)
|
|
- `0`: Básico
|
|
- `1`: Medio
|
|
- `2`: Completo
|
|
|
|
### Tipo de Respuesta (tip)
|
|
- `A`: Amigable (legible)
|
|
- `M`: Con metadatos
|
|
- `AM`: Amigable con metadatos
|
|
|
|
### Periodicidad (p)
|
|
- `1`: Mensual
|
|
- `3`: Trimestral
|
|
- `6`: Semestral
|
|
- `12`: Anual
|
|
|
|
## 🔍 Ejemplos de Consultas desde curl
|
|
|
|
```bash
|
|
# Obtener últimos datos del IPC
|
|
curl -X POST http://localhost:3000/mcp/v1 \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"jsonrpc": "2.0",
|
|
"method": "tools/call",
|
|
"params": {
|
|
"name": "ine_datos_serie",
|
|
"arguments": {"idSerie": "IPC251856", "nult": 1}
|
|
},
|
|
"id": 1
|
|
}'
|
|
|
|
# Listar herramientas disponibles
|
|
curl -X POST http://localhost:3000/mcp/v1 \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"jsonrpc": "2.0",
|
|
"method": "tools/list",
|
|
"params": {},
|
|
"id": 1
|
|
}'
|
|
```
|
|
|
|
## 📚 Recursos
|
|
|
|
- [API del INE - Documentación oficial](https://www.ine.es/dyngs/DataLab/manual.html?cid=45)
|
|
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
- [VS Code AI Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)
|
|
|
|
## 🛡️ Estructura del Proyecto
|
|
|
|
```
|
|
mcp-ine/
|
|
├── src/
|
|
│ ├── index.ts # Servidor principal (HTTP JSON-RPC)
|
|
│ ├── server-sse.ts # Servidor SSE
|
|
│ ├── swagger.ts # Especificación OpenAPI
|
|
│ ├── types/
|
|
│ │ └── ine.types.ts # Tipos TypeScript
|
|
│ └── services/
|
|
│ └── ine-client.ts # Cliente HTTP para API INE
|
|
├── dist/ # Código compilado
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── mcp-config.json # Configuración para AI Toolkit
|
|
├── install.sh # Script de instalación
|
|
├── start-server.sh # Iniciar servidor HTTP
|
|
├── start-sse.sh # Iniciar servidor SSE
|
|
└── README.md
|
|
```
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### El servidor no inicia
|
|
|
|
```bash
|
|
# Limpiar y reinstalar
|
|
npm run clean
|
|
rm -rf node_modules package-lock.json
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
### Error de conexión en AI Toolkit
|
|
|
|
1. Verifica que el servidor esté corriendo: `http://localhost:3000/health`
|
|
2. Comprueba que no haya otro proceso usando el puerto 3000
|
|
3. Revisa la configuración MCP en AI Toolkit
|
|
|
|
### Errores de TypeScript
|
|
|
|
```bash
|
|
# Reinstalar tipos
|
|
npm install --save-dev @types/node @types/express
|
|
npm run build
|
|
```
|
|
|
|
## 📄 Licencia
|
|
|
|
MIT
|
|
|
|
## 🤝 Contribuciones
|
|
|
|
Las contribuciones son bienvenidas. Por favor, abre un issue o pull request.
|
|
|
|
## 📧 Soporte
|
|
|
|
Para reportar problemas o sugerencias, abre un issue en el repositorio.
|
|
|
|
---
|
|
|
|
Desarrollado con ❤️ para facilitar el acceso a los datos estadísticos del INE de España.
|