mcp-styledbook/SOLUCAO_PROBLEMAS.md

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

# 🛠️ Solução de Problemas - MCP StyledBook

Este guia foi criado para ajudar a resolver problemas comuns na configuração e uso do MCP StyledBook em diferentes sistemas operacionais.

## 📋 Requisitos básicos

- Node.js versão 14.0.0 ou superior
- Acesso para criar/modificar arquivos nas pastas do seu usuário
- Uma ferramenta que suporte MCP (Cursor, Trae, Windsurf, Claude Desktop)

## 🔥 Problemas Comuns em Todos os Sistemas

### MCP não é detectado pela ferramenta

**Sintoma**: O MCP StyledBook não aparece na lista de ferramentas disponíveis no Claude/GPT.

**Soluções**:
1. Verifique se o arquivo `.cursor/mcp.json` está no local correto
2. Verifique se o formato do JSON está correto (sem erros de sintaxe)
3. Reinicie completamente a ferramenta (Cursor/Trae/Windsurf)
4. Tente executar o MCP manualmente para ver se há erros:
   ```bash
   npx mcp-styledbook --transport=stdio
   ```

### Timeout ao tentar usar ferramentas

**Sintoma**: O modelo tenta usar as ferramentas do MCP mas ocorre timeout.

**Soluções**:
1. Verifique sua conexão com a internet
2. Confirme se o NPM está conseguindo baixar pacotes:
   ```bash
   npm ping
   ```
3. Tente instalar globalmente e usar o caminho absoluto:
   ```bash
   npm install -g mcp-styledbook
   ```
   E então modifique o mcp.json para apontar para a instalação global.

## 🪟 Windows - Problemas Específicos

### Erro "npx não é reconhecido como um comando"

**Sintoma**: Erro indicando que o comando `npx` não é reconhecido.

**Soluções**:
1. Verifique se o Node.js está instalado e no PATH:
   ```cmd
   node --version
   npm --version
   ```
2. Use a configuração com cmd.exe:
   ```json
   {
     "mcpServers": {
       "styledbook": {
         "command": "cmd",
         "args": ["/c", "npx -y mcp-styledbook --transport=stdio"]
       }
     }
   }
   ```
3. Instale globalmente e use o caminho completo:
   ```cmd
   npm install -g mcp-styledbook
   where mcp-styledbook
   ```
   Use o caminho completo retornado no arquivo mcp.json.

### Interface gráfica do Cursor não funciona

**Sintoma**: Ao clicar em "Add new global MCP server", o Cursor abre um arquivo JSON em branco.

**Solução**: Este é um bug conhecido em algumas versões do Cursor no Windows. Crie manualmente o arquivo `%USERPROFILE%\.cursor\mcp.json` com o conteúdo correto.

## 🍎 macOS - Problemas Específicos

### Permissões negadas ao criar arquivos

**Sintoma**: Erro de permissão ao tentar criar o arquivo mcp.json.

**Soluções**:
1. Verifique as permissões da pasta:
   ```bash
   ls -la ~/.cursor
   ```
2. Crie a pasta se não existir:
   ```bash
   mkdir -p ~/.cursor
   ```
3. Ajuste as permissões se necessário:
   ```bash
   chmod 755 ~/.cursor
   ```

### Problemas com instalação global do npm

**Sintoma**: Erros ao tentar usar npm install -g.

**Soluções**:
1. Use npx diretamente (não precisa de instalação global)
2. Se precisar instalar globalmente, corrija as permissões:
   ```bash
   sudo npm install -g mcp-styledbook
   ```
   Ou use a abordagem recomendada sem sudo:
   ```bash
   mkdir -p ~/.npm-global
   npm config set prefix '~/.npm-global'
   # Adicione ao seu .profile, .zshrc ou .bashrc:
   # export PATH=~/.npm-global/bin:$PATH
   ```

## 🐧 Linux - Problemas Específicos

### Problemas com o PATH

**Sintoma**: O comando npx é encontrado no terminal, mas não funciona quando chamado pelo Cursor.

**Soluções**:
1. Use caminhos absolutos no arquivo mcp.json:
   ```bash
   which npx
   ```
   E use o caminho completo.
2. Adicione o PATH ao arquivo mcp.json:
   ```json
   {
     "mcpServers": {
       "styledbook": {
         "command": "npx",
         "args": ["-y", "mcp-styledbook", "--transport=stdio"],
         "env": {
           "PATH": "/usr/local/bin:/usr/bin:/bin",
           "NODE_OPTIONS": "--no-warnings"
         }
       }
     }
   }
   ```

### Problemas com WSL (Windows Subsystem for Linux)

**Sintoma**: Configuração funciona no Windows nativo, mas não no WSL.

**Soluções**:
1. Certifique-se de que o Node.js está instalado no WSL:
   ```bash
   node --version
   ```
2. Crie um arquivo mcp.json específico para o WSL:
   ```json
   {
     "mcpServers": {
       "styledbook": {
         "command": "bash",
         "args": ["-c", "npx -y mcp-styledbook --transport=stdio"]
       }
     }
   }
   ```

## 🔍 Verificando se o MCP está funcionando

Para testar se o MCP está funcionando corretamente:

1. Inicie o MCP em modo HTTP:
   ```bash
   npx mcp-styledbook --transport=http
   ```

2. Em outro terminal, envie uma requisição de teste:
   ```bash
   curl -X POST http://localhost:3001/mcp -H "Content-Type: application/json" -d '{
     "jsonrpc": "2.0",
     "id": "test",
     "method": "info"
   }'
   ```

3. Você deve receber uma resposta com informações sobre o servidor.

## 💡 Dicas Avançadas

### Usar versão específica do MCP

Para garantir compatibilidade, você pode fixar uma versão específica:

```json
{
  "mcpServers": {
    "styledbook": {
      "command": "npx",
      "args": ["-y", "mcp-styledbook@1.0.0", "--transport=stdio"]
    }
  }
}
```

### Debug com logs detalhados

Para obter logs mais detalhados:

```json
{
  "mcpServers": {
    "styledbook": {
      "command": "npx",
      "args": ["-y", "mcp-styledbook", "--transport=stdio"],
      "env": {
        "DEBUG": "mcp:*",
        "NODE_OPTIONS": "--no-warnings"
      }
    }
  }
}
```

### Integração com Projeto npm Local

Se você está desenvolvendo o MCP localmente:

```json
{
  "mcpServers": {
    "styledbook-local": {
      "command": "node",
      "args": ["/caminho/absoluto/para/seu/projeto/bin/cli.js", "--transport=stdio"]
    }
  }
}
```

## 🆘 Suporte Adicional

Se ainda estiver tendo problemas:

1. Verifique os logs da sua ferramenta (Cursor, Trae, Windsurf)
2. Tente atualizar o Node.js e npm para as versões mais recentes
3. Verifique se há atualizações do MCP StyledBook:
   ```bash
   npm view mcp-styledbook version
   ```

Se nada funcionar, crie um issue no repositório do projeto com detalhes do problema, sistema operacional e logs de erro.