Fastmail

Interaja com e-mails, contatos e dados de calendário do Fastmail usando a API do Fastmail.

Documentação

Servidor MCP Fastmail (Não oficial)

Um servidor não oficial do Model Context Protocol (MCP) que fornece acesso à API do Fastmail, permitindo que assistentes de IA interajam com e-mails, contatos e dados de calendário.

Aviso: Este é um projeto da comunidade. Não é afiliado, endossado ou suportado pela Fastmail. "Fastmail" é uma marca registrada da Fastmail Pty Ltd; é usado aqui apenas para descrever compatibilidade com suas APIs públicas JMAP/CalDAV/WebDAV. Use por sua conta e risco sob os termos da licença do projeto.

Recursos

Operações Principais de E-mail

Listar mailboxes e obter estatísticas de mailbox
Listar, pesquisar e filtrar e-mails com critérios avançados
Obter e-mails específicos por ID com conteúdo completo
Enviar e-mails (texto e HTML) com tratamento adequado de rascunho/enviados
Responder a e-mails com encadeamento adequado (cabeçalhos In-Reply-To, References)
Criar, editar e enviar rascunhos de e-mail (com ou sem encadeamento)
Gerenciamento de e-mail: marcar como lido/não lido, excluir, mover entre pastas

Recursos Avançados de E-mail

Tratamento de Anexos: Listar, baixar e enviar anexos; salvar anexos diretamente no armazenamento em nuvem WebDAV
Ferramentas de metadados com foco em privacidade: Variantes somente de metadados das ferramentas de listar/pesquisar/thread (sem conteúdo do corpo)
Suporte a Threads: Obter threads de conversa completas
Pesquisa Avançada: Filtragem por múltiplos critérios (remetente, intervalo de datas, anexos, status de leitura)
Operações em Lote: Processar múltiplos e-mails simultaneamente
Estatísticas e Análises: Resumos de conta e estatísticas de mailbox

Operações de Contatos

Listar todos os contatos com informações completas
Obter contatos específicos por ID
Pesquisar contatos por nome ou e-mail
Criar, atualizar e excluir contatos (JMAP ContactCard/set; requer um token de API com escopo de leitura/gravação de contatos)

Operações de Calendário

Listar, obter, criar, atualizar e excluir eventos de calendário (via CalDAV)
Eventos de dia inteiro e com horário, participantes, atualizações com reconhecimento de recorrência

Operações de Rótulo vs. Mover

move_email/bulk_move: Substitui TODAS as mailboxes de um e-mail (comportamento de pasta)
add_labels/remove_labels: Adiciona/remove mailboxes ESPECÍFICAS preservando as demais (comportamento de rótulo)

Gerenciamento de Identidade e Conta

Listar identidades de envio disponíveis
Resumo da conta com estatísticas abrangentes

Configuração

Pré-requisitos

Node.js 20+
Uma conta Fastmail com acesso à API
Token de API do Fastmail

Instalação

Clone ou baixe este repositório
Instale as dependências:
```
npm install
```
Compile o projeto:
```
npm run build
```

Configuração

Obtenha seu token de API do Fastmail:
- Faça login na interface web do Fastmail
- Vá para Configurações → Privacidade e Segurança
- Encontre a seção "Aplicativos conectados e tokens de API"
- Clique em "Gerenciar tokens de API"
- Clique em "Novo token de API"
- Copie o token gerado

Defina as variáveis de ambiente:

export FASTMAIL_API_TOKEN="your_api_token_here"
# Optional: customize base URL (defaults to https://api.fastmail.com)
# Only api.fastmail.com and www.fastmailusercontent.com are accepted by default,
# each with an optional regional prefix (phl.api.fastmail.com,
# phl-www.fastmailusercontent.com) as returned by JMAP session discovery.
# For self-hosted JMAP servers, also set FASTMAIL_ALLOW_UNSAFE_BASE_URL=true.
export FASTMAIL_BASE_URL="https://api.fastmail.com"
# Optional: customize attachment download directory (defaults to ~/Downloads/fastmail-mcp/).
# download_attachment savePaths are confined to this directory; set it to the root
# you want attachments saved under to write there directly in one step.
export FASTMAIL_DOWNLOAD_DIR="/path/to/your/downloads"

