Documentação Técnica do AI Navigation Layer

Guia completo de arquitetura, contratos de atributos semânticos, integração de ferramentas MCP, políticas de segurança e otimizações de performance.

01. Visão Geral & Conceito

O que é o AI Navigation Layer?

O AI Navigation Layer é uma camada de engenharia que torna aplicações web compreensíveis e navegáveis por agentes de inteligência artificial sem necessidade de automações frágeis de tela (screen scraping) nem envio de código HTML massivo para modelos de linguagem.

Através de metadados semânticos padronizados no DOM integrados a um servidor local do Model Context Protocol (MCP), o agente descobre ferramentas disponíveis, entende a hierarquia da tela e conduz o usuário com segurança até o recurso desejado.

02. Padrão de Semântica no DOM

Atributos do Contrato MCP

Componentes visuais são decorados com atributos padronizados data-mcp-*:

data-mcp-resource

Identifica o tipo de recurso de negócio (ex: certificates, course, progress).

data-mcp-resource-id

Identificador específico da instância do recurso (ex: react-avancado).

data-mcp-action

Ação permitida sobre o recurso: navigate, open, view, execute, create.

data-mcp-description

Descrição semântica de alto nível destinada à compreensão do agente de IA.

data-mcp-access

Nível de acesso esperado: public, student, teacher, admin.

data-mcp-parent

Identificador do recurso pai, utilizado pelo scanner para construir a árvore e breadcrumbs.

03. Guia de Implementação

Como criar um <MCPResource />

Para tornar qualquer componente existente navegável pela IA, envolva-o com MCPResource ou use MCPNavigation:

import { MCPResource } from "@/components/mcp/MCPResource";
import { MCPNavigation } from "@/components/mcp/MCPNavigation";

export function CertificateBadge() {
  return (
    <MCPResource
      resource="course_certificate"
      resourceId="react-avancado"
      action="view"
      description="Visualizar certificado emitido do curso React Avançado"
      parent="course_react-avancado"
      access="student"
      context={{ courseId: "react-avancado" }}
    >
      <MCPNavigation
        href="/dashboard/courses/react-avancado/certificate"
        resource="course_certificate"
        description="Acessar certificado"
      >
        <span>Ver Certificado</span>
      </MCPNavigation>
    </MCPResource>
  );
}

04. Segurança & Autorização

Princípios Fundamentais de Segurança

1. A IA NUNCA é camada de autorização: O fato de um recurso estar visível no DOM ou ter sido mencionado em uma conversa não concede permissão de execução. O motor de autorização verifica o papel do usuário (RBAC) com validação estrita antes de permitir a navegação ou mutação.

2. Safe Route Registry vs. URLs arbitrárias: A IA retorna apenas tokens tipados (resourceId). As URLs são resolvidas exclusivamente no código do cliente através do routeRegistry. Isso extingue riscos de Open Redirect, Server-Side Request Forgery (SSRF) ou injeção de links maliciosos gerados pelo modelo.

05. Economia de Tokens & Performance

Por que não enviar todo o HTML para a IA?

Uma página web típica carrega entre 15.000 e 80.000 tokens de HTML, SVG, estilos inline e scripts. Enviar esse volume para cada consulta do usuário provoca:

Custo proibitivo de API por requisição.
Latência elevada (2 a 5 segundos extras de processamento).
Risco de vazamento de dados confidenciais (PII) renderizados na tela.
Alucinação do modelo por excesso de ruído visual.

Com o MCP DOM Scanner, o payload enviado ao agente é reduzido para menos de 350 tokens, representando uma economia de 96% a 99% de consumo computacional.