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

- Fonte: https://doutorai.pt/apps/mcp-apps-generative-ui-showcase
- Categoria: Interfaces Generativas
- Dificuldade: Avançado
- Modelos: OpenAI, Claude, Gemini
- Frameworks: -
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY, RESOURCE_URI_META_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# MCP Apps Generative UI Showcase

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](https://github.com/CopilotKit/CopilotKit), [AG-UI](https://github.com/ag-ui-protocol/ag-ui) e [MCP Apps](https://github.com/modelcontextprotocol/ext-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

| App                         | Description                                                          | Example Prompt                                                   |
| --------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **✈️ Airline Booking**      | Assistente de 5 passos: pesquisar voos, selecionar lugares, inserir detalhes dos passageiros | "Book a flight from JFK to LAX on January 20th for 2 passengers" |
| **🏨 Hotel Booking**        | Assistente de 4 passos: pesquisar hotéis, comparar quartos, reservar alojamento      | "Find a hotel in Paris from January 15 to 18 for 2 guests"       |
| **📈 Investment Simulator** | Gestão de portfólios com gráficos ao vivo, compras/vendas               | "Create a $10,000 tech-focused portfolio"                        |
| **📋 Kanban Board**         | Gestão de tarefas com arrastar e soltar, colunas e cartões                     | "Create a kanban board for my software project"                  |

## Quick Start

### 1. Install Dependencies

```bash
# 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`:

```bash
OPENAI_API_KEY=sk-...
```

### 3. Compilar e Executar

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

1. **Instalação das Dependências**
   ```bash
   npm install
   ```

2. **Compilar o Projeto**
   ```bash
   npm run build
   ```

3. **Executar o Projeto**
   ```bash
   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:

```bash
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:
   ```bash
   git checkout -b minha-nova-funcionalidade
   ```
3. Faz as tuas alterações e commit:
   ```bash
   git commit -m "Adiciona nova funcionalidade"
   ```
4. Faz push para a branch:
   ```bash
   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).

```bash
# 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

```python
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.

```typescript
// 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:

| Serviço    | URL                                               |
| ---------- | ------------------------------------------------- |
| Web App    | https://web-app-production-9af6.up.railway.app    |
| Servidor MCP | https://mcp-server-production-bbb4.up.railway.app |

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

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/mcp-apps-generative-ui-showcase