Demonstração de UI Generativa de Aplicações MCP

https://github.com/user-attachments/assets/48eeab8d-7845-4d06-83ef-d518a807da03

Reserva de voos, reserva de hotéis, gestão de portfólios e execução de um quadro kanban - tudo dentro do chat. Construído com CopilotKit, AG-UI e MCP Apps, a mostrar a Extensão MCP Apps (SEP-1865) para renderizar UIs interativas diretamente no chat.

Conceito Gen UI - apps em chat isoladas sobre um protocolo de ferramentas. O servidor MCP regista ferramentas (workout-generator, create-portfolio, create-board…) e liga cada uma a um recurso HTML/JS através de _meta["ui/resourceUri"]. Quando o agente chama uma ferramenta, o CopilotKit monta a app ligada como um iframe isolado no chat; o iframe comunica de volta com as ferramentas MCP através de JSON-RPC postMessage. Resultado: superfícies de produto completas e interativas (assistentes de múltiplos passos, quadros de arrastar e soltar, gráficos ao vivo) a funcionar em linha - lógica propriedade do servidor, apresentação propriedade do chat.

Live Demo

https://web-app-production-9af6.up.railway.app

Featured Apps

Quick Start

1. Install Dependencies

# From the mcp-apps directory
npm install

cd mcp-server
npm install
cd ..

2. Definir Variáveis de Ambiente

Cria um ficheiro .env.local no diretório mcp-apps:

OPENAI_API_KEY=sk-...

3. Compilar e Executar

Para compilar e executar o projeto, segue os passos abaixo:

1. Instalação das Dependências

npm install

2. Compilar o Projeto

npm run build

3. Executar o Projeto

npm start

Após executar o comando npm start, o projeto estará disponível em http://localhost:3000.

4. Testes

Para executar os testes, utiliza o seguinte comando:

npm test

5. Contribuição

Se desejas contribuir para este projeto, por favor, segue estas instruções:

1. Faz um fork do repositório.
2. Cria uma nova branch para a tua funcionalidade ou correção de bug:

git checkout -b minha-nova-funcionalidade

3. Faz as tuas alterações e commit:

git commit -m "Adiciona nova funcionalidade"

4. Faz push para a branch:

git push origin minha-nova-funcionalidade

5. Cria um Pull Request.

6. Licença

Este projeto está licenciado sob a Licença MIT. Para mais informações, consulta o ficheiro [LICENSE](LICENSE).

# Terminal 1: Build and run MCP Server
cd mcp-server
npm run build
npm run dev
# Server runs at http://localhost:3001/mcp

# Terminal 2: Run Next.js Frontend (from mcp-apps directory)
npm run dev
# Frontend at http://localhost:3000

Open http://localhost:3000 e experimenta um dos exemplos de prompts!

Como Funciona

As MCP Apps são aplicações interativas em HTML/JS que são renderizadas em iframes isolados dentro da barra lateral de chat. Elas comunicam-se com o servidor MCP através de JSON-RPC sobre postMessage.

User: "Book a flight from JFK to LAX"
        ↓
AI calls search-flights tool
        ↓
MCPAppsMiddleware intercepts, fetches HTML resource
        ↓
CopilotKit renders flights-app.html in iframe
        ↓
User interacts with wizard UI
        ↓
UI calls MCP tools via postMessage → server

Padrão de Registo de Ferramentas

O padrão de registo de ferramentas é uma abordagem que permite que as ferramentas sejam registadas e utilizadas de forma consistente em diferentes partes de uma aplicação. Este guia irá mostrar-te como implementar este padrão.

Estrutura do Padrão

1. Interface da Ferramenta

• Define os métodos que todas as ferramentas devem implementar.

2. Implementação da Ferramenta

• Cada ferramenta deve implementar a interface definida.

3. Registo da Ferramenta

• Um sistema para registar e recuperar ferramentas.

Exemplo de Implementação

class ToolInterface:
    def execute(self):
        pass

class MyTool(ToolInterface):
    def execute(self):
        print("Executando MyTool")

class ToolRegistry:
    def __init__(self):
        self.tools = {}

    def register_tool(self, name, tool):
        self.tools[name] = tool

    def get_tool(self, name):
        return self.tools.get(name)

# Registar a ferramenta
registry = ToolRegistry()
registry.register_tool("my_tool", MyTool())

# Recuperar e executar a ferramenta
tool = registry.get_tool("my_tool")
if tool:
    tool.execute()

Considerações Finais

Ao implementar o padrão de registo de ferramentas, assegura-te de que as ferramentas são facilmente extensíveis e que o sistema de registo é eficiente. Este padrão pode ajudar a manter a tua aplicação organizada e facilitar a adição de novas funcionalidades no futuro.

// Tool declares its UI resource via _meta
server.registerTool(
  "search-flights",
  {
    inputSchema: { origin, destination, departureDate, passengers },
    _meta: { "ui/resourceUri": "ui://flights/flights-app.html" },
  },
  handler,
);

// Resource serves the HTML
server.registerResource(
  "flights-app",
  "ui://flights/flights-app.html",
  {
    mimeType: "text/html+mcp", // Marks as MCP App
  },
  () => ({ contents: [{ text: htmlContent }] }),
);

Estrutura do Projeto

mcp-apps/
├── src/app/
│   ├── page.tsx                    # Main demo page
│   └── api/copilotkit/route.ts     # CopilotKit + MCPAppsMiddleware
├── mcp-server/
│   ├── server.ts                   # MCP server with all tools
│   ├── src/
│   │   ├── flights.ts              # 15 airports, 6 airlines
│   │   ├── hotels.ts               # 10 cities, 30 hotels
│   │   ├── stocks.ts               # 18 stocks, portfolios
│   │   └── kanban.ts               # Board templates
│   └── apps/
│       ├── flights-app.html        # Airline booking wizard
│       ├── hotels-app.html         # Hotel booking wizard
│       ├── trading-app.html        # Investment simulator
│       └── kanban-app.html         # Kanban board
└── README.md

Tecnologias Chave

• CopilotKit (@copilotkit/*) - Interface de chat AI com suporte para Apps MCP
• AG-UI MCP Apps Middleware - Faz a ponte entre servidores MCP e CopilotKit
• MCP SDK (@modelcontextprotocol/sdk) - Servidor do Protocolo de Contexto de Modelo
• Vite - Agrupa cada app em ficheiros HTML autónomos

Implementação

A demonstração está implementada no Railway com dois serviços:

Para produção, define a variável de ambiente MCP_SERVER_URL para apontar para o teu servidor MCP implementado.