Expo MCP Server (tools/expo-mcp)

Português | 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:

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:

{
  "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:

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:

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