Saltar para o conteúdo principal

Plugin para Claude Code

O plugin do Campbooks para Claude Code liga o seu agente de programação à sua caixa de entrada via MCP. Uma vez instalado, duas skills tratam do trabalho pesado: /campbooks:setup guia-o pelo processo de onboarding e /campbooks:triage executa a sua sessão diária de caixa de entrada.

Instalar​

Numa sessão de Claude Code:

/plugin marketplace add notacamp/campbooks
/plugin install campbooks@campbooks

O Claude Code irá solicitar duas coisas:

  1. URL do servidor Campbooks — https://app.campbooks.not-a-camp.com para o Campbooks Cloud, ou o URL da sua própria instância (sem barra no final).
  2. Chave MCP — uma credencial sem expiração; ver abaixo.

Criar a chave MCP​

Os tokens OAuth de curta duração expiram após duas horas e não podem ser utilizados numa configuração estática de agente. Uma chave MCP mantém-se válida até a rodar ou eliminar.

  1. Na sua instância do Campbooks abra Definições → Acesso à API e clique em Novo cliente.
  2. Dê-lhe um nome — "Agente Claude Code" funciona bem.
  3. Selecione os scopes de que necessita (ver abaixo) e clique em Criar.
  4. Na página seguinte verá a chave MCP: uma string única na forma <client-id>.<client-secret>. Copie-a agora — é mostrada apenas uma vez. Se a perder, regenere o client secret na mesma página de Definições.
  5. Cole a chave no campo mcp_key na configuração do plugin.

Para rodar a chave mais tarde: vá a Definições → Acesso à API, encontre o cliente e regenere o seu secret. A chave antiga deixa de funcionar imediatamente.

Conjuntos de scopes​

Os scopes são um teto para o que o agente pode fazer. Scope mais restrito = menos tools em tools/list = menos contexto usado por sessão. Escolha o que realmente precisa.

Conjunto completo (recomendado para utilizadores avançados):

emails:read emails:write emails:send
tags:read tags:write
documents:read documents:write
document_types:read document_types:write
contacts:read contacts:write
calendar:read calendar:write
reminders:read reminders:write
tasks:read tasks:write
folders:read folders:write
email_accounts:read email_accounts:write
scout:read scout:write
scheduled_emails:read scheduled_emails:write

Apenas triage (leitura + skim, sem envio):

emails:read emails:write
tags:read documents:read calendar:read tasks:read reminders:read

Apenas leitura (somente consulta, sem alterações):

emails:read documents:read calendar:read tasks:read

Os três tools de contexto — get_overview, get_setup_status e guide — não requerem scope e estão sempre disponíveis para qualquer cliente autenticado.

Skills​

O plugin inclui duas skills que pode invocar diretamente numa sessão de Claude Code.

/campbooks:setup — onboarding guiado​

Execute-a na primeira vez, ou sempre que o plugin não estiver a ligar. Guia-o pelos seguintes passos, um de cada vez:

  1. Verificar a ligação MCP — chama get_setup_status. Se a chamada falhar, guia-o pela criação do cliente de API e colagem da chave MCP.
  2. Ligar uma caixa de correio — se nenhuma conta de email estiver ligada, pergunta se está no Campbooks Cloud ou a correr a sua própria instância:
    • Caminho Cloud: chama connect_email_account(mode: "web") e dá-lhe o URL OAuth para abrir num browser. Aguarde o fluxo OAuth completar e confirme.
    • Caminho auto-alojado: oferece o script auxiliar de OAuth local (ver OAuth Local abaixo).
  3. Processamento de IA — indica a sua configuração de IA atual e oferece ativar IA gerida ou orienta-o para Definições → IA para uma chave personalizada.
  4. Taxonomia — se ainda não tiver tipos de documento, etiquetas ou pastas, pergunta que tipo de trabalho a caixa de entrada trata e propõe um conjunto inicial (para aprovação antes de criar qualquer coisa).
  5. Primeira sessão de skim — carrega o baralho de skim, mostra os principais clusters e conduz pelas primeiras decisões.

A skill nunca cria nada sem um "sim" explícito da sua parte.

/campbooks:triage — sessão diária de caixa de entrada​