Executando o Servidor

Inicie o servidor MCP:

npm start

Para desenvolvimento com recarga automática:

npm run dev

Executar a partir de um clone

git clone https://github.com/MadLlama25/fastmail-mcp && cd fastmail-mcp
npm install && npm run build
FASTMAIL_API_TOKEN="your_token" node dist/index.js

Nota: npx github:MadLlama25/fastmail-mcp não funciona no npm 10 (um bug conhecido do GitFetcher do npm). Use o clone acima, ou instale a Extensão de Desktop empacotada.

Instalar como Extensão de Desktop do Claude (DXT)

Você pode instalar este servidor como uma Extensão de Desktop para o Claude Desktop usando o arquivo .dxt empacotado.

Compile e empacote:
```
npm run build
npx @anthropic-ai/dxt pack
```
Isso produz fastmail-mcp.dxt na raiz do projeto.
Instale no Claude Desktop:
- Abra o arquivo .dxt, ou arraste-o para o Claude Desktop
- Quando solicitado:
  - Token de API do Fastmail: cole seu token (armazenado criptografado pelo Claude) — obrigatório
  - URL Base do Fastmail: deixe em branco para usar https://api.fastmail.com (padrão)
  - Diretório de Download: deixe em branco para ~/Downloads/fastmail-mcp/
  - Nome de Usuário / Senha / Nome de Exibição CalDAV: opcional — obrigatório para ferramentas de calendário (use uma senha específica do aplicativo; veja Suporte a Calendário CalDAV)
  - URL / Nome de Usuário / Senha WebDAV: opcional — obrigatório para save_attachment_to_webdav (veja Armazenamento de arquivos WebDAV)
Use qualquer uma das ferramentas (ex.: get_recent_emails).

Ferramentas Disponíveis (52 no total)

Formato de resposta das ferramentas de listar/pesquisar: as ferramentas de consulta (list_emails, list_emails_metadata, search_emails, search_emails_metadata, get_recent_emails, advanced_search, advanced_search_metadata, list_contacts, search_contacts) retornam um envelope JSON {"total", "items"} — total é a contagem de correspondências relatada pelo servidor, items a página retornada. Quando o servidor não relata total, um array simples é retornado.

🎯 Ferramentas Mais Populares:

check_function_availability: Verifique o que está disponível e obtenha orientação de configuração
test_bulk_operations: Teste com segurança operações em lote com modo de simulação (dry-run)
send_email: Envio de e-mail completo com tratamento adequado de rascunho/enviados
advanced_search: Filtragem poderosa de e-mails por múltiplos critérios
get_recent_emails: Acesso rápido a e-mails recentes de qualquer mailbox

Ferramentas de E-mail

