Implement durable OAuth MCP bridge with local Codex worker and deployment guides

2026-11-05 21:34:11 +00:00 · 2026-10-14 18:42:41 -03:00
commit 29fcf73c83
39 changed files with 4130 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,113 @@
+# codex-chatgpt-mcp-proxy
+
+Ponte pessoal entre um cliente MCP (incluindo ChatGPT) e o Codex CLI em um computador
+residencial. O computador só inicia conexões HTTPS de saída. As tarefas retornam um ID;
+status e resultados são consultados depois, sem prometer notificações espontâneas.
+
+```mermaid
+flowchart LR
+    ChatGPT -->|HTTPS /mcp + OAuth| Cloud[Servidor FastAPI + SDK MCP]
+    Cloud --> DB[(SQLite persistente)]
+    Worker[Worker residencial] -->|HTTPS polling + token separado| Cloud
+    Worker --> Journal[(Journal / outbox local)]
+    Worker -->|stdio JSON RPC| Codex[Codex App Server dedicado]
+    Codex --> Demo[Workspace local autorizado]
+    Owner[Proprietário no PC] -->|aprovações locais| Journal
+    IdP[Provedor OAuth estabelecido] -->|JWT RS256 + JWKS| Cloud
+```
+
+## Início rápido local
+
+Requer Python 3.12 e Codex CLI autenticado. Protocolo validado com Codex 0.162.1.
+Não altera Codex, Node, autenticação ou configurações globais. Node não é dependência
+do código Python; o SDK oficial MCP 2.3.0 está fixado no lockfile.
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install uv==0.8.22
+.venv/bin/uv sync --locked
+.venv/bin/python examples/local_env.py
+set -a
+source private/local.env
+set +a
+.venv/bin/codex-bridge server
+```
+
+Em outro terminal, na mesma pasta:
+
+```bash
+set -a
+source private/local.env
+set +a
+.venv/bin/codex-bridge worker
+```
+
+Em um terceiro terminal:
+
+```bash
+set -a
+source private/local.env
+set +a
+.venv/bin/python examples/smoke_real.py
+```
+
+O smoke usa um cliente MCP real, chama o Codex real, retoma a thread em um novo processo
+App Server e verifica um arquivo inofensivo em `demo/`. Isto **não comprova** uma chamada
+originada no ChatGPT. O modelo do exemplo é `gpt-6-luna`; configure um modelo disponível
+na sua instalação se necessário. `model/list` confirma disponibilidade sem inferência.
+Se a sandbox da sessão hospedeira bloquear o processo Codex, execute o worker no seu
+terminal normal mantendo a sandbox própria do Codex e as aprovações.
+
+## Ferramentas
+
+| Ferramenta | Efeito |
+|---|---|
+| `bridge_status` | Disponibilidade, workspaces públicos, versão e contagem da fila |
+| `submit_task` | Submissão rápida idempotente; pode alterar arquivos localmente |
+| `get_task` | Estado, histórico, resultado, erro e IDs Codex |
+| `get_task_events` | Eventos limitados e paginação incremental |
+| `continue_task` | Novo turno na mesma thread; rejeita continuação concorrente |
+| `cancel_task` | Solicita interrupção; não desfaz alterações |
+| `list_tasks` | Listagem paginada e filtro por estado |
+
+Submissões recebem `instruction`, `workspace`, `idempotency_key` e opcionalmente
+`timeout_seconds`. O workspace é um identificador previamente autorizado; caminhos
+arbitrários e uma ferramenta genérica de shell não são expostos.
+
+## Produção
+
+1. Configure `.env` a partir de `.env.example`, mantendo segredos fora do Git.
+2. Configure um provedor OAuth estabelecido com PKCE S256, proprietário e audiência.
+3. Inspecione o proxy existente e preencha rede, entrada TLS e certificate resolver.
+4. Aponte o DNS público à VM e confirme certificados e HTTPS.
+5. Execute `docker compose --env-file .env up -d --build --wait --wait-timeout 90`.
+6. Configure o worker com URL HTTPS e token separado, usando apenas a demo inicialmente.
+7. Cadastre `/mcp` no ChatGPT com OAuth e teste a partir do ChatGPT.
+
+A configuração de produção falha se os dados OAuth estiverem ausentes. Não há porta
+publicada pelo Compose; Traefik acessa o container pela rede interna existente.
+A aplicação ignora **todos** os headers encaminhados; metadata e audiência vêm da URL
+configurada, e Host/Origin são verificados. A confiança nesses headers é, portanto, vazia.
+
+## Documentação
+
+- [Decisões e protocolo verificado](DECISOES.md)
+- [API worker](API_WORKER.md)
+- [Estados e recuperação](ESTADOS.md)
+- [Autenticação e Keycloak](AUTENTICACAO.md)
+- [Instalação na VM e no Ubuntu](OPERACAO.md)
+- [Cadastro e teste no ChatGPT](CHATGPT.md)
+- [Limitações e segurança](SEGURANCA.md)
+- [Validação executada](VALIDACAO.md)
+
+## Testes
+
+```bash
+.venv/bin/pytest -q
+.venv/bin/ruff check src tests examples
+.venv/bin/ruff format --check src tests examples
+```
+
+Um proprietário, um worker, uma tarefa ativa, SQLite local ao servidor e polling com
+jitter/backoff. Não há garantia de exactly-once. Reservas expiradas **não** iniciam uma
+segunda execução: ficam em reconciliação. Resultados finais podem ser reenviados.