# Jupyter AI MCP para Codex

Projeto reproduzivel para executar JupyterLab e expor suas ferramentas ao Codex por MCP.
As dependencias Python sao gerenciadas exclusivamente pelo `uv`.

## Requisitos

- `uv`
- Python 3.10 ou superior (o `uv` pode instala-lo)
- Codex Desktop, CLI ou extensao para VS Code
- Docker Desktop, apenas se voce escolher a execucao em container

## Execucao no WSL2 recomendada

Uma pasta localizada em `D:\Projetos\jupyter-ai-mcp-codex`, por exemplo, aparece no
WSL2 como `/mnt/d/Projetos/jupyter-ai-mcp-codex`.

Depois de copiar este projeto para a unidade `D:`, abra o WSL2 e execute:

```bash
cd /mnt/d/Projetos/jupyter-ai-mcp-codex
bash scripts/start-local.sh
```

O script usa exclusivamente caminhos relativos ao proprio projeto, executa
`uv sync --frozen` a partir do `uv.lock` e cria um novo `.venv` local. Nenhum caminho do
OneDrive ou do usuario original fica incorporado ao ambiente.

Se o `uv` ainda nao estiver instalado na distribuicao WSL2, siga a instalacao oficial
do `uv` e depois execute o script novamente.

> Para melhor desempenho com muitos arquivos pequenos, o filesystem nativo do WSL2
> costuma ser mais rapido que `/mnt/d`. O uso em `D:` continua valido e e adequado
> quando a prioridade e manter os arquivos visiveis para o Windows.

## Execucao local no Windows

No PowerShell, dentro desta pasta:

```powershell
.\scripts\start-local.ps1
```

O script executa `uv sync --frozen` e inicia:

- JupyterLab: `http://127.0.0.1:8888`
- MCP: `http://127.0.0.1:3001/mcp`

Mantenha o terminal aberto. A URL do JupyterLab com o token de acesso sera exibida no log.

## Execucao com Docker

```powershell
.\scripts\start-docker.ps1
```

Ou diretamente:

```powershell
docker compose up --build
```

As portas sao publicadas somente no loopback da maquina. Os notebooks ficam persistidos em
`notebooks/`, dentro da propria pasta do projeto.

Para encerrar:

```powershell
docker compose down
```

## Conexao com o Codex

Este projeto inclui `.codex/config.toml` com o servidor:

```toml
[mcp_servers.jupyter-mcp]
url = "http://127.0.0.1:3001/mcp"
```

Abra a copia localizada na unidade `D:` como projeto confiavel no Codex e reinicie o
Codex depois de iniciar o JupyterLab. A configuracao e local ao projeto; ela nao altera
a configuracao global em `~/.codex/config.toml`.

Se o Codex estiver rodando no Windows e o Jupyter no WSL2, teste primeiro
`http://127.0.0.1:3001/mcp`. O script WSL2 faz o MCP escutar em `0.0.0.0` dentro da
distribuicao, e o encaminhamento de `localhost` do WSL2 normalmente torna a porta
acessivel no Windows. A configuracao fornecida ja usa esse endereco. Nao publique a
porta `3001` no roteador nem abra uma regra ampla no Firewall do Windows.

## Verificacao

Confira se o MCP esta ouvindo:

```powershell
Test-NetConnection 127.0.0.1 -Port 3001
```

O resultado esperado e `TcpTestSucceeded : True`. Depois, no Codex, solicite que ele leia
ou execute `notebooks/verificacao.ipynb` usando as ferramentas do Jupyter MCP.

No WSL2, a verificacao equivalente e:

```bash
curl --silent --output /dev/null --write-out '%{http_code}\n' \
  http://127.0.0.1:3001/mcp
```

O endpoint MCP pode responder que uma requisicao MCP valida e necessaria; isso ainda
confirma que o servidor HTTP esta acessivel. Os logs do Jupyter devem exibir
`MCP server started on port 3001`.