list_mailboxes: Obtenha todas as mailboxes da sua conta. Em contas com muitas mailboxes, a saída completa pode ser grande — passe properties para uma visão enxuta.
- Parâmetros: properties (array opcional de campos a retornar), parentId (opcional; apenas filhos desta mailbox, null para o nível superior)
get_mailbox_by_name: Consulte uma mailbox pelo seu caminho completo a partir da raiz (ex.: Inbox/Receipts)
- Parâmetros: path (obrigatório)
create_mailbox: Crie uma nova mailbox (pasta/rótulo)
- Parâmetros: name (obrigatório), parentId (opcional, omita ou use null para o nível superior)
list_emails: Liste e-mails de uma mailbox específica ou de todas as mailboxes
- Parâmetros: mailboxId (opcional), limit (padrão: 20, máximo: 100), ascending (opcional, mais antigos primeiro)
list_emails_metadata: Liste e-mails de uma mailbox, somente metadados (cabeçalhos, sem conteúdo do corpo)
- Parâmetros: mailboxId (opcional), limit (padrão: 20, máximo: 100), ascending (opcional, mais antigos primeiro)
get_email: Obtenha um e-mail específico por ID
- Parâmetros: emailId (obrigatório)
get_email_metadata: Obtenha apenas os metadados de um e-mail específico (cabeçalhos na lista de permissões, sem corpo)
- Parâmetros: emailId (obrigatório)
send_email: Envie um e-mail (suporta encadeamento via cabeçalhos opcionais inReplyTo e references)
- Parâmetros: to (obrigatório — array ou string separada por vírgulas), cc (array opcional), bcc (array opcional), from (opcional), mailboxId (opcional), subject (obrigatório), textBody (opcional), htmlBody (opcional), inReplyTo (array opcional), references (array opcional), replyTo (array opcional), attachments (array opcional — veja Anexos de e-mail no envio)
reply_email: Responda a um e-mail existente com cabeçalhos de encadeamento adequados (constrói automaticamente In-Reply-To e References). Defina send=false para salvar como rascunho em vez de enviar.
- Parâmetros: originalEmailId (obrigatório), to (array opcional, padrão para o remetente original), cc (array opcional), bcc (array opcional), from (opcional), textBody (opcional), htmlBody (opcional), send (booleano opcional, padrão: true), replyTo (array opcional), attachments (array opcional — veja Anexos de e-mail no envio)
create_draft: Crie um rascunho de e-mail (pelo menos um de para/assunto/corpo/anexos é obrigatório; suporta cabeçalhos de encadeamento para rascunhos de resposta)
- Parâmetros: to (array opcional), cc (array opcional), bcc (array opcional), from (opcional), mailboxId (opcional), subject (opcional), textBody (opcional), htmlBody (opcional), replyTo (array opcional), inReplyTo (array opcional), references (array opcional), attachments (array opcional — veja Anexos de e-mail no envio)
edit_draft: Edite um rascunho existente no lugar — apenas os campos fornecidos são alterados; anexos existentes são preservados
- Parâmetros: emailId (obrigatório), to, cc, bcc, from, subject, textBody, htmlBody, replyTo, attachments (todos opcionais)
send_draft: Envie um rascunho existente
- Parâmetros: emailId (obrigatório)
search_emails: Pesquise e-mails por conteúdo
- Parâmetros: query (obrigatório), limit (padrão: 20, máximo: 100), ascending (opcional, mais antigos primeiro), excludeDrafts (opcional, omitir mensagens de rascunho)
- Rascunhos são incluídos por padrão. Defina excludeDrafts: true para filtrá-los no lado do servidor.
- Pesquisa todas as mailboxes, incluindo Lixeira e Spam. Para fluxos de limpeza/verificação, exclua a mailbox de Lixeira explicitamente (ex.: advanced_search com excludeMailboxIds) em vez de confiar em uma contagem de pesquisa simples.
get_recent_emails: Obtenha os e-mails mais recentes (inspirado no top-ten do JMAP-Samples)
- Parâmetros: limit (padrão: 10, máximo: 50), mailboxName (opcional), ascending (opcional, mais antigos primeiro)
- Quando mailboxName é omitido, todas as mailboxes são pesquisadas exceto Lixeira e Spam. Passe um nome de mailbox (ex.: 'inbox', 'sent') para limitar a uma pasta.
search_emails_metadata: Pesquise e-mails por conteúdo, retornando apenas metadados
- Parâmetros: query (obrigatório), limit (padrão: 20, máximo: 100), ascending (opcional, mais antigos primeiro)
mark_email_read: Marque um e-mail como lido ou não lido
- Parâmetros: emailId (obrigatório), read (padrão: true)
pin_email: Fixe ou desafixe um e-mail
- Parâmetros: emailId (obrigatório), pinned (padrão: true)
archive_email: Arquive um e-mail — move e marca como lido em uma única etapa atômica
- Parâmetros: emailId (obrigatório), targetMailboxId (obrigatório)
delete_email: Exclua um e-mail (mover para a lixeira)
- Parâmetros: emailId (obrigatório)
move_email: Mova um e-mail para uma mailbox diferente (substitui todas as mailboxes)
- Parâmetros: emailId (obrigatório), targetMailboxId (obrigatório)
add_labels: Adicione rótulos (mailboxes) a um e-mail sem remover os existentes
- Parâmetros: emailId (obrigatório), mailboxIds (array obrigatório)
remove_labels: Remova rótulos específicos (mailboxes) de um e-mail
- Parâmetros: emailId (obrigatório), mailboxIds (array obrigatório)

