# mcp-meta

MCP server para **Meta Business Messaging**: WhatsApp Cloud API, Messenger Platform, Instagram Messaging e Graph API Webhooks.

Cobre ~55 tools agrupadas em 4 produtos. Todos os endpoints apontam para `graph.facebook.com/{version}` (default `v22.0`, override via `META_API_VERSION`).

## Instalação

```bash
cd /Users/barboza/Solutions/mcp-meta
npm install
npm run build
```

## Configuração (variáveis de ambiente)

Todas são opcionais — também podem ser passadas por chamada via `access_token` / `phone_number_id` / etc. nos args do tool. Env apenas serve como default.

| Env | Uso |
|-----|-----|
| `META_API_VERSION` | Versão da Graph API (default `v22.0`) |
| `META_BASE_URL` | Base URL (default `https://graph.facebook.com`) |
| `META_APP_SECRET` | Usado por `webhook_validate_signature` |
| `META_VERIFY_TOKEN` | Token de handshake (`hub.verify_token`) |
| `WHATSAPP_ACCESS_TOKEN` | Bearer para Cloud API |
| `WHATSAPP_PHONE_NUMBER_ID` | ID padrão do número emissor |
| `WHATSAPP_BUSINESS_ACCOUNT_ID` | WABA ID (templates, phone numbers) |
| `MESSENGER_PAGE_ACCESS_TOKEN` | Token da Page FB |
| `MESSENGER_PAGE_ID` | ID da Page padrão |
| `INSTAGRAM_PAGE_ACCESS_TOKEN` | Token da Page ligada ao IG (default: mesmo `MESSENGER_PAGE_ACCESS_TOKEN`) |
| `INSTAGRAM_USER_ID` | IG user ID, se aplicável |

## Uso via Claude Code / MCP client

Adicione em `~/.claude.json` (ou equivalente):

```json
{
  "mcpServers": {
    "meta": {
      "command": "node",
      "args": ["/Users/barboza/Solutions/mcp-meta/dist/index.js"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "EAAJB...",
        "WHATSAPP_PHONE_NUMBER_ID": "1234567890",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "987654321",
        "MESSENGER_PAGE_ACCESS_TOKEN": "EAAJB...",
        "MESSENGER_PAGE_ID": "1111111",
        "META_APP_SECRET": "...",
        "META_VERIFY_TOKEN": "..."
      }
    }
  }
}
```

Para desenvolvimento (tsx, sem build):

```json
"args": ["--import", "tsx", "/Users/barboza/Solutions/mcp-meta/src/index.ts"]
```

## Tools disponíveis

### Descoberta
- `meta_list_tools(product?)` — lista todas as ferramentas e endpoints mapeados
- Resource `meta://reference/endpoints.json` — catálogo completo em JSON

### WhatsApp Cloud API (~26 tools)
Mensagens: `whatsapp_send_text`, `whatsapp_send_image`, `whatsapp_send_audio`, `whatsapp_send_video`, `whatsapp_send_document`, `whatsapp_send_sticker`, `whatsapp_send_location`, `whatsapp_send_contacts`, `whatsapp_send_reaction`, `whatsapp_send_template`, `whatsapp_send_reply_buttons`, `whatsapp_send_list`, `whatsapp_send_cta_url`, `whatsapp_send_flow`

Estado: `whatsapp_mark_as_read`

Mídia: `whatsapp_upload_media`, `whatsapp_get_media`, `whatsapp_delete_media`

Templates: `whatsapp_list_templates`, `whatsapp_create_template`, `whatsapp_delete_template`

Perfil/conta: `whatsapp_get_business_profile`, `whatsapp_update_business_profile`, `whatsapp_list_phone_numbers`, `whatsapp_register_phone_number`, `whatsapp_block_users`

### Messenger Platform (~14 tools)
`messenger_send_text`, `messenger_send_quick_replies`, `messenger_send_attachment`, `messenger_send_generic_template`, `messenger_send_button_template`, `messenger_send_media_template`, `messenger_sender_action`, `messenger_upload_attachment`, `messenger_get_user_profile`, `messenger_list_conversations`, `messenger_set_profile`, `messenger_get_profile`, `messenger_pass_thread_control`, `messenger_take_thread_control`

### Instagram Messaging (~10 tools)
`instagram_send_text`, `instagram_send_quick_replies`, `instagram_send_attachment`, `instagram_send_generic_template`, `instagram_send_button_template`, `instagram_send_product_template`, `instagram_private_reply_to_comment`, `instagram_react_to_message`, `instagram_get_user_profile`, `instagram_list_conversations`

### Webhooks (3 tools)
`webhook_verify_challenge`, `webhook_validate_signature`, `webhook_parse_event`

## Fonte de verdade

O arquivo [`reference/endpoints.json`](./reference/endpoints.json) é o catálogo canônico dos endpoints — gerado por crawl da documentação oficial em `developers.facebook.com/documentation/business-messaging/...` e `developers.facebook.com/docs/messenger-platform/...`.

Cada tool wrapea um endpoint desse catálogo. Para adicionar suporte a um endpoint novo:

1. Adicionar entrada em `reference/endpoints.json`
2. Criar o tool em `src/tools/<produto>.ts` usando `graphRequest()` de `src/client.ts`
3. Registrar em `src/index.ts` (já automático via `registerXxxTools`)

## Licença

MIT.