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.

🌟 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

chmod +x install.sh
./install.sh

Instalación manual

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

🎮 Uso

Modo HTTP JSON-RPC (Principal)

Este es el modo recomendado para AI Toolkit:

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:

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:

node dist/index.js --stdio

🔧 Configuración en VS Code AI Toolkit

Opción 1: HTTP JSON-RPC (Recomendado)

Abre VS Code
Instala la extensión AI Toolkit
Inicia el servidor: npm start
En AI Toolkit, configura el servidor MCP:

{
  "mcpServers": {
    "ine-server": {
      "url": "http://localhost:3000/mcp/v1",
      "transport": "http",
      "description": "API del INE España"
    }
  }
}

Opción 2: SSE

{
  "mcpServers": {
    "ine-server-sse": {
      "url": "http://localhost:3001/sse",
      "transport": "sse",
      "description": "API del INE España (SSE)"
    }
  }
}

Opción 3: stdio

{
  "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

{
  "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

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "ine_operaciones_disponibles",
    "arguments": {
      "idioma": "ES",
      "geo": 0
    }
  },
  "id": 2
}

Ejemplo 3: Obtener variables del IPC

{
  "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

# 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

🛡️ 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

# 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

Verifica que el servidor esté corriendo: http://localhost:3000/health
Comprueba que no haya otro proceso usando el puerto 3000
Revisa la configuración MCP en AI Toolkit

Errores de TypeScript

# 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.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
src		src
.gitignore		.gitignore
AI_TOOLKIT_SETUP.md		AI_TOOLKIT_SETUP.md
API.txt		API.txt
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
install.sh		install.sh
mcp-config.json		mcp-config.json
package-lock.json		package-lock.json
package.json		package.json
start-server.sh		start-server.sh
start-sse.sh		start-sse.sh
tsconfig.json		tsconfig.json

License

manalejandro/mcp-ine

Folders and files

Latest commit

History

Repository files navigation