Recursos Avançados de E-mail

get_email_attachments: Obtém a lista de anexos de um e-mail
- Parâmetros: emailId (obrigatório)
download_attachment: Baixa um anexo de e-mail. Se savePath for fornecido, salva o arquivo em disco e retorna o caminho e o tamanho do arquivo. Caso contrário, retorna uma URL de download.
- Parâmetros: emailId (obrigatório), attachmentId (obrigatório), savePath (opcional)
- savePath pode ser absoluto ou relativo. Caminhos relativos (incluindo um nome de arquivo simples) são resolvidos em relação ao diretório de download, então um anexo chega lá em uma única etapa. Caminhos absolutos devem estar dentro desse diretório; travessia ou escape por symlink para fora dele é rejeitado. Para salvar diretamente em seu próprio local, defina FASTMAIL_DOWNLOAD_DIR para essa raiz — o confinamento permanece ativo, com escopo no diretório que você escolher.
save_attachment_to_webdav: Salva um anexo diretamente no armazenamento em nuvem WebDAV (Fastmail Files, Nextcloud, ...) sem tocar no disco local
- Parâmetros: emailId (obrigatório), attachmentId (obrigatório), remotePath (obrigatório, relativo), overwrite (padrão: false), createParents (padrão: true)
- O servidor de armazenamento e as credenciais vêm da configuração de ambiente FASTMAIL_WEBDAV_*; a ferramenta apenas escolhe o caminho relativo abaixo dessa base. Arquivos existentes nunca são substituídos, a menos que overwrite: true.
advanced_search: Busca avançada de e-mails com múltiplos critérios
- Parâmetros: query (opcional), from (opcional), to (opcional), subject (opcional), hasAttachment (opcional), isUnread (opcional), isPinned (opcional), mailboxId (opcional), requiredMailboxIds (array opcional — o e-mail deve estar em TODOS estes), excludeMailboxIds (array opcional — exclui e-mails em qualquer um destes), after (opcional), before (opcional), limit (padrão: 50, máx: 100), ascending (opcional, mais antigos primeiro)
- Como search_emails, busca em todas as caixas de correio, incluindo Lixeira e Spam — use o escopo com mailboxId/excludeMailboxIds quando isso for importante. (get_recent_emails é o que exclui Lixeira/Spam por padrão.)
advanced_search_metadata: Mesmos filtros de advanced_search, resultados apenas com metadados (sem conteúdo do corpo)
get_thread: Obtém todos os e-mails em um tópico de conversa
- Parâmetros: threadId (obrigatório), includeDrafts (opcional, incluir rascunhos em andamento)
- Mensagens de rascunho são excluídas por padrão (uma resposta em andamento é ruído ao ler uma conversa). Defina includeDrafts: true para incluí-las. Rascunhos são identificados pela palavra-chave $draft, então a assimetria com search_emails (que inclui rascunhos por padrão) é deliberada: uma busca ainda deve encontrar tudo o que você escreveu.
get_thread_metadata: Obtém todos os e-mails em um tópico, apenas metadados. Também aceita um ID de e-mail e resolve o tópico pai dele.
- Parâmetros: threadId (obrigatório), includeDrafts (opcional)

Estatísticas e Análises de E-mail

get_mailbox_stats: Obtém estatísticas de uma caixa de correio (contagem de não lidos, total de e-mails, etc.)
- Parâmetros: mailboxId (opcional, padrão: todas as caixas de correio)
get_account_summary: Obtém o resumo geral da conta com estatísticas

Operações em Massa

bulk_mark_read: Marca múltiplos e-mails como lidos/não lidos
- Parâmetros: emailIds (array obrigatório), read (padrão: true)
bulk_pin: Fixa ou desafixa múltiplos e-mails
- Parâmetros: emailIds (array obrigatório), pinned (padrão: true)
bulk_move: Move múltiplos e-mails para uma caixa de correio
- Parâmetros: emailIds (array obrigatório), targetMailboxId (obrigatório)
bulk_delete: Exclui múltiplos e-mails (move para a lixeira)
- Parâmetros: emailIds (array obrigatório)
bulk_add_labels: Adiciona rótulos a múltiplos e-mails simultaneamente
- Parâmetros: emailIds (array obrigatório), mailboxIds (array obrigatório)
bulk_remove_labels: Remove rótulos de múltiplos e-mails simultaneamente
- Parâmetros: emailIds (array obrigatório), mailboxIds (array obrigatório)

