258
AI_TOOLKIT_SETUP.md
Archivo normal
258
AI_TOOLKIT_SETUP.md
Archivo normal
@@ -0,0 +1,258 @@
|
||||
# Configuración para VS Code AI Toolkit
|
||||
|
||||
## Cómo Configurar el Servidor MCP INE en AI Toolkit
|
||||
|
||||
### Opción 1: HTTP JSON-RPC (Recomendado) 🎯
|
||||
|
||||
1. **Inicia el servidor MCP INE**:
|
||||
```bash
|
||||
cd /home/ale/projects/mcp/mcp-ine
|
||||
npm start
|
||||
```
|
||||
|
||||
2. **Abre VS Code AI Toolkit**:
|
||||
- Presiona `Ctrl+Shift+P` (o `Cmd+Shift+P` en Mac)
|
||||
- Busca: **"AI Toolkit: Configure MCP Servers"**
|
||||
|
||||
3. **Agrega esta configuración**:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ine-spain": {
|
||||
"url": "http://localhost:3000/mcp/v1",
|
||||
"transport": "http",
|
||||
"description": "API del Instituto Nacional de Estadística (INE) de España - 24 herramientas para consultar datos estadísticos"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. **Reinicia AI Toolkit** y verifica que aparezca "ine-spain" con 24 herramientas
|
||||
|
||||
### Opción 2: Server-Sent Events (SSE)
|
||||
|
||||
1. **Inicia el servidor SSE**:
|
||||
```bash
|
||||
cd /home/ale/projects/mcp/mcp-ine
|
||||
npm run start:sse
|
||||
```
|
||||
|
||||
2. **Configuración en AI Toolkit**:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ine-spain-sse": {
|
||||
"url": "http://localhost:3001/sse",
|
||||
"transport": "sse",
|
||||
"description": "API INE España via SSE"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Opción 3: stdio (Comunicación Directa)
|
||||
|
||||
Esta opción NO requiere iniciar el servidor manualmente.
|
||||
|
||||
**Configuración en AI Toolkit**:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ine-spain-stdio": {
|
||||
"command": "node",
|
||||
"args": [
|
||||
"dist/index.js",
|
||||
"--stdio"
|
||||
],
|
||||
"cwd": "/home/ale/projects/mcp/mcp-ine",
|
||||
"description": "API INE España via stdio",
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Verificar que Funciona
|
||||
|
||||
### 1. Verifica el Estado del Servidor (HTTP/SSE)
|
||||
|
||||
```bash
|
||||
# Para HTTP (puerto 3000)
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Para SSE (puerto 3001)
|
||||
curl http://localhost:3001/health
|
||||
```
|
||||
|
||||
Respuesta esperada:
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"timestamp": "2025-10-09T01:02:33.658Z",
|
||||
"service": "MCP INE Server"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Lista las Herramientas Disponibles
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/mcp/v1 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}' \
|
||||
| python3 -m json.tool | grep '"name"' | wc -l
|
||||
```
|
||||
|
||||
Debe devolver: **24** (número de herramientas)
|
||||
|
||||
### 3. Prueba una Consulta Real
|
||||
|
||||
```bash
|
||||
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,
|
||||
"tip":"A"
|
||||
}
|
||||
},
|
||||
"id":1
|
||||
}' | python3 -m json.tool
|
||||
```
|
||||
|
||||
## Ejemplos de Consultas en AI Toolkit
|
||||
|
||||
Una vez configurado, puedes hacer estas preguntas en el chat:
|
||||
|
||||
### Consultas Básicas
|
||||
|
||||
```
|
||||
¿Cuál es el último valor del IPC en España?
|
||||
|
||||
Dame los últimos 12 meses del IPC
|
||||
|
||||
¿Qué operaciones estadísticas tiene disponibles el INE?
|
||||
```
|
||||
|
||||
### Consultas Específicas
|
||||
|
||||
```
|
||||
Obtén los datos de la tabla 50902 de los últimos 5 períodos
|
||||
|
||||
¿Qué variables tiene la operación IPC?
|
||||
|
||||
Lista las series de la operación EPA (Encuesta de Población Activa)
|
||||
```
|
||||
|
||||
### Consultas con Filtros
|
||||
|
||||
```
|
||||
Busca datos del IPC para Madrid (provincia 29) con variación mensual
|
||||
|
||||
Dame los grupos ECOICOP disponibles para el IPC
|
||||
|
||||
¿Cuáles son las provincias de Andalucía en los datos del INE?
|
||||
```
|
||||
|
||||
### Consultas de Metadatos
|
||||
|
||||
```
|
||||
¿Qué periodicidades están disponibles en el INE?
|
||||
|
||||
Lista las publicaciones de la operación IPC
|
||||
|
||||
Dame información detallada sobre la operación del IPC
|
||||
```
|
||||
|
||||
## Solución de Problemas
|
||||
|
||||
### El servidor no aparece en AI Toolkit
|
||||
|
||||
1. Verifica que el servidor esté corriendo:
|
||||
```bash
|
||||
curl http://localhost:3000/health
|
||||
```
|
||||
|
||||
2. Si no responde, inicia el servidor:
|
||||
```bash
|
||||
cd /home/ale/projects/mcp/mcp-ine
|
||||
npm start
|
||||
```
|
||||
|
||||
3. Reinicia VS Code completamente
|
||||
|
||||
4. Verifica la configuración JSON (sin errores de sintaxis)
|
||||
|
||||
### Error "Cannot connect to MCP server"
|
||||
|
||||
1. Comprueba que no haya otro proceso usando el puerto:
|
||||
```bash
|
||||
netstat -tuln | grep 3000
|
||||
```
|
||||
|
||||
2. Si hay otro proceso, mátalo o cambia el puerto:
|
||||
```bash
|
||||
PORT=3005 npm start
|
||||
```
|
||||
|
||||
Y actualiza la URL en la configuración:
|
||||
```json
|
||||
"url": "http://localhost:3005/mcp/v1"
|
||||
```
|
||||
|
||||
### El servidor se cierra solo
|
||||
|
||||
Ejecuta el servidor en modo background o en una terminal separada:
|
||||
|
||||
```bash
|
||||
# Terminal 1: Servidor
|
||||
cd /home/ale/projects/mcp/mcp-ine
|
||||
npm start
|
||||
|
||||
# Terminal 2: VS Code
|
||||
code .
|
||||
```
|
||||
|
||||
O usa `nohup`:
|
||||
```bash
|
||||
nohup npm start > server.log 2>&1 &
|
||||
```
|
||||
|
||||
### Las herramientas no aparecen
|
||||
|
||||
1. Verifica que la URL sea correcta (debe terminar en `/mcp/v1`)
|
||||
2. Verifica que el servidor responda:
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/mcp/v1 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'
|
||||
```
|
||||
3. Revisa los logs del servidor en la terminal
|
||||
|
||||
### Error de certificados SSL (si usas HTTPS)
|
||||
|
||||
Para desarrollo local, usa HTTP (no HTTPS):
|
||||
```json
|
||||
"url": "http://localhost:3000/mcp/v1"
|
||||
```
|
||||
|
||||
## Documentación Adicional
|
||||
|
||||
- **Swagger UI**: http://localhost:3000/api-docs
|
||||
- **README completo**: `/home/ale/projects/mcp/mcp-ine/README.md`
|
||||
- **Guía rápida**: `/home/ale/projects/mcp/mcp-ine/QUICKSTART.md`
|
||||
- **API INE oficial**: https://www.ine.es/dyngs/DataLab/manual.html?cid=45
|
||||
|
||||
## Contacto y Soporte
|
||||
|
||||
- **GitHub Issues**: Para reportar problemas
|
||||
- **Documentación**: Ver README.md y QUICKSTART.md
|
||||
- **API INE**: https://www.ine.es
|
||||
|
||||
---
|
||||
|
||||
💡 **Consejo**: Mantén el servidor corriendo en una terminal separada mientras usas AI Toolkit para evitar interrupciones.
|
||||
Referencia en una nueva incidencia
Block a user