Gerar widgets de aplicação MCP com ferramentas de geração de código por IA

[Este tópico é documentação de pré-lançamento e está sujeito a alterações.]

Este artigo explica como usar ferramentas de geração de código por IA, como o GitHub Copilot CLI ou o Claude Code, para gerar aplicações interativas do protocolo de contexto do modelo (MCP) para as suas ferramentas Power Apps MCP orientadas por modelos. As aplicações MCP são ficheiros HTML autónomos que renderizam visualmente a saída JSON de uma ferramenta sob forma de cartões, gráficos, dashboards ou mapas dentro de qualquer host compatível com MCP Apps, incluindo Microsoft 365 Copilot, Claude e Visual Studio Code.

Se tiver uma ferramenta MCP que devolve dados JSON, a competência generate-mcp-app-ui pode produzir um widget polido e com suporte de tema que apresenta esses dados num formato visual compacto diretamente dentro de uma conversação do chat.

O que pode fazer com a competência generate-mcp-app

• Cria widgets visuais para qualquer ferramenta MCP descrevendo o que queres e colando a saída JSON da ferramenta.
• Escolha o visual certo para os seus dados, como gráficos para tendências numéricas, cartões para registos estruturados, tabelas para comparações, mapas para coordenadas, e assim por diante.
• Suporta automaticamente temas claros e escuros através de tokens de design Fluent UI.
• Adicione interatividade para que os widgets possam chamar a sua ferramenta novamente em tempo de execução (por exemplo, um botão de atualização).
• Refinar a experiência de utilizador de forma iterativa descrevendo alterações na linguagem natural. Por exemplo, "tornar a galeria compacta", "adicionar um gráfico" ou "usar um layout de cartão."

Pré-requisitos

Requisitos de software

Requisitos adicionais

• Uma ferramenta MCP que devolve a saída JSON. O tipo de saída da sua ferramenta deve estar definido como JSON.
• Uma ligação à internet a funcionar. Os widgets carregam o Fluent UI e outras bibliotecas a partir da Content Delivery Network (CDN) em tempo de execução.

Instala o plugin

Execute o seguinte comando de instalação a partir do GitHub Copilot CLI ou Claude Code. O instalador deteta automaticamente as ferramentas disponíveis e instala todos os plugins do Power Platform, incluindo generate-mcp-app-ui.

/plugin marketplace add microsoft/power-platform-skills

Para instalar apenas a competência do widget da Aplicação MCP:

/plugin install mcp-apps@power-platform-skills

Visão geral das competências

A competência também é ativada por frases em linguagem natural como "criar um widget", "criar um widget para a minha ferramenta" ou "criar uma aplicação MCP".

Gerar um widget

Siga estes passos para criar um novo widget para uma ferramenta MCP.

1. Crie e teste uma ferramenta personalizada feita por designers de aplicações orientadas a modelos e copie o resultado JSON completo. Certifica-te de que o tipo de saída da ferramenta está definido como JSON. Mais informações: Criar ferramentas personalizadas

2. Invocar a habilidade e descrever o que você quer que seja exibido, colando a saída JSON na conversa:

   /generate-mcp-app-ui Visualizes flights using an animated arc map for routes and a synchronized Gantt timeline for departure and arrival schedules, enabling quick understanding of flight coverage, timing, and overlaps. Here's an example of the tool's output: {"flight_records":[{"Departure Time":"2024-07-02T05:00:00Z","Arrival Time":"2024-07-02T07:30:00Z","Flight Name":"Zava 1001","Status":"Active","Airport":"Seattle-Tacoma","Airport1":"Los Angeles Intl"},{"Departure Time":"2024-07-02T03:00:00Z","Arrival Time":"2024-07-02T10:00:00Z","Flight Name":"Zava 103","Status":"Active","Airport":"Seattle-Tacoma","Airport1":"Hartsfield-Jackson"}]}
   

3. Revise o ficheiro HTML gerado. A capacidade escreve um ficheiro HTML autónomo, por exemplo flight-map.html, no seu diretório de trabalho.

4. Pré-visualização num navegador. Abrir o ficheiro HTML localmente, uma vez que o widget tem a opção de recurso para testes. Podes pedir ao agente de chat para adicionar uma pré-visualização HTML independente caso falte.

5. Iterar. Descreva quaisquer alterações diretamente no chat:

   • "Faz o mapa maior"
   • "Adicionar sugestões de ferramenta no Gráfico"
   • "Diminuir a altura e encaixar 250 píxeis com layout responsivo e sem barras de scroll"

Implementa o teu widget

Quando o seu widget estiver pronto, copie o ficheiro HTML para a entrada UX da ferramenta correspondente e ele será devolvido como a resposta da interface da ferramenta. Consulte a documentação de criação de ferramentas personalizadas para mais detalhes.

Adicionar interatividade com callServerTool

Se também fornecer o nome da sua ferramenta ao invocar a competência, o widget gerado pode incluir uma integração interativa com chamadas para a ferramenta. Isto permite que o widget volte a chamar a sua ferramenta em tempo de execução. Por exemplo, um botão de atualização na experiência do utilizador da ferramenta pode chamar-se a si próprio.