Ferramentas de Contatos

list_contacts: Lista todos os contatos
- Parâmetros: limit (padrão: 50, máx: 200)
get_contact: Obtém um contato específico por ID
- Parâmetros: contactId (obrigatório)
search_contacts: Busca contatos por nome ou e-mail
- Parâmetros: query (obrigatório), limit (padrão: 20, máx: 100)
create_contact: Cria um novo contato (requer escopo de contatos de leitura-escrita no token da API)
- Parâmetros: name {given, surname, full}, emails [{address, label}], phones [{number, label}], addresses [{full, label}], notes, addressBookId (todos opcionais, mas um nome ou um e-mail é obrigatório)
update_contact: Atualiza um contato existente — cada campo fornecido substitui completamente o valor armazenado (emails: [] remove todos os e-mails); campos não especificados não são alterados
- Parâmetros: contactId (obrigatório), mesmos campos do create, expectState (pré-condição de estado JMAP opcional)
delete_contact: Exclui permanentemente um contato (não pode ser desfeito)
- Parâmetros: contactId (obrigatório), expectState (opcional)

Ferramentas de Calendário

list_calendars: Lista todos os calendários
list_calendar_events: Lista eventos de calendário (apenas campos principais — sem participantes para eficiência de token)
- Parâmetros: calendarId (opcional), startDate (opcional, ISO 8601), endDate (opcional, ISO 8601), limit (padrão: 50, máx: 500)
get_calendar_event: Obtém um evento de calendário específico por ID. Retorna organizador e participantes quando disponíveis.
- Parâmetros: eventId (obrigatório)
create_calendar_event: Cria um novo evento de calendário. Suporta apenas data (ex.: 2026-04-01) para eventos de dia inteiro. DTEND é exclusivo conforme RFC 5545 — um evento de um dia em 1º de abril precisa de end: "2026-04-02".
- Parâmetros: calendarId (obrigatório), title (obrigatório), description (opcional), start (obrigatório, ISO 8601 ou apenas data), end (obrigatório, ISO 8601 ou apenas data), location (opcional), participants (array opcional de {email, name?})
update_calendar_event: Corrige um evento de calendário existente. Preserva todos os dados existentes (participantes, lembretes, regras de recorrência, etc.) que não estão sendo alterados. Omita um campo para deixá-lo inalterado; passar uma string vazia ou apenas espaços em branco para title, description ou location é rejeitado (não vai apagar silenciosamente a propriedade). Para excluir description ou location, liste-os em clearFields. Horários flutuantes (sem Z/offset) preservam o fuso horário original. AVISO: fornecer participants substitui TODOS os dados de participantes existentes; participants: [] remove todos os participantes (e o ORGANIZADOR agora órfão).
- Parâmetros: eventId (obrigatório), title, description, start, end, location, participants (array de {email, name?}), clearFields (array de "description"/"location" para excluir), confirmRecurring (booleano)
delete_calendar_event: Exclui um evento de calendário
- Parâmetros: eventId (obrigatório)

Limitações conhecidas do calendário

Eventos recorrentes: Apenas a modificação de "todos os eventos" é suportada (VEVENT mestre). "Apenas este evento" ou "este e eventos futuros" não são suportados. Alterar início/fim em eventos recorrentes com exceções de sobreposição requer confirmRecurring: true — exceções órfãs são podadas para evitar erros do servidor.
Parâmetros de participantes: RSVP, ROLE, CUTYPE e outros parâmetros de participantes são analisados na leitura, mas não podem ser definidos na criação/atualização — apenas email e name são aceitos.

Ferramentas de Identidade e Teste

