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.

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:

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