chatgpt-codex-local-mcp

MCP Server local e seguro para expor contexto de repositorios locais ao ChatGPT/Codex sem entregar um shell generico.

O objetivo do MVP e permitir leitura controlada de projetos locais: listar repositorios permitidos, listar arquivos, ler arquivos de texto, buscar texto, consultar git status, consultar git diff e detectar stack. Escrita fica desabilitada e comandos de teste/lint so aparecem quando MCP_ENABLE_COMMANDS=true.

Status

Implementado:

• Fase 1: discovery local e recomendacao arquitetural.

• Fase 2: MCP read-only com ferramentas pequenas e validacao de paths.

• Transporte local stdio.

• Transporte HTTP Streamable em /mcp para testes locais, tunel seguro ou HTTPS futuro.

• Memoria persistente em docs/memory para continuidade entre sessoes de agentes.

• Ferramentas MCP de leitura segmentada da memoria do projeto.

• Documentacao de seguranca, Tailscale, integracao ChatGPT e roadmap.

Relatorio da Fase 1: docs/discovery.md.

Nao implementado por padrao:

• Escrita de arquivos.

• Atualizacao de memoria via MCP, exceto quando MCP_ENABLE_WRITE=true.

• Shell generico.

• Exposicao publica.

• Comandos de projeto, exceto quando explicitamente habilitados via allowlist.

Related MCP server: codex-web-bridge

Discovery local

Executado em 2026-06-17 nesta maquina:

• macOS: 26.5.1 build 25F80.

• Node.js: v22.22.0.

• npm: 10.9.4.

• pnpm: nao instalado.

• Python: 3.12.2.

• Tailscale: 1.98.5.

• Tailscale IP da maquina: 100.126.171.18.

• Workspace inicial: /Users/fernandodelima/autevia/chatgpt-codex-local-mcp.

• SDK MCP TypeScript escolhido: @modelcontextprotocol/sdk@1.29.0.

Recomendacao: TypeScript com SDK oficial MCP, porque o SDK instalado ja suporta McpServer, StdioServerTransport e StreamableHTTPServerTransport, e a documentacao atual recomenda Streamable HTTP para servidores remotos e stdio para integracoes locais.

Arquitetura

ChatGPT Pro / Codex / MCP client
  |
  | stdio local ou HTTPS / tunnel / Tailscale quando aplicavel
  v
chatgpt-codex-local-mcp
  |
  | ferramentas read-only, paths validados, output limitado
  v
repositorios locais permitidos

Principios:

• O servidor so acessa paths dentro de MCP_ALLOWED_ROOTS.

• Symlinks sao resolvidos antes da autorizacao.

• Arquivos sensiveis como .env, chaves e credenciais sao bloqueados.

• Nao existe run_any_command.

• MCP_ENABLE_WRITE=false por padrao.

• MCP_ENABLE_COMMANDS=false por padrao.

• Logs vao para stderr, para nao quebrar transporte stdio.

• Memoria persistente vive em docs/memory; leitura e segmentada e escrita e restrita a esse diretorio quando explicitamente habilitada.

Configuracao

Copie .env.example para .env e ajuste:

MCP_HOST=127.0.0.1
MCP_PORT=3333
MCP_TRANSPORT=stdio
MCP_AUTH_TOKEN=
MCP_REQUIRE_AUTH=true
MCP_ALLOWED_ROOTS=/Users/fernandodelima/dev,/Users/fernandodelima/projects
MCP_ENABLE_WRITE=false
MCP_ENABLE_COMMANDS=false
MCP_ENABLE_NETWORK=false
MCP_LOG_LEVEL=info
MCP_MAX_FILE_BYTES=200000
MCP_MAX_OUTPUT_BYTES=120000
MCP_COMMAND_TIMEOUT_MS=120000

Se MCP_ALLOWED_ROOTS nao for definido, o servidor usa o diretorio atual como root permitido. Para uso real, defina explicitamente seus diretorios de projetos.

Instalar e rodar

npm install
npm run build
npm test

Modo local via stdio:

npm run dev

Para configurar em um cliente MCP via stdio, prefira apontar para o binario construido, evitando saidas do npm no stdout:

npm run build
MCP_ALLOWED_ROOTS=/Users/fernandodelima/dev node dist/server.js

Modo HTTP local:

MCP_REQUIRE_AUTH=true MCP_AUTH_TOKEN=replace-with-long-random-token npm run dev:http
curl http://127.0.0.1:3333/healthz

Endpoint MCP HTTP:

http://127.0.0.1:3333/mcp

Por padrao, /mcp exige:

Authorization: Bearer <MCP_AUTH_TOKEN>

Somente localhost pode dispensar token, e apenas quando MCP_REQUIRE_AUTH=false for configurado explicitamente. stdio nao e afetado por essa autenticacao HTTP.

Ferramentas MCP

Read-only:

• list_allowed_repositories

• detect_project_stack

• list_project_files

• read_file

• search_in_project

• get_git_status

• get_git_diff

• read_memory_index

• read_onboarding_memory

• read_project_memory

• read_architecture_memory

• read_decisions_memory

• read_backlog_memory

• read_pending_memory

• read_chat_context_memory

• read_references_memory

• read_important_files_memory

Opcional, somente com MCP_ENABLE_COMMANDS=true:

• run_project_command_from_allowlist

Opcional, somente com MCP_ENABLE_WRITE=true:

• update_project_memory

update_project_memory nao aceita paths arbitrarios. Ela so grava arquivos enumerados dentro de docs/memory do projeto informado e exige confirmWrite=true a cada chamada.

Memoria persistente

A memoria do projeto fica em docs/memory. Novos agentes devem comecar por:

1. docs/memory/onboarding.md

2. docs/memory/contexto-chat.md

3. docs/memory/index.md

Ao encerrar trabalhos relevantes, registre um snapshot em docs/memory/sessoes/sessao-XXX.md e mantenha contexto-chat.md curto.

Allowlist atual de comandos:

• git status

• git diff

• mvn test

• mvn -q test

• ./mvnw test

• npm test

• npm run test

• npm run lint

Tailscale

Para manter privado, prefira Tailscale Serve dentro da tailnet em vez de Funnel.

Exemplo para encaminhar um servidor local HTTP:

MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_REQUIRE_AUTH=true \
MCP_AUTH_TOKEN=replace-with-long-random-token npm run dev:http
tailscale serve --https=443 localhost:3333

Isso publica para dispositivos da sua tailnet. Tailscale Funnel torna o servico acessivel pela internet e nao deve ser usado sem revisao explicita.

Veja docs/tailscale.md e docs/exposure-options.md.

ChatGPT

Para ChatGPT Apps/Connectors, a documentacao atual da OpenAI indica que um app usa um MCP server e que o conector precisa de um endpoint HTTPS /mcp. Para desenvolvimento local, a OpenAI documenta Secure MCP Tunnel ou alternativas como ngrok/Cloudflare Tunnel. Veja docs/chatgpt-integration.md.

Referencias

• OpenAI Apps SDK Quickstart: https://developers.openai.com/apps-sdk/quickstart

• OpenAI connect from ChatGPT: https://developers.openai.com/apps-sdk/deploy/connect-chatgpt

• OpenAI developer mode: https://developers.openai.com/api/docs/guides/developer-mode

• OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels

• MCP transport spec: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports

• MCP architecture: https://modelcontextprotocol.io/docs/learn/architecture

• Tailscale Serve: https://tailscale.com/docs/reference/tailscale-cli/serve

• Tailscale Funnel: https://tailscale.com/docs/features/tailscale-funnel