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:

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