/generate-mcp-app-ui Show the current weather conditions with a refresh button. Tool name: get_weather. Tool output: {"city":"Seattle","temp_f":54,"condition":"Overcast","humidity":78,"forecast":[...]}

A funcionalidade conecta app.callServerTool ao widget para que, quando os utilizadores selecionam Atualizar, o widget obtenha dados atualizados diretamente a partir da sua ferramenta. Se não fornecer um nome de ferramenta, o widget é só de leitura e compõe apenas os dados entregues através da chamada de retorno ontoolresult.

• Microsoft 365 Copilot Chat: consulte Aplicações MCP no Copilot Chat para caminhos de implementação, incluindo sideloading para testes, implementação através do centro de administração do Microsoft 365 para utilização organizacional e publicação na loja de agentes Microsoft 365.
• Agentes declarativos Power Apps: Consulte a documentação de agentes declarativos Power Apps MCP para saber como ligar ferramentas MCP a aplicações orientadas a modelos.
• Outros anfitriões MCP: Consulte a documentação do seu anfitrião para o processo de registo do widget das aplicações MCP.

Detalhes técnicos do widget

Protocolo de aplicações MCP

Os widgets comunicam com o anfitrião do chat usando a App classe do @modelcontextprotocol/ext-apps pacote. O protocolo gere estas chamadas de retorno e métodos.

Importações CDN

Os widgets carregam todas as dependências a partir da CDN. Não é necessário nenhum passo de construção ou instalação local. As dependências apresentam-se em dois formatos:

• Módulos ECMAScript (ESM) — importados no interior <script type="module"> usando uma URL terminada em /+esm

• Definição Universal de Módulo (UMD) — carregada através de uma etiqueta simples <script src> ; regista-se globalmente como efeito secundário

  Biblioteca	Formato	URL	Propósito
  @modelcontextprotocol/ext-apps	ESM	cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm	Classe de aplicações App MCP
  @fluentui/tokens	ESM	cdn.jsdelivr.net/npm/@fluentui/tokens/+esm	webLightTheme / webDarkTheme Conjuntos de tokens
  @fluentui/web-components@beta	UMD	unpkg.com/@fluentui/web-components@beta/dist/web-components.min.js	Elementos personalizados do Fluent UI

Estados visuais

Cada widget gere três estados:

Componentes de interface fluente

Os seguintes componentes web da Fluent UI estão disponíveis em widgets:

<fluent-card>, <fluent-button>, <fluent-text-input>, <fluent-textarea>, <fluent-dropdown>, <fluent-listbox>, <fluent-option>, <fluent-checkbox>, <fluent-spinner>, <fluent-divider>, <fluent-badge>, <fluent-switch>, <fluent-tooltip>

Suporte ao tema

Os widgets suportam temas claro e escuro através de tokens de design Fluent UI. O widget aplica os valores corretos dos tokens quando o tema do anfitrião muda via onhostcontextchanged. Use sempre variáveis de token, por exemplo, var(--colorNeutralForeground1), em vez de valores de cor codificados fixamente para garantir a renderização correta em ambos os temas.

Tokens de cor

Nunca uses valores hexidecimais ou RGB codificados fixamente. Não invente nomes de tokens que não estejam listados aqui.

Melhores práticas

• Forneça dados reais de teste. A funcionalidade analisa a estrutura JSON real para selecionar a visualização apropriada. Os widgets produzidos por dados simulados danificam-se quando ligados à ferramenta real.
• Sê específico quanto ao visual. Descreve o formato que queres, como mapa, gráfico, mesa ou layout de cartas. Descrições vagas levam a resultados genéricos.
• Começa com uma única perspetiva. Widgets são cartões de conversa compactos, não aplicações completas. Sem pestanas, navegação de páginas ou barras de pesquisa que dupliquem a área de entrada do chat.
• Teste com ambos os temas. Pré-visualiza em modo claro e escuro para verificar contraste e legibilidade.
• Compare o visual com os dados. Mapas para coordenadas, gráficos para dados numéricos ou de tendência, cartões para registos estruturados, tabelas para comparações.

Limitações

• Os widgets devem carregar todas as bibliotecas externas a partir da CDN. É necessária uma ligação à internet em tempo de execução.
• O modo de exibição em ecrã completo requer uma implementação adicional para além do que a habilidade gera.
• A funcionalidade não lida com o registo do servidor MCP nem com a implementação no centro de administração do Microsoft 365. Deve completar esses passos separadamente.
• A autenticação (OAuth 2.1, Microsoft Entra SSO) é gerida pelo ambiente anfitrião MCP, não pelo próprio HTML do widget.

Documentação relacionada

Documentação para programadores do Microsoft 365

• Aplicações MCP agora disponíveis no Copilot Chat
• Toolkit de Agentes do Microsoft 365

Documentação da Power Platform

• Criar e editar páginas generativas com ferramentas de geração de código por IA
• Referência CLI da Power Platform

Referências externas

• Especificação do Protocolo de Contexto de Modelo (MCP)
• Componentes Web de Interface Fluente
• Repositório de Competências da Power Platform