construtor-de-aplicacoes-mcp

IMPORTANTE: Como Usar Este Skill

Este arquivo fornece apenas um GUIA DE NAVEGAÇÃO. Antes de implementar qualquer recurso do servidor MCP, você DEVE:

1. Ler esta visão geral para entender quais arquivos de referência são relevantes
2. SEMPRE ler o(s) arquivo(s) de referência específico(s) para os recursos que você está implementando
3. Aplicar os padrões detalhados desses arquivos à sua implementação

Não confie apenas nos exemplos de referência rápida neste arquivo - eles são apenas exemplos mínimos. Os arquivos de referência contêm práticas recomendadas críticas, considerações de segurança e padrões avançados.

---

Práticas Recomendadas para Servidor MCP

Guia abrangente para construir servidores MCP prontos para produção com ferramentas, recursos, prompts e widgets usando mcp-use.

⚠️ PRIMEIRO: Projeto Novo ou Projeto Existente?

Antes de fazer qualquer outra coisa, determine se você está dentro de um projeto mcp-use existente.

Detecção: Verifique o espaço de trabalho por um package.json que liste "mcp-use" como dependência, OU qualquer arquivo .ts que importe de "mcp-use/server".

├─ Projeto mcp-use ENCONTRADO → Não crie a estrutura. Você já está em um projeto.
│  └─ Pule para "Navegação Rápida" abaixo para adicionar recursos.
│
├─ NENHUM projeto mcp-use (diretório vazio, projeto não relacionado ou novo)
│  └─ Crie a estrutura primeiro com npx create-mcp-use-app, depois adicione recursos.
│     Veja "Criando Estrutura de um Novo Projeto" abaixo.
│
└─ Dentro de um projeto NÃO RELACIONADO (ex: aplicativo Next.js) e o usuário quer um servidor MCP
   └─ Pergunte ao usuário onde criar o servidor, então crie a estrutura nesse diretório.
      NÃO crie a estrutura dentro da raiz de um projeto existente não relacionado.

NUNCA crie manualmente o boilerplate MCPServer, package.json ou estrutura do projeto à mão. A CLI configura TypeScript, scripts de desenvolvimento, integração com inspetor, recarga automática e compilação de widgets que são difíceis de replicar manualmente.

---

Criando Estrutura de um Novo Projeto

npx create-mcp-use-app meu-servidor
cd meu-servidor
npm run dev

Para detalhes completos da estrutura e flags da CLI, veja quickstart.md.

---

Navegação Rápida

Escolha seu caminho com base no que você está construindo:

🚀 Fundamentos

Quando: SEMPRE leia estes primeiro ao iniciar trabalho MCP em uma nova conversa. Consulte mais tarde para esclarecimento de arquitetura/conceito.

1. concepts.md - Primitivas MCP (Ferramenta, Recurso, Prompt, Widget) e quando usar cada uma
2. architecture.md - Estrutura do servidor (baseado em Hono), sistema de middleware, server.use() vs server.app
3. quickstart.md - Estruturação, configuração e primeiro exemplo de ferramenta
4. deployment.md - Implantação no Manufact Cloud, auto-hospedagem, Docker, gerenciamento de implantações

Carregue estes antes de mergulhar nas seções de ferramentas/recursos/widgets.

---

🔐 Adicionando Autenticação?

Quando: Protegendo seu servidor com OAuth (WorkOS, Supabase ou personalizado)

• overview.md

  • Quando: Primeira vez adicionando autenticação, entendendo ctx.auth, ou escolhendo um provedor
  • Cobre: Configuração oauth, formato do contexto do usuário, comparação de provedores, erros comuns

• workos.md

  • Quando: Usando WorkOS AuthKit para autenticação
  • Cobre: Configuração, variáveis de ambiente, DCR vs pré-registrado, funções/permissões, chamadas API WorkOS

• supabase.md

  • Quando: Usando Supabase para autenticação
  • Cobre: Configuração, variáveis de ambiente, HS256 vs ES256, chamadas API com suporte a RLS

• custom.md

  • Quando: Usando qualquer outro provedor de identidade (GitHub, Okta, Azure AD, Google, etc.)
  • Cobre: Verificação personalizada, extração de informações do usuário, exemplos de provedores

---

🔧 Construindo Backend do Servidor (Sem UI)?