Execute-a sempre que quiser trabalhar o que está à espera. Percorre estes passos em ordem (qualquer passo pode ser saltado):

  1. Visão geral — chama get_overview e reporta contagem de não lidos, threads a aguardar resposta, documentos pendentes, eventos de calendário de hoje, lembretes em atraso e tarefas sugeridas. Um parágrafo curto ou lista rápida — apenas o suficiente para o orientar.
  2. Baralho de skim — carrega clusters agrupados por anel (prioridade, notificações, newsletters, etc.), propõe ações e aplica-as em lote ou uma a uma após a sua confirmação.
  3. A aguardar resposta — lista threads onde enviou a última mensagem e ainda não recebeu resposta. Redige respostas inline; envia apenas após um "sim, envia" explícito.
  4. Documentos pendentes — lista documentos a aguardar revisão. Aprove, rejeite ou reclassifique, um a um ou em lote.
  5. Tarefas e lembretes sugeridos — mostra tarefas e lembretes extraídos pela IA; confirma ou dispensa cada um após ver o título.
  6. Resumo final — emails tratados, respostas enviadas, documentos aprovados, tarefas confirmadas.

Como é uma sessão​

Aqui está uma execução típica de manhã:

> /campbooks:triage

Tem 14 emails não lidos, 2 threads a aguardar resposta sua, 3 documentos
pendentes de revisão (incluindo uma fatura da ACME de €1.290) e um lembrete
em atraso: "Entregar declaração de IVA" venceu ontem.

Baralho de skim — 4 clusters:
  Anel de prioridade
    • Faturas ACME — 2 emails — Scout sugere manter
  Anel de notificações
    • Alertas de PR do GitHub — 9 emails — sugerir arquivar
    • Recibos de pagamento Stripe — 4 emails — sugerir arquivar
  Anel de newsletters
    • Digests de produto — 6 emails — sugerir arquivar

Aplicar estas ações (exceto o manter da ACME)?

> sim

Arquivados 19 emails em 3 clusters. 2 emails mantidos.

A aguardar resposta — 2 threads:
  1. Jane na ACME — "Re: proposta Q3" — há 4 dias
  2. Onboarding bancário — "Os seus documentos" — há 2 dias

Redigir um seguimento para o thread da ACME?

> sim

"Olá Jane, só a fazer um seguimento da proposta do Q3 — posso fazer uma
chamada esta semana se ajudar. Faz saber."

Enviar esta resposta?

> sim

Enviado. A avançar para documentos...

O agente mostra o que está prestes a fazer antes de cada escrita e aguarda a sua resposta.

OAuth Local (apenas auto-alojado)​

Se os callbacks OAuth do seu servidor auto-alojado não estão acessíveis a partir da internet pública, pode criar um token de atualização localmente e passá-lo ao servidor via API MCP.

Utilizadores Cloud: use o fluxo connect_email_account(mode: "web") — a skill /campbooks:setup trata disso automaticamente.

Pré-requisitos​

  • Python 3 (apenas biblioteca padrão — sem pip install necessário).
  • As credenciais OAuth do próprio servidor — GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET ou ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET do ambiente do servidor. Um token criado com um client_id diferente falhará quando o servidor tentar atualizá-lo.
  • http://localhost:8765/callback adicionado aos URIs de redirecionamento permitidos da aplicação OAuth (Google Cloud Console → Credenciais → o seu cliente OAuth → URIs de redirecionamento autorizados; Consola de Desenvolvimento Zoho → Consola de API → o seu cliente → URIs de Redirecionamento).

Executar​

python3 integrations/claude-plugin/scripts/campbooks_oauth.py google \
  --client-id YOUR_GOOGLE_CLIENT_ID \
  --client-secret YOUR_GOOGLE_CLIENT_SECRET

# Zoho — especifique a região do centro de dados do seu servidor
python3 integrations/claude-plugin/scripts/campbooks_oauth.py zoho \
  --client-id YOUR_ZOHO_CLIENT_ID \
  --client-secret YOUR_ZOHO_CLIENT_SECRET \
  --region eu

Omita --client-id / --client-secret e o script solicita-os de forma segura. Abre o seu browser, completa o fluxo de consentimento e imprime uma linha de JSON:

{"provider": "google", "refresh_token": "1//0e..."}

A skill /campbooks:setup chama connect_email_account(mode: "token", ...) com esse token automaticamente — não precisa de colar o token no chat. Guarde-o em segurança: concede acesso total à caixa de correio.

Última atualização em