Revise antes de registrar
Confira o resumo atual primeiro; registros do ledger são dados financeiros, e uma entrada duplicada é mais difícil de analisar do que uma entrada ausente.
ledger({ action: "summary", months: 1 })Ferramenta MCP pública
ledger
Finalidade
Gerencie transações financeiras e lembretes de renovação de serviços externos por meio do dispatcher do Ledger, com resumos estruturados e limites de auditoria.
Quando usar
- Registre uma despesa ou outra transação compatível com valor, moeda, data e contexto do comerciante.
- Liste, resuma ou veja uma visão geral de registros autorizados do Ledger com filtros de data, categoria, moeda ou projeto.
- Crie ou gerencie lembretes de renovação de assinaturas e, opcionalmente, vincule o ciclo de revisão a TODOs.
Quando NÃO usar
- Não use remember genérico para registros financeiros; ledger preserva o contrato de dados financeiros.
- Não infira um total entre moedas; os resumos mantêm as moedas separadas quando a agregação não é segura.
- Não atualize nem exclua um registro sem o ID/versão exatos exigidos e a autorização do usuário.
- A API REST aceita um conjunto de campos mais amplo que a ferramenta MCP pública; consulte /docs/api/memory para os filtros de scope, bucket, team e provenance.
Escopo necessário
- As ações de leitura exigem memory:read; alterações de transações e assinaturas exigem memory:write na superfície pública de chat.
- O limite de owner/equipe/escopo autenticado governa todas as operações de registro e lembrete do Ledger.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
action | add_expense | list | summary | overview | update_transaction · obrigatório | Operação do Ledger escolhida pelo chamador. Somente estes cinco valores literais são aceitos. |
item / amount / transaction_type / currency | string / number | Campos essenciais da transação; amount e currency são obrigatórios para gravações financeiras. |
transaction_date / category / merchant / payment_method / note | string | Campos opcionais de classificação, data e observação da transação. |
query / date_from / date_to / min_amount / max_amount | string / number | Filtros de lista e resumo. |
transaction_id / expected_version / patch | string / integer / object | Alvo exato da atualização, versão de concorrência otimista e campos de atualização permitidos. |
owner_timezone / project_id | string | Interpretação de datas e limite autorizado do projeto/equipe. |
limit / offset / months | integer / boolean · padrão: 20 / 0 / 6 / false | Controles de paginação, horizonte do resumo e saída estruturada. |
Esquema de retorno
A saída estruturada contém a transação, os grupos do resumo ou a visão geral solicitada, além de um resumo em texto voltado ao usuário. Chamadores de widget podem receber metadados de atualização; segredos brutos nunca fazem parte do contrato de resposta.
Exemplos
ledger({
action: "add_expense",
item: "Domain renewal",
amount: 18.00,
currency: "USD",
transaction_date: "2026-08-21",
category: "software"
})ledger({ action: "summary", months: 1 })Erros
- Falha de autorização: o token não possui memory:read para leituras ou memory:write para alterações.
- Falha de validação: campos obrigatórios da transação, formatos de data, moeda ou valores da ação são inválidos.
- Falha de concorrência: uma atualização tem expected_version antigo ou a transação exata não foi encontrada.
- Limite de agregação: registros em moedas diferentes são informados separadamente em vez de produzir um total combinado falso.
Ferramentas relacionadas
Origem: Referência MCP