Quando: Implementando recursos MCP (ações, dados, modelos). Leia o arquivo específico para a primitiva que você está construindo.

• tools.md

  • Quando: Criando ações de backend que a IA pode chamar (enviar-email, buscar-dados, criar-usuario)
  • Cobre: Definição de ferramenta, esquemas, anotações, contexto, tratamento de erros

• resources.md

  • Quando: Expondo dados somente leitura que os clientes podem buscar (configurações, perfis de usuário, documentação)
  • Cobre: Recursos estáticos, recursos dinâmicos, modelos de recursos parametrizados, conclusão de URI

• prompts.md

  • Quando: Criando modelos de mensagens reutilizáveis para interações de IA (revisão-de-código, resumir)
  • Cobre: Definição de prompt, parametrização, conclusão de argumentos, práticas recomendadas de prompt

• response-helpers.md

  • Quando: Formatando respostas de ferramentas/recursos (texto, JSON, markdown, imagens, erros)
  • Cobre: text(), object(), markdown(), image(), error(), mix()

---

🎨 Construindo Widgets Visuais (UI Interativa)?

Quando: Criando interfaces visuais baseadas em React para navegar, comparar ou selecionar dados

• basics.md

  • Quando: Criando seu primeiro widget ou adicionando UI a uma ferramenta existente
  • Cobre: Configuração de widget, hook useWidget(), verificações isPending, manipulação de props

• state.md

  • Quando: Gerenciando estado da UI (seleções, filtros, abas) dentro de widgets
  • Cobre: useState, setState, persistência de estado, quando usar estado de ferramenta vs widget

• interactivity.md

  • Quando: Adicionando botões, formulários ou chamando ferramentas de dentro de widgets
  • Cobre: useCallTool(), tratamento de formulários, botões de ação, atualizações otimistas

• ui-guidelines.md

  • Quando: Estilizando widgets para suportar temas, layouts responsivos ou acessibilidade
  • Cobre: useWidgetTheme(), modo claro/escuro, autoSize, padrões de layout, melhores práticas CSS

• advanced.md

  • Quando: Construindo widgets complexos com dados assíncronos, limites de erro ou otimizações de performance
  • Cobre: Estados de carregamento, tratamento de erros, memoização, divisão de código

---

📚 Precisa de Exemplos Completos?

Quando: Você quer ver implementações completas de casos de uso comuns

• common-patterns.md
  • Exemplos completos: aplicativo de clima, lista de tarefas, navegador de receitas
  • Mostra: Código do servidor + código do widget + melhores práticas em contexto

---

Árvore de Decisão

O que você precisa?

├─ Novo projeto do zero
│  └─> quickstart.md (estruturação + configuração)
│
├─ Autenticação OAuth / usuário
│  └─> authentication/overview.md → guia específico do provedor
│
├─ Ação de backend simples (sem UI)
│  └─> Use Ferramenta: server/tools.md
│
├─ Dados somente leitura para clientes
│  └─> Use Recurso: server/resources.md
│
├─ Modelo de prompt reutilizável
│  └─> Use Prompt: server/prompts.md
│
├─ UI visual/interativa
│  └─> Use Widget: widgets/basics.md
│
└─ Implantar em produção
   └─> deployment.md (implantação em nuvem, auto-hospedagem, Docker)

---

Princípios Fundamentais

1. Ferramentas para ações - Operações de backend com entrada/saída
2. Recursos para dados - Dados somente leitura que clientes podem buscar
3. Prompts para modelos - Modelos de mensagens reutilizáveis
4. Widgets para UI - Interfaces visuais quando útil
5. Dados mockados primeiro - Prototipagem rápida, conectar APIs depois

---

❌ Erros Comuns

Evite estes anti-padrões encontrados em servidores MCP de produção:

Definição de Ferramenta

• ❌ Retornar objetos brutos em vez de usar helpers de resposta
  • ✅ Use helpers text(), object(), widget(), error()
• ❌ Pular .describe() do esquema Zod em cada campo
  • ✅ Adicione descrições a todos os campos do esquema para melhor compreensão da IA
• ❌ Sem validação ou sanitização de entrada
  • ✅ Valide entradas com Zod, sanitize dados fornecidos pelo usuário
• ❌ Lançar erros em vez de retornar helper error()
  • ✅ Use error("mensagem") para respostas de erro elegantes

