agenda-mcp-google-workspace/DOCUMENTACAO.md

MCP Server para integração com Google Workspace (Gmail, Calendar, Meet)

# Documentação do Servidor MCP Google Workspace

## Visão Geral
Este é um servidor MCP (Model Context Protocol) que fornece integração com serviços do Google Workspace, incluindo:
- Gmail
- Google Calendar
- Google Meet

## Pré-requisitos
1. Node.js (versão 14 ou superior)
2. Conta Google Workspace
3. Projeto configurado no Google Cloud Console
4. Credenciais OAuth2.0 configuradas

## Configuração Inicial

### 1. Configuração do Google Cloud Console
1. Acesse [Google Cloud Console](https://console.cloud.google.com)
2. Crie um novo projeto ou selecione um existente
3. Habilite as seguintes APIs:
   - Gmail API
   - Google Calendar API
   - Google Meet API
4. Configure as credenciais OAuth:
   - Vá em "APIs & Services" > "Credentials"
   - Clique em "Create Credentials" > "OAuth client ID"
   - Escolha "Web application"
   - Configure as URIs de redirecionamento autorizadas
   - Anote o Client ID e Client Secret

### 2. Configuração do Ambiente

#### Estrutura de Arquivos
```
agenda-mcp/
├── src/
│   └── index.ts
├── .env
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml
└── .dockerignore
```

#### Configuração das Variáveis de Ambiente
Crie um arquivo `.env` na raiz do projeto:
```env
GOOGLE_CLIENT_ID=seu_client_id
GOOGLE_CLIENT_SECRET=seu_client_secret
GOOGLE_REFRESH_TOKEN=seu_refresh_token
```

## Instalação e Execução

### Método 1: Execução Local

```bash
# Instalar dependências
npm install

# Compilar o projeto
npm run build

# Rodar o servidor
npm start
```

### Método 2: Execução com Docker

```bash
# Construir a imagem
docker-compose build

# Iniciar o container
docker-compose up -d

# Verificar logs
docker-compose logs -f

# Parar o container
docker-compose down
```

## Ferramentas Disponíveis

### Gmail

1. `list_emails`
   - Lista e-mails recentes da caixa de entrada
   - Parâmetros:
     - `maxResults`: Número máximo de e-mails (padrão: 10)
     - `query`: Filtro de busca (opcional)

2. `search_emails`
   - Pesquisa avançada de e-mails
   - Parâmetros:
     - `query`: Consulta de pesquisa (obrigatório)
     - `maxResults`: Número máximo de resultados (padrão: 10)
   - Exemplos de consultas:
     - `"from:alice@example.com"`
     - `"subject:Meeting Update"`
     - `"has:attachment filename:pdf"`
     - `"is:unread"`

3. `send_email`
   - Envia um novo e-mail
   - Parâmetros:
     - `to`: Destinatário (obrigatório)
     - `subject`: Assunto (obrigatório)
     - `body`: Corpo do e-mail (obrigatório)
     - `cc`: Cópia (opcional)
     - `bcc`: Cópia oculta (opcional)

4. `modify_email`
   - Modifica rótulos de e-mail
   - Parâmetros:
     - `id`: ID do e-mail (obrigatório)
     - `addLabels`: Rótulos para adicionar
     - `removeLabels`: Rótulos para remover

### Google Calendar

1. `list_events`
   - Lista eventos do calendário
   - Parâmetros:
     - `maxResults`: Número máximo de eventos (padrão: 10)
     - `timeMin`: Data inicial (ISO format)
     - `timeMax`: Data final (ISO format)

2. `create_event`
   - Cria novo evento
   - Parâmetros:
     - `summary`: Título (obrigatório)
     - `start`: Data/hora início (obrigatório)
     - `end`: Data/hora fim (obrigatório)
     - `location`: Local (opcional)
     - `description`: Descrição (opcional)
     - `attendees`: Lista de participantes (opcional)

3. `update_event`
   - Atualiza evento existente
   - Parâmetros:
     - `eventId`: ID do evento (obrigatório)
     - Outros parâmetros são opcionais

4. `delete_event`
   - Remove evento
   - Parâmetros:
     - `eventId`: ID do evento (obrigatório)

### Google Meet

1. `list_meetings`
   - Lista reuniões agendadas
   - Parâmetros:
     - `max_results`: Número máximo de resultados (padrão: 10)
     - `time_min`: Data inicial (ISO format)
     - `time_max`: Data final (ISO format)

2. `get_meeting`
   - Obtém detalhes de uma reunião
   - Parâmetros:
     - `meeting_id`: ID da reunião (obrigatório)

3. `create_meeting`
   - Cria nova reunião
   - Parâmetros:
     - `summary`: Título (obrigatório)
     - `start_time`: Início (obrigatório)
     - `end_time`: Fim (obrigatório)
     - `description`: Descrição (opcional)
     - `attendees`: Participantes (opcional)

4. `update_meeting`
   - Atualiza reunião existente
   - Parâmetros:
     - `meeting_id`: ID da reunião (obrigatório)
     - Outros parâmetros são opcionais

5. `delete_meeting`
   - Remove reunião
   - Parâmetros:
     - `meeting_id`: ID da reunião (obrigatório)

## Ferramentas de Desenvolvimento

### MCP Inspector
Para testar as ferramentas:
```bash
npm run inspector
```

### Modo Watch
Para desenvolvimento com recompilação automática:
```bash
npm run watch
```

## Escopos OAuth Necessários
- `https://www.googleapis.com/auth/calendar`
- `https://www.googleapis.com/auth/calendar.events`
- `https://www.googleapis.com/auth/meetings.space.created`
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/gmail.send`

## Troubleshooting

### Problemas Comuns

1. **Erro de Credenciais**
   - Verifique se o arquivo `.env` está presente
   - Confirme se as credenciais estão corretas
   - Verifique se o token de atualização é válido

2. **Erro de Permissão**
   - Verifique se todos os escopos OAuth necessários foram concedidos
   - Tente gerar um novo token de atualização

3. **Erro de Compilação**
   - Execute `npm run build` novamente
   - Verifique se há erros no TypeScript

### Comandos Úteis

```bash
# Verificar logs do Docker
docker-compose logs -f

# Reiniciar o container
docker-compose restart

# Limpar e reconstruir
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

## Suporte
Para problemas ou dúvidas, abra uma issue no repositório do projeto.

## Licença
Este projeto está licenciado sob a MIT License.