# Expo MCP Server (`tools/expo-mcp`)

[Português](#português) | [English](#english)

---

<a name="português"></a>
## Português

### Visão Geral

O Expo MCP Server é um servidor MCP (Model Context Protocol) local desenvolvido para permitir que assistentes de IA (como Cursor, Claude Desktop ou agentes customizados) inspecionem e diagnostiquem projetos React Native baseados em Expo com segurança, via transporte stdio.

### Funcionalidades

O servidor oferece 4 ferramentas somente leitura:

1. `expo_project_summary`
   Le os arquivos `package.json` e as configurações públicas do Expo, retornando o nome do projeto, versão, versão do Expo, versão do React Native, scripts disponíveis, gerenciador de pacotes identificado pelo lockfile, estrutura de pastas (`android`, `ios`, `app`, `src/app`) e presencas de `expo-router` ou `expo-dev-client`. NUNCA retorna valores de arquivos `.env`.

2. `expo_doctor`
   Executa `npx expo-doctor` e retorna o resultado estruturado (status de sucesso, código de saída, duração em milissegundos, stdout, stderr e flag de timeout).

3. `expo_dependencies_check`
   Executa `npx expo install --check` em modo somente leitura (forçando `CI=1` no processo filho para impedir prompts interativos).

4. `expo_public_config`
   Executa `npx expo config --type public`, faz o parse do JSON e sanitiza o resultado removendo campos sensíveis (como tokens, senhas, chaves e credenciais), além de limitar a profundidade e tamanho total do objeto.

### Arquitetura de Segurança

- **Diretório Raiz Fixo**: O diretório do projeto vem estritamente da variável de ambiente `EXPO_PROJECT_ROOT`. O caminho é resolvido, normalizado e validado. Chamadas que tentem alterar o diretório via argumentos são rejeitadas.
- **Sem Invocação de Shell**: Todos os processos são disparados usando `spawn` com `shell: false`. No Windows, o comando é resolvido com `cmd.exe /c npx`.
- **Lista de Permissões (Allowlist)**: Apenas os comandos predefinidos autorizados podem ser executados pelo runner em `src/runner.ts`.
- **Isolamento de Ambiente**: Variáveis de ambiente sensíveis do sistema operacional (tokens, senhas, chaves) são expurgadas antes de passar o ambiente para o processo filho.
- **Sanitização de Saídas**: Códigos de escape ANSI são removidos, saídas de `stdout` e `stderr` são limitadas a 60.000 caracteres cada, e segredos (como JWTs e credenciais em URLs) são automaticamente redigidos.
- **Canal Exclusivo para Protocolo**: O servidor nunca usa `console.log`, reservando o `stdout` estritamente para o protocolo MCP JSON-RPC. Logs internos usam apenas `console.error`.

### Estrutura do Projeto

```
.cursor/
  mcp.json
tools/
  expo-mcp/
    src/
      tools/
        projectSummary.ts
        doctor.ts
        dependenciesCheck.ts
        publicConfig.ts
      config.ts
      index.ts
      redact.ts
      runner.ts
    test/
      config.test.ts
      redact.test.ts
      runner.test.ts
    AGENTS.md
    README.md
    package.json
    tsconfig.json
    vitest.config.ts
```

### Instalação e Compilação

Navegue até a pasta da ferramenta:

```bash
cd tools/expo-mcp
npm install
npm run build
```

Scripts disponíveis:

- `npm run dev`: Executa os testes em modo watch.
- `npm run build`: Compila o TypeScript para a pasta `dist/`.
- `npm run start`: Inicia o servidor MCP via stdio.
- `npm test`: Executa a suíte de testes automatizados com Vitest.
- `npm run typecheck`: Executa a verificação estática de tipos.
- `npm run inspect`: Abre o MCP Inspector para testar as ferramentas interativamente.

### Integração com o Cursor

Edite ou crie o arquivo `.cursor/mcp.json` na raiz do seu aplicativo:

```json
{
  "mcpServers": {
    "expo-local": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${workspaceFolder}/tools/expo-mcp/dist/index.js"
      ],
      "env": {
        "EXPO_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

---

<a name="english"></a>
## English

### Overview

Expo MCP Server is a secure, local MCP (Model Context Protocol) server designed to allow AI assistants (such as Cursor, Claude Desktop, or custom agents) to inspect and diagnose Expo-based React Native projects safely over stdio transport.

### Features

The server exposes 4 read-only tools:

1. `expo_project_summary`
   Reads `package.json` and public Expo configuration files, returning project name, version, Expo version, React Native version, available scripts, package manager identified by lockfile, directory structure (`android`, `ios`, `app`, `src/app`), and presence of `expo-router` or `expo-dev-client`. NEVER returns `.env` values.

2. `expo_doctor`
   Runs `npx expo-doctor` and returns a structured result (ok status, exit code, duration in milliseconds, stdout, stderr, and timeout flag).

3. `expo_dependencies_check`
   Runs `npx expo install --check` in read-only mode (setting `CI=1` in the child process to prevent interactive prompts).

4. `expo_public_config`
   Runs `npx expo config --type public`, parses the JSON output, and sanitizes sensitive keys (tokens, passwords, keys, credentials), limiting depth and total response size.

### Security Architecture

- **Strict Project Root**: The target project directory comes strictly from the `EXPO_PROJECT_ROOT` environment variable. Paths are resolved, normalized, and validated. Arguments attempting to supply paths are rejected.
- **No Shell Execution**: Processes are spawned with `shell: false`. On Windows, commands are resolved safely via `cmd.exe /c npx`.
- **Command Allowlist**: Only pre-approved commands can be executed by `src/runner.ts`.
- **Environment Isolation**: Sensitive host environment variables (tokens, keys, passwords) are scrubbed before passing environment to child processes.
- **Output Sanitization**: ANSI escape codes are stripped, `stdout` and `stderr` are truncated to 60,000 characters each, and secrets (JWTs, URL credentials) are automatically redacted.
- **Dedicated Transport Channel**: `console.log` is strictly avoided to preserve `stdout` for JSON-RPC MCP messages. Internal logs use `console.error`.

### Installation and Building

Navigate to the tools directory:

```bash
cd tools/expo-mcp
npm install
npm run build
```

Available scripts:

- `npm run dev`: Runs Vitest in watch mode.
- `npm run build`: Compiles TypeScript to `dist/`.
- `npm run start`: Runs the MCP server via stdio.
- `npm test`: Runs the automated test suite with Vitest.
- `npm run typecheck`: Runs static type checking.
- `npm run inspect`: Launches MCP Inspector for interactive testing.

### Cursor Integration

Create or edit `.cursor/mcp.json` in your application root:

```json
{
  "mcpServers": {
    "expo-local": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${workspaceFolder}/tools/expo-mcp/dist/index.js"
      ],
      "env": {
        "EXPO_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```