Desenvolvimento de Widget

• ❌ Acessar props sem verificar isPending
  • ✅ Sempre verifique if (isPending) return <Loading/>
• ❌ Widget gerencia estado do servidor (filtros, seleções)
  • ✅ Widgets gerenciam seu próprio estado de UI com useState
• ❌ Faltando wrapper McpUseProvider ou autoSize
  • ✅ Envolva o componente raiz: <McpUseProvider autoSize>
• ❌ Estilos inline sem consciência de tema
  • ✅ Use useWidgetTheme() para suporte a modo claro/escuro

Segurança e Produção

• ❌ Chaves de API ou segredos codificados no código
  • ✅ Use process.env.API_KEY, documente em .env.example
• ❌ Sem tratamento de erros em manipuladores de ferramentas
  • ✅ Envolva em try/catch, retorne error() em falha
• ❌ Operações caras sem cache
  • ✅ Cache chamadas de API, computações com TTL
• ❌ Configuração CORS ausente
  • ✅ Configure CORS para implantações de produção

---

🔒 Regras de Ouro

Diretrizes arquiteturais opinativas:

1. Uma Ferramenta = Uma Capacidade

Divida ações amplas em ferramentas focadas:

• ❌ gerenciar-usuarios (muito vago)
• ✅ criar-usuario, excluir-usuario, listar-usuarios

2. Retorne Dados Completos de Uma Vez

Chamadas de ferramentas são caras. Evite carregamento preguiçoso:

• ❌ listar-produtos + obter-detalhes-produto (2 chamadas)
• ✅ listar-produtos retorna dados completos incluindo detalhes

3. Widgets Controlam Seu Próprio Estado

O estado da UI reside no widget, não em ferramentas separadas:

• ❌ Ferramenta selecionar-item, ferramenta definir-filtro
• ✅ Widget gerencia com useState ou setState

4. exposeAsTool Padrão é false

Widgets são registrados apenas como recursos por padrão. Use uma ferramenta personalizada (recomendado) ou defina exposeAsTool: true para expor um widget ao modelo:

// ✅ TODOS OS 4 PASSOS NECESSÁRIOS para inferência de tipo correta:

// Passo 1: Defina o esquema separadamente
const propsSchema = z.object({
  titulo: z.string(),
  itens: z.array(z.string()),
});

// Passo 2: Referencie a variável do esquema nos metadados
export const widgetMetadata: WidgetMetadata = {
  description: "...",
  props: propsSchema, // ← NÃO inline z.object()
  exposeAsTool: false,
};

// Passo 3: Inferir o tipo Props da variável do esquema
type Props = z.infer<typeof propsSchema>;

// Passo 4: Use Props tipadas com useWidget
export default function MeuWidget() {
  const { props, isPending } = useWidget<Props>(); // ← Adicione <Props>
  // ...
}

⚠️ Erro comum: Fazer apenas os passos 1-2, mas pular 3-4 (perde segurança de tipo)

5. Valide Apenas nas Fronteiras

• Confie no código interno e garantias do framework
• Valide entrada do usuário, respostas de API externas
• Não adicione tratamento de erro para cenários que não podem acontecer

6. Prefira Widgets para Navegar/Comparar

Em caso de dúvida, adicione um widget. UI visual melhora:

• Navegação por múltiplos itens
• Comparação lado a lado de dados
• Fluxos de seleção interativos

---

Referência Rápida

Servidor Mínimo

import { MCPServer, text } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "meu-servidor",
  title: "Meu Servidor",
  version: "1.0.0",
});

server.tool(
  {
    name: "saudar",
    description: "Saudar um usuário",
    schema: z.object({ nome: z.string().describe("Nome do usuário") }),
  },
  async ({ nome }) => text("Olá " + nome + "!"),
);

server.listen();

---

Helpers de Resposta

Helper	Use Quando	Exemplo
text()	Resposta de string simples	text("Sucesso!")
object()	Dados estruturados	object({ status: "ok" })
markdown()	Texto formatado	markdown("# Titulo\nConteudo")
widget()	UI visual	widget({ props: {...}, output: text(...) })
mix()	Múltiplos conteúdos	mix(text("Oi"), image(url))
error()	Respostas de erro	error("Falha ao buscar dados")
resource()	Incorporar referências de recursos	resource("docs://guia", "text/markdown")