mcp-styledbook/EXEMPLO_NPX.md

Model Context Protocol para criação de ebooks estilizados com pesquisa profunda e formatação visual impactante

# 🚀 Usando MCP StyledBook via NPX (Sem Instalação Local)

Este guia demonstra como usar o MCP StyledBook em **Cursor, Trae ou Windsurf** sem precisar instalar absolutamente nada localmente.

## 📋 Pré-requisitos

- Node.js instalado (versão 14.0.0 ou superior)
- Uma ferramenta compatível com MCP (Cursor, Trae ou Windsurf)

## 🧰 Instalação Express (Recomendado)

Para uma instalação rápida e sem complicações, use os scripts automáticos:

### Windows
Execute o arquivo `mcp-install-windows.bat` com duplo clique ou via linha de comando:
```cmd
mcp-install-windows.bat
```

### macOS / Linux
Execute o arquivo `mcp-install-unix.sh`:
```bash
chmod +x mcp-install-unix.sh
./mcp-install-unix.sh
```

## 🔄 Método Manual: Configuração via arquivo JSON

### Windows

1. Crie um arquivo `.cursor\mcp.json` em `C:\Users\SEU_USUARIO\.cursor\mcp.json`
```cmd
mkdir %USERPROFILE%\.cursor
notepad %USERPROFILE%\.cursor\mcp.json
```

2. Adicione o seguinte conteúdo:
```json
{
  "mcpServers": {
    "styledbook": {
      "command": "cmd",
      "args": ["/c", "npx -y mcp-styledbook --transport=stdio"],
      "env": {
        "NODE_OPTIONS": "--no-warnings"
      }
    }
  }
}
```

### macOS / Linux

1. Crie um arquivo `.cursor/mcp.json` em sua pasta home:
```bash
mkdir -p ~/.cursor
nano ~/.cursor/mcp.json
```

2. Adicione o seguinte conteúdo:
```json
{
  "mcpServers": {
    "styledbook": {
      "command": "npx",
      "args": ["-y", "mcp-styledbook", "--transport=stdio"],
      "env": {
        "NODE_OPTIONS": "--no-warnings"
      }
    }
  }
}
```

## 📂 Configuração por Projeto (Alternativa)

Para usar apenas em um projeto específico:

1. Na raiz do seu projeto, crie uma pasta `.cursor`:
```bash
mkdir -p .cursor
```

2. Crie um arquivo `mcp.json` dentro dela com o conteúdo:
```json
{
  "mcpServers": {
    "styledbook": {
      "command": "npx",
      "args": ["-y", "mcp-styledbook", "--transport=stdio"],
      "env": {
        "NODE_OPTIONS": "--no-warnings"
      }
    }
  }
}
```

## 🖥️ Configuração para outras ferramentas

### Trae

1. Abra o Trae e vá em Configurações > MCP
2. Adicione um novo servidor com:
   - Tipo: comando
   - Comando: `npx`
   - Argumentos: `-y mcp-styledbook --transport=stdio`

### Windsurf

1. Abra o Windsurf e vá em Configurações > Cascade > MCP
2. Adicione um novo servidor com:
   - Nome: StyledBook
   - Comando: `npx`
   - Argumentos: `-y mcp-styledbook --transport=stdio`

## 🌐 Método de Teste via HTTP (Alternativo)

Para verificar se tudo está funcionando corretamente:

```bash
# Em um terminal separado
npx mcp-styledbook --transport=http
```

O servidor será iniciado na porta 3001 e você verá uma mensagem confirmando.

Configure temporariamente nas ferramentas:
- URL: `http://localhost:3001/mcp`

## 🔍 Verificando se está funcionando

Para verificar se o MCP está corretamente configurado:

1. Abra o Cursor (ou outra ferramenta)
2. Faça uma pergunta como:
   ```
   Use o StyledBook para criar um ebook sobre café com 2 capítulos.
   ```

3. O modelo deverá responder que usará as ferramentas do MCP e iniciar o processo.

## 🚨 Solução de Problemas Comuns

### 1. MCP não aparece na lista de servidores

- **Sintoma**: O MCP não aparece na lista de servidores disponíveis.
- **Solução**: Verifique se o arquivo `mcp.json` está no local correto e reinicie completamente a aplicação.

### 2. Erro "Command not found" no Windows

- **Sintoma**: Erro indicando que `npx` não foi encontrado.
- **Solução**: Use a configuração com `cmd`:
  ```json
  "command": "cmd",
  "args": ["/c", "npx -y mcp-styledbook --transport=stdio"]
  ```

### 3. Porta já em uso

- **Sintoma**: Erro indicando que a porta 3001 já está em uso.
- **Solução**: Especifique uma porta diferente:
  ```bash
  npx mcp-styledbook --port=3002
  ```

### 4. Cursor abre o arquivo mcp.json em vez de mostrar o modal de configuração

- **Sintoma**: Ao clicar em "Add new global MCP server", o Cursor abre o arquivo JSON.
- **Solução**: Este é um bug conhecido em algumas versões do Cursor. Edite o arquivo manualmente conforme instruções acima.

### 5. Ferramenta não responde (timeout)

- **Sintoma**: A ferramenta não responde ou dá timeout.
- **Solução**: Verifique se o Node.js está atualizado e tente usar o modo HTTP para debug.

## 🌟 Dicas de Uso

- Sempre reinicie o Cursor/Trae/Windsurf após alterar a configuração MCP.
- Use prompts específicos mencionando as ferramentas do StyledBook.
- O modo STDIO é mais estável para uso diário; o modo HTTP é melhor para debugging.
- Se estiver tendo problemas, verifique os logs do Cursor/Trae/Windsurf.