# Spec: pack-mcp-google-chat-notification

## Contexto

Precisamos de um MCP server dedicado a enviar notificações para o Google Chat via Webhooks.
Ele será usado em conjunto com outros MCPs (ex: `pack-mcp-gitlab`) para orquestrar fluxos como:
criar MR → notificar canal do Google Chat.

A orquestração fica no agente/hook do Kiro, não no MCP. Este MCP tem responsabilidade única: enviar mensagens para o Google Chat.

## Referência de Arquitetura

Seguir os mesmos padrões do projeto `pack-mcp-gitlab`:

- Python 3.10+, build com `hatchling`
- MCP server via `mcp` (FastMCP), transporte `stdio`
- Estrutura: `src/pack_mcp_google_chat_notification/` com `server.py`, `client.py`, `errors.py`, `__init__.py`
- Entry point: `pack-mcp-google-chat-notification = "pack_mcp_google_chat_notification.server:main"`
- Decorator de tratamento de erros centralizado (`handle_error`) que converte exceções em `McpError`
- Sanitização de URLs de webhook nos logs (não expor tokens)
- Client como singleton inicializado via variáveis de ambiente
- Testes com `pytest` + `hypothesis`
- Publicação no PyPI

## Variáveis de Ambiente

- `GOOGLE_CHAT_WEBHOOK_URL`: URL padrão do webhook (opcional, pode ser passada por tool call)
- `LOG_LEVEL`: nível de log (default: `WARNING`)

## Tools (MCP)

### 1. `send_message`

Envia uma mensagem de texto simples para um espaço do Google Chat.

**Parâmetros:**
- `text` (str, obrigatório): Texto da mensagem. Suporta formatação básica do Google Chat.
- `webhook_url` (str, opcional): URL do webhook. Se omitido, usa `GOOGLE_CHAT_WEBHOOK_URL`.

**Retorno:** JSON com `{ "success": true }` ou erro descritivo.

**Validações:**
- `text` não pode ser vazio
- `webhook_url` deve ser uma URL válida do Google Chat (começar com `https://chat.googleapis.com/`)
- Se nenhum webhook for fornecido (nem parâmetro, nem env var), retornar erro claro

### 2. `send_card`

Envia uma mensagem com Card V2 (formato rico) para o Google Chat.

**Parâmetros:**
- `title` (str, obrigatório): Título do card
- `subtitle` (str, opcional): Subtítulo
- `sections` (list[dict], obrigatório): Lista de seções do card, cada uma com:
  - `header` (str, opcional): Título da seção
  - `widgets` (list[dict]): Widgets da seção (textParagraph, decoratedText, buttonList, etc.)
- `webhook_url` (str, opcional): URL do webhook

**Retorno:** JSON com `{ "success": true }` ou erro descritivo.

### 3. `send_thread_message`

Envia mensagem em uma thread existente ou cria nova thread.

**Parâmetros:**
- `text` (str, obrigatório): Texto da mensagem
- `thread_key` (str, obrigatório): Chave da thread (ex: `mr-123`, `deploy-prod-2024`)
- `webhook_url` (str, opcional): URL do webhook

**Retorno:** JSON com `{ "success": true, "thread_key": "..." }`

## API do Google Chat (Webhooks)

- Endpoint: POST para a URL do webhook
- Content-Type: `application/json`
- Body para texto simples: `{ "text": "mensagem" }`
- Body para card: `{ "cardsV2": [{ "cardId": "...", "card": { ... } }] }`
- Para threads: adicionar query param `?threadKey=CHAVE&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD`
- Usar `httpx` como HTTP client (async-friendly, moderno)
- Timeout padrão: 10 segundos
- Tratar HTTP 200 como sucesso, qualquer outro status como erro

## Tratamento de Erros

- Timeout de conexão → mensagem clara
- HTTP != 200 → incluir status code e body na mensagem de erro
- Webhook URL inválida → validação antes do request
- Sanitizar webhook URLs nos logs (conter tokens no path)

## Estrutura do Projeto

```
pack-mcp-google-chat-notification/
├── pyproject.toml
├── README.md
├── src/
│   └── pack_mcp_google_chat_notification/
│       ├── __init__.py
│       ├── server.py      # Tools MCP
│       ├── client.py       # Lógica HTTP (httpx)
│       └── errors.py       # Decorator de erro + sanitização
└── tests/
    ├── __init__.py
    ├── conftest.py
    └── strategies.py
```

## Dependências

```toml
dependencies = [
    "httpx>=0.27.0",
    "mcp>=1.0.0",
]
```

## Configuração MCP (exemplo para mcp.json)

```json
{
  "mcpServers": {
    "google-chat": {
      "command": "uvx",
      "args": ["pack-mcp-google-chat-notification"],
      "env": {
        "GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/XXXX/messages?key=YYYY&token=ZZZZ"
      }
    }
  }
}
```
