# 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](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

```text
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:

```bash
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

```bash
npm install
npm run build
npm test
```

Modo local via stdio:

```bash
npm run dev
```

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

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

Modo HTTP local:

```bash
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:

```text
http://127.0.0.1:3333/mcp
```

Por padrao, `/mcp` exige:

```text
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](docs/memory). Novos agentes devem
comecar por:

1. [docs/memory/onboarding.md](docs/memory/onboarding.md)
2. [docs/memory/contexto-chat.md](docs/memory/contexto-chat.md)
3. [docs/memory/index.md](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:

```bash
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](docs/tailscale.md) e
[docs/exposure-options.md](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](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