repo_Claude/.claude/skills/init-jupyter/SKILL.md

---
name: init-jupyter
description: Inicializa o inicia Jupyter Lab via MCP con kernel compartido. Detecta notebooks existentes automáticamente.
argument-hint: [ruta-proyecto]
disable-model-invocation: true
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob
---

# Inicializar/Iniciar Proyecto Jupyter via MCP

Este skill gestiona entornos Jupyter Lab integrados con Claude via MCP. Detecta automáticamente si ya existe un proyecto configurado.

## Modo de Colaboración (Kernel Compartido)

**IMPORTANTE**: Para que las ejecuciones de Claude sean visibles en Jupyter Lab, se debe usar el **mismo kernel** que el notebook abierto. Esto permite:
- Ver las ejecuciones de Claude en tiempo real en Jupyter Lab
- Compartir variables y estado entre Claude y el usuario
- Colaboración real entre ambos en el mismo notebook

## Flujo de decisión

### 1. Detectar notebooks existentes

Buscar archivos `.ipynb` en:
- Raíz del proyecto
- Carpeta `notebooks/`
- Cualquier subcarpeta

```bash
find [ruta] -name "*.ipynb" -type f 2>/dev/null | head -5
```

### 2. Si HAY notebooks existentes → Iniciar directamente

**2a. Verificar que MCP está configurado con kernel compartido**
- Comprobar si existe `.claude/settings.local.json` con configuración de jupyter
- Verificar que incluye `--start-new-runtime false` para colaboración
- Si no existe o falta la configuración, crearlo (ver paso 3f)

**2b. Verificar que jupyter-mcp-server está instalado**
```bash
which jupyter-mcp-server || uv tool install jupyter-mcp-server
```

**2c. Iniciar Jupyter via MCP**
```bash
source .venv/bin/activate 2>/dev/null || true
jupyter lab --no-browser --NotebookApp.token='' --NotebookApp.password='' --NotebookApp.disable_check_xsrf=True
```

**2d. Informar al usuario** que Jupyter está corriendo y puede usar las herramientas MCP de Jupyter desde Claude.

### 3. Si NO hay notebooks → Inicializar proyecto completo

Seguir estos pasos:

**3a. Validar ubicación**
- Si se proporciona `$1`, usar esa ruta
- Si no, usar el directorio actual

**3b. Inicializar proyecto con uv** (si no existe pyproject.toml)
```bash
cd [ruta] && uv init
```

**3c. Crear entorno virtual**
```bash
uv venv
```

**3d. Instalar dependencias**
```bash
uv add jupyter jupyter-collaboration
```

**3e. Instalar jupyter-mcp-server**
```bash
uv tool install jupyter-mcp-server
```

**3f. Configurar MCP para Claude (con kernel compartido)**
Crear o actualizar `.claude/settings.local.json`:
```json
{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp-server",
      "args": [
        "--jupyter-url", "http://localhost:8888",
        "--start-new-runtime", "false"
      ]
    }
  }
}
```

**Parámetros clave:**
- `--jupyter-url`: URL del servidor Jupyter (por defecto localhost:8888)
- `--start-new-runtime false`: **CRÍTICO** - Conecta al kernel existente en lugar de crear uno nuevo

**3g. Crear carpeta notebooks** (opcional)
```bash
mkdir -p notebooks
```

**3h. Iniciar Jupyter via MCP**
```bash
source .venv/bin/activate
jupyter lab --no-browser --NotebookApp.token='' --NotebookApp.password='' --NotebookApp.disable_check_xsrf=True
```

## Ejemplos de uso

**Iniciar/inicializar en directorio actual:**
```bash
/init-jupyter
```

**Iniciar/inicializar en ruta específica:**
```bash
/init-jupyter ~/proyectos/mi-analisis
```

## Flujo de trabajo colaborativo (Kernel Compartido)

### Cómo funciona la colaboración

1. **Usuario inicia Jupyter Lab** (via este skill)
2. **Usuario abre un notebook** en Jupyter Lab → se inicia un kernel
3. **Claude se conecta al MISMO kernel** via MCP con `--start-new-runtime false`
4. **Ambos comparten**:
   - El mismo estado de variables
   - El mismo historial de ejecución
   - Las salidas son visibles para ambos en tiempo real

### Pasos para colaborar

1. Ejecutar `/init-jupyter` para iniciar Jupyter Lab
2. Abrir el navegador en http://localhost:8888
3. Abrir o crear el notebook deseado
4. **Claude ya puede ejecutar celdas** y el usuario verá las ejecuciones en su Jupyter Lab

### Obtener kernel ID específico (opcional)

Si hay múltiples kernels corriendo, puedes obtener el ID del kernel activo:
```bash
curl -s http://localhost:8888/api/kernels | jq '.[0].id'
```

Y configurar MCP con ese kernel específico:
```json
{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp-server",
      "args": [
        "--jupyter-url", "http://localhost:8888",
        "--runtime-id", "KERNEL_ID_AQUI"
      ]
    }
  }
}
```

## Notas importantes

- **Siempre usa MCP**: Jupyter se ejecuta siempre de forma que Claude pueda interactuar via MCP
- **Kernel compartido por defecto**: Con `--start-new-runtime false`, Claude usa el kernel existente
- Si detecta notebooks existentes, NO reinicializa el proyecto, solo inicia Jupyter
- Si el proyecto ya tiene `pyproject.toml`, no ejecuta `uv init`
- La configuración MCP se guarda en `.claude/settings.local.json` del proyecto
- El servidor MCP permite a Claude crear, editar y ejecutar celdas de notebooks
- **jupyter-collaboration** ya está incluido en las dependencias para sincronización en tiempo real