Guias
Uma aplicação, três portas: sistemas preparados para pessoas, automatismos e assistentes de IA
A Datapoint lançou o Datapoint.Mediator, uma biblioteca de código aberto que permite escrever as regras de um sistema uma única vez e oferecê-las por três portas: a API, a linha de comandos e o MCP, usado pelos assistentes de IA. Explicamos porque é que isto importa, mesmo para quem não é da área técnica.
Durante muitos anos, um sistema de informação era usado sobretudo por pessoas sentadas em frente a um ecrã. Hoje, quem lhe faz pedidos são também outros sistemas, tarefas automáticas que correm de madrugada e, cada vez mais, assistentes de inteligência artificial que trabalham em nome de alguém. Cada um destes utilizadores chega por uma porta diferente, e todos esperam que o sistema aplique as mesmas regras.
Para ajudar a construir sistemas preparados para esta realidade, a Datapoint disponibilizou o Datapoint.Mediator, uma biblioteca de código aberto e de utilização gratuita que permite escrever as regras de um sistema uma única vez e oferecê-las por três portas diferentes. A versão 4.0 está disponível em beta, e o código pode ser consultado, usado e melhorado por qualquer pessoa no repositório github.com/datapoint-software/mediator.
Um banco, três balcões
Pense no seu banco. Pode ser atendido ao balcão de uma agência, levantar dinheiro numa caixa automática ou fazer uma transferência na aplicação do telemóvel. São três formas muito diferentes de chegar ao mesmo sítio, mas as regras da sua conta são sempre as mesmas: o saldo é o mesmo, os limites são os mesmos e só quem tem autorização pode movimentar o dinheiro.
Ninguém aceitaria uma caixa automática que se esquecesse de verificar o limite diário, só porque essa verificação foi programada apenas para o balcão. E, no entanto, é exatamente isto que pode acontecer num sistema de informação quando cada forma de acesso é construída à parte.
As três portas de uma aplicação moderna
Uma aplicação da nova geração deve estar preparada para receber pedidos por três portas:
A API. Uma API, ou interface de programação de aplicações, é a forma como outros sistemas, sites e aplicações móveis comunicam com o sistema, de máquina para máquina. É a porta que já conhecemos, e continua a ser essencial.
A linha de comandos. Uma linha de comandos, ou CLI, permite dar instruções ao sistema escrevendo comandos num terminal. É usada pelas equipas técnicas e por tarefas automáticas, como o fecho do mês ou a importação noturna de dados, e é cada vez mais usada também por assistentes de IA que trabalham diretamente num terminal.
O MCP. O MCP, ou Model Context Protocol, é um padrão aberto que permite a um assistente de IA descobrir que operações um sistema oferece, perceber para que serve cada uma e pedi-las em nome de uma pessoa.
A API existe há muito tempo. A linha de comandos e o MCP são o que distingue as aplicações preparadas para a forma como se vai trabalhar nos próximos anos, em que parte das tarefas repetitivas passa a ser pedida por automatismos e por assistentes, sempre sob a responsabilidade de alguém.
O risco de fazer tudo três vezes
A forma mais óbvia de oferecer as três portas é construir cada uma à parte. O problema é que cada porta precisa de saber as mesmas coisas: quem pode fazer o quê, que dados são válidos e como se grava a informação de forma coerente. Quando essas regras são escritas três vezes, mais cedo ou mais tarde deixam de ser iguais. Uma alteração feita na API fica esquecida na linha de comandos, ou uma verificação de permissões não chega ao assistente de IA.
Se uma regra só for verificada numa das portas, as outras duas passam a ser uma forma de a contornar.
Além do risco de segurança, há o custo: cada nova operação tem de ser construída, testada e mantida três vezes, e cada nova porta que se queira abrir no futuro obriga a repetir todo o trabalho.
Um pedido, três caminhos
O Datapoint.Mediator resolve este problema separando duas coisas: o que o sistema faz, que é escrito uma única vez, e as portas por onde se chega até ele, que são apenas formas diferentes de fazer o mesmo pedido. Imagine o pedido «emitir uma fatura à Ana, no valor de 100 euros»:
| Porta | Quem a usa | Como chega o pedido |
|---|---|---|
| API | O programa de faturação, o site ou a aplicação móvel | POST /api/invoices/create |
| Linha de comandos | A equipa técnica ou a tarefa automática do fecho do mês | invoicing invoices create --customer Ana --amount 100 |
| MCP | Um assistente de IA a quem alguém pediu a fatura | A ferramenta invoices_create |
Por qualquer uma das três portas, o pedido segue exatamente o mesmo caminho dentro do sistema e passa pelas mesmas verificações:
Quem pede tem permissão? Por omissão, a resposta é não: uma operação só pode ser usada por quem tiver sido expressamente autorizado. Um assistente de IA nunca pode fazer mais do que a pessoa em nome de quem trabalha, e pode ser configurado para fazer menos.
Os dados estão certos? Um valor em falta ou mal escrito é recusado antes de qualquer alteração, com a mesma mensagem em todas as portas.
Fica tudo gravado, ou nada? Se uma operação tiver vários passos, ou são todos gravados, ou nenhum é. Não há faturas a meio.
Fica registado? Cada pedido deixa o mesmo rasto, venha de onde vier, o que facilita perceber o que aconteceu e quanto tempo demorou.
O que ganha a sua organização
Mais segurança. As regras de acesso são escritas num só sítio e aplicam-se a todas as portas. As mensagens de erro não repetem os dados enviados nem revelam detalhes internos, e as operações que alteram dados são assinaladas aos assistentes de IA como tal, para que possam pedir confirmação à pessoa antes de avançar.
Menos custo. Cada regra é escrita, testada e mantida uma vez. Abrir uma nova porta não obriga a reconstruir o sistema.
Preparado para a IA, sem recomeçar. Um sistema construído desta forma pode abrir a porta a assistentes de IA quando a organização o decidir, com as mesmas permissões que já aplica às pessoas, e escolhendo que operações ficam disponíveis.
Rasto comum. Todos os pedidos são medidos e registados da mesma forma, o que facilita a auditoria e a deteção de problemas.
Sem dependência. A biblioteca é de código aberto, com a licença MIT, e o MCP é um padrão aberto. Qualquer equipa pode usar, estudar e adaptar o código.
Três perguntas para fazer ao seu fornecedor de software
Mesmo que não seja da área técnica, pode usar estas perguntas para perceber se os sistemas da sua organização estão preparados para receber pedidos de automatismos e de assistentes de IA:
Se um assistente de IA usar o nosso sistema, fica sujeito às mesmas permissões que a pessoa em nome de quem trabalha?
As regras do sistema estão escritas uma única vez, ou repetidas em cada forma de acesso?
Podemos acrescentar uma nova forma de acesso, como uma linha de comandos ou um servidor MCP, sem reconstruir o sistema?
Para as equipas de desenvolvimento
Esta secção é mais técnica. O Datapoint.Mediator é um conjunto de pacotes NuGet para .NET 10 que implementa o padrão Mediator: os componentes enviam comandos e consultas através de um mediador, em vez de chamarem diretamente os respetivos handlers. Na versão 4.0, cada comando ou consulta pode receber um nome com o atributo [Action], e cada porta passa a ser uma linha de configuração:
// Camada de negócio: a operação é definida uma única vez
[Action("invoices.create", Description = "Creates an invoice for a customer.")]
public sealed record CreateInvoice(string Customer, decimal Amount) : ICommand<Guid>;
// Cada porta é uma linha
app.MapActions("/api"); // API: POST /api/invoices/create
root.AddActions(services); // CLI: invoicing invoices create --customer Ana --amount 100
services.AddMcpServer().WithMediatorActions(); // MCP: a ferramenta invoices_createComportamentos partilhados. Autorização (que nega por omissão), validação com FluentValidation e transações com Entity Framework Core correm por esta ordem em todas as portas, tal como os comportamentos que escrever.
O utilizador certo em cada porta. A API usa o utilizador do pedido HTTP; a linha de comandos e um servidor MCP local usam um utilizador fixo, definido no arranque.
Seguro por omissão. Uma ação sem regra de autorização é recusada; ações ocultas falham da mesma forma que ações inexistentes, para não poderem ser descobertas; os erros nunca repetem os dados recebidos; e configurações inválidas falham no arranque.
Documentação e observabilidade. A API publica metadados OpenAPI, a linha de comandos gera a ajuda de cada comando, as ferramentas MCP usam as descrições das ações, e cada pedido é medido com OpenTelemetry.
Para começar, instale os pacotes com dotnet add package Datapoint.Mediator.DependencyInjection --prerelease e explore o exemplo de faturação incluído no repositório, que oferece a mesma camada de negócio como API, linha de comandos e servidor MCP. O manual, os exemplos e o código estão em github.com/datapoint-software/mediator. Como se trata de uma versão beta, agradecemos sugestões e relatos de problemas no próprio repositório.
A nossa forma de trabalhar
Na Datapoint, desenvolvemos, integramos e mantemos sistemas de informação, e acreditamos que um bom sistema deve estar preparado para quem o vai usar amanhã, e não apenas para quem o usa hoje. Publicámos o Datapoint.Mediator como código aberto para que qualquer equipa o possa usar, estudar e melhorar. Se quer preparar os sistemas da sua organização para receber pedidos de automatismos e de assistentes de IA, conheça a nossa integração MCP ou fale connosco.