list_identities: Lista identidades de envio (endereços de e-mail que podem ser usados para envio)
check_function_availability: Verifica quais funções estão disponíveis com base nas permissões da conta (inclui orientação de configuração). As ferramentas de calendário rodam via CalDAV, então o calendário é reportado como disponível quando as credenciais CalDAV estão configuradas, independentemente da capacidade de calendário JMAP.
test_bulk_operations: Testa com segurança operações em massa com modo de simulação (dry-run)
- Parâmetros: dryRun (padrão: true), limit (padrão: 3)

Informações da API

Este servidor usa a API JMAP (JSON Meta Application Protocol) fornecida pela Fastmail. JMAP é uma alternativa moderna e eficiente ao IMAP para acesso a e-mail.

Inspirado no Fastmail JMAP-Samples

Muitos recursos neste servidor MCP são inspirados no repositório oficial Fastmail JMAP-Samples, incluindo:

Recuperação de e-mails recentes (baseado no exemplo top-ten)
Operações de gerenciamento de e-mail
Chamadas de método JMAP encadeadas eficientes

Autenticação

O servidor usa autenticação por token de portador com a API da Fastmail. Os tokens de API fornecem acesso seguro sem expor a senha principal da sua conta.

Limites de taxa

A Fastmail aplica limites de taxa às solicitações de API. O servidor lida com a limitação de taxa padrão, mas solicitações excessivas podem ser limitadas.

Suporte a Calendário CalDAV

A Fastmail atualmente não expõe acesso a calendário via tokens de API JMAP — o escopo urn:ietf:params:jmap:calendars não está disponível porque a especificação JMAP Calendars ainda é um Internet-Draft do IETF (draft-ietf-jmap-calendars). A Fastmail declarou que adicionará suporte a calendário JMAP quando a especificação se tornar um RFC, mas não há cronograma público.

No entanto, a Fastmail suporta totalmente CalDAV para acesso a calendário via caldav.fastmail.com. Todas as ferramentas de calendário usam CalDAV diretamente.

Configuração

Crie uma senha específica de aplicativo na Fastmail:
- Vá para Configurações → Privacidade e Segurança → Gerenciar senhas de aplicativos
- Crie uma nova senha de aplicativo (você pode nomeá-la "CalDAV MCP" ou similar)

Defina as seguintes variáveis de ambiente:

export FASTMAIL_CALDAV_USERNAME="your-email@fastmail.com"
export FASTMAIL_CALDAV_PASSWORD="your-app-specific-password"
# Optional: display name for ORGANIZER when creating events with participants
export FASTMAIL_CALDAV_DISPLAY_NAME="Your Name"

Quando essas variáveis estão definidas, todas as ferramentas de calendário estão disponíveis. Quando não estão definidas, as ferramentas de calendário retornarão um erro com instruções de configuração.

Armazenamento de arquivos WebDAV (opcional)

save_attachment_to_webdav salva anexos diretamente no armazenamento em nuvem. Configure o destino (nunca fornecido pelas ferramentas em tempo de execução — isso é deliberado, para que um chamador mal-intencionado não possa redirecionar uploads):

# Fastmail Files:
export FASTMAIL_WEBDAV_URL="https://myfiles.fastmail.com/"
export FASTMAIL_WEBDAV_USERNAME="your-email@fastmail.com"
export FASTMAIL_WEBDAV_PASSWORD="app-password-with-files-scope"

# ...or any WebDAV server, e.g. Nextcloud:
# export FASTMAIL_WEBDAV_URL="https://cloud.example.com/remote.php/dav/files/USERNAME/"

A URL deve ser HTTPS. Observação: o Fastmail Files ignora a pré-condição WebDAV If-None-Match, então a ferramenta realiza uma verificação explícita de existência antes de uploads sem substituição.

Anexos de e-mail no envio

send_email, create_draft, edit_draft e reply_email aceitam um array attachments. Cada entrada usa exatamente uma fonte:

{ "localPath": "report.pdf" } — um arquivo dentro de FASTMAIL_DOWNLOAD_DIR (mesmo confinamento dos downloads)
{ "emailId": "...", "attachmentId": "..." } — reanexar de um e-mail existente (cópia zero: nenhum byte é transferido)
{ "blobId": "...", "name": "...", "type": "..." } — um blob JMAP já enviado

Os uploads respeitam o maxSizeUpload do servidor (~50 MB na Fastmail). Editar um rascunho preserva seus anexos existentes.

Escopo de escrita de contatos

create_contact / update_contact / delete_contact precisam que o token da API tenha escopo de contatos de leitura-escrita (Configurações → Privacidade e Segurança → Tokens de API). Tokens somente leitura mantêm as três ferramentas de leitura funcionando e falham nas escritas com um erro forbidden.

Desenvolvimento

Estrutura do Projeto

src/
├── index.ts               # Main MCP server implementation
├── auth.ts                # Authentication handling
├── jmap-client.ts         # JMAP client wrapper
├── contacts-calendar.ts   # Contacts extensions (JMAP)
├── caldav-client.ts       # CalDAV calendar client (the calendar path — JMAP calendars are not available)
├── webdav-files-client.ts # WebDAV file storage client (save_attachment_to_webdav)
├── url-validation.ts      # Base-URL allowlist / HTTPS validation
├── coerce.ts              # Input coercion helpers
└── *.test.ts              # Unit tests (colocated)

Compilação

npm run build

Modo de Desenvolvimento

npm run dev

Licença

MIT

Contribuindo

Contribuições são bem-vindas! Por favor, garanta que:

O código siga o estilo existente
Todas as funções sejam devidamente tipadas
O tratamento de erros seja implementado
A documentação seja atualizada para novos recursos

Solução de Problemas

Problemas Comuns

Erros de Autenticação: Certifique-se de que seu token de API é válido e possui as permissões necessárias
Dependências Ausentes: Execute npm install para garantir que todas as dependências estejam instaladas
Erros de Build: Verifique se a compilação TypeScript é concluída sem erros usando npm run build
Erros "Proibido" em Calendário/Contatos: Use check_function_availability para ver as orientações de configuração

Ferramentas de E-mail Falhando com Erros de Serialização?

Se get_email, list_emails, search_emails ou advanced_search falharem com erros de "serialização de conteúdo" ou "Não é possível ler propriedades de indefinido", atualize para v1.7.1 ou posterior (qualquer versão atual inclui a correção). Isso foi causado por validação incompleta de resposta JMAP que surgiu após a atualização do MCP SDK v1.x adicionar verificação de resultados mais rigorosa.

Calendário Não Funciona?

As ferramentas de calendário operam via CalDAV, não JMAP. Se retornarem "CalDAV não configurado", defina FASTMAIL_CALDAV_USERNAME e FASTMAIL_CALDAV_PASSWORD (veja Suporte a Calendário CalDAV).

Contatos Não Funcionam?

Se as funções de contatos retornarem erros "Proibido":

Escopo do Token de API: gravações (create_contact/update_contact/delete_contact) precisam de escopo de contatos com leitura/gravação (veja Escopo de gravação de contatos)
Plano da Conta: a API de contatos pode exigir determinados planos Fastmail

Erros Contact not found / Calendar event not found significam que o ID está desatualizado — reliste e tente novamente.

Solução: Execute check_function_availability para orientações de configuração passo a passo.

Testando Sua Configuração

Use as ferramentas de teste integradas:

check_function_availability: Veja o que está disponível e obtenha ajuda de configuração
test_bulk_operations: Teste operações em lote com segurança sem fazer alterações

Para informações de erro mais detalhadas, verifique a saída do console ao executar o servidor.

Privacidade e Segurança

Os tokens de API são armazenados criptografados pelo Claude Desktop quando instalados via DXT e nunca são registrados por este servidor.
O servidor evita registrar erros brutos e dados sensíveis (tokens, endereços de e-mail, identidades, nomes de anexos/blobIds) em mensagens de erro.
As respostas das ferramentas podem incluir metadados/conteúdo do seu e-mail por design (por exemplo, listagem de e-mails), mas identificadores internos e credenciais não são divulgados além do que o Fastmail retorna para os dados solicitados.
Se você encontrar erros, as mensagens são sanitizadas e resumidas para evitar vazamento de informações pessoais.