Um Curso Intensivo em MCP: Um Guia para Iniciantes Usando TypeScript

Este post é adaptado da minha apresentação, "Um Curso Intensivo em MCP: Um Guia para Iniciantes Usando TypeScript"

A indústria de tecnologia frequentemente depende de jargões pesados para explicar conceitos simples. Se você ler a documentação oficial do Protocolo de Contexto de Modelo (MCP), ela afirma: "Um padrão de código aberto para conectar aplicações de IA... Pense nisso como uma porta USB-C para aplicações de IA."

Embora seja preciso, esse não é o modelo mental mais intuitivo para engenheiros de software.

Para mim, a maneira que fez sentido foi dar uma definição mais prática:

MCP é um conjunto de regras que define como alimentar contexto em um modelo.

Isso permite que seu agente de IA entenda os dados subjacentes e a arquitetura da sua aplicação. Em vez de digitar manualmente cargas úteis JSON ou navegar por interfaces, você pode usar comandos em linguagem natural para executar funções complexas porque o agente já tem o contexto do seu sistema.

Os Três Pilares do MCP

O protocolo opera em três primitivas principais:

• Recursos: Qualquer coisa que contenha dados. Isso pode ser um arquivo JSON estático, um documento HTML ou uma conexão com um banco de dados PostgreSQL.
• Ferramentas: Funções executáveis. Essas são as ações que seu servidor MCP expõe ao agente de IA, permitindo que o agente manipule dados ou interaja com serviços externos.
• Prompts: Instruções pré-definidas anexadas ao agente que utilizam os recursos e ferramentas disponíveis para realizar tarefas específicas.

Construindo um Servidor MCP em TypeScript

Se você já construiu um servidor básico usando ExpressJS, a arquitetura de um servidor MCP parecerá muito familiar. Você define um servidor, estabelece suas capacidades e expõe endpoints (recursos ou ferramentas).

No entanto, construir para agentes de IA introduz um desafio único em relação à integridade dos dados.

• A limitação do TypeScript: TypeScript é fantástico para a experiência do desenvolvedor, mas seus tipos são removidos na compilação. Em tempo de execução, seu servidor executa JavaScript puro.
• A variável de IA: Quando um LLM dita a entrada com base na linguagem natural, você não pode contar com verificações em tempo de compilação para garantir que a estrutura dos dados esteja correta.
• A Solução: Devemos usar bibliotecas de validação em tempo de execução como Zod.

Se sua ferramenta espera um parâmetro idade como um número, mas o LLM insere a string "vinte e cinco", o Zod captura a violação do esquema em tempo de execução, impedindo que os dados malformados corrompam seu banco de dados ou derrubem seu serviço.

Definindo Ferramentas e Metadados

Ao criar uma ferramenta—como uma função para criar um novo usuário—você deve definir metadados rigorosos. Isso dita como o LLM interage com a função:

• readOnlyHint: Defina como false se a ferramenta modificar dados (por exemplo, criando um usuário) em vez de apenas buscá-los.
• destructiveHint: Defina como true apenas se a ferramenta puder excluir ou alterar irrevogavelmente dados.
• idempotentHint: Define se executar o mesmo comando várias vezes resulta no mesmo estado sem efeitos colaterais indesejados.

Ao definir esses parâmetros, você estabelece limites sobre o que a IA pode e não pode executar de forma autônoma. Durante o desenvolvimento, você configura o cliente para solicitar autorização manual antes que o agente possa executar comandos de escrita.

Do JSON Básico às APIs do Mundo Real: A Integração com o Google Calendar

Embora testar um servidor MCP contra um arquivo JSON local seja bom para aprendizado, o verdadeiro poder do protocolo se desbloqueia ao interagir com APIs externas autenticadas.

Eu construí um servidor MCP personalizado conectado à API do Google Calendar. Ele lida com a autenticação OAuth e de token JSON, concedendo ao meu agente de IA local acesso direto à minha agenda pessoal.

Aqui está uma demonstração de dois minutos mostrando meu projeto MCP do Google Calendar.

Como o agente tem o contexto da API do calendário via o servidor MCP, posso executar comandos usando estritamente linguagem natural:

• Consultando: Posso perguntar ao agente, "O que eu tenho para 21 de setembro?" O agente lê o recurso MCP e retorna: "Seu calendário inclui NYC Code & Coffee: Um Curso Intensivo em MCP."
• Executando: Em vez de preencher manualmente formulários de eventos ou escrever solicitações de API, posso dizer ao agente, "Crie um evento: Jantar com minha esposa no dia 22 de outubro." O agente mapeia a linguagem natural para os parâmetros necessários (Título, Hora de Início, Hora de Término) e executa a ferramenta. O evento imediatamente aparece no Google Calendar.

A Realidade das Ferramentas de IA

A integração de LLMs diretamente em ambientes locais e sistemas de backend não é uma tendência passageira; é uma mudança fundamental na engenharia de software. Estamos nos movendo em direção à linguagem natural como uma camada de execução.

Como desenvolvedor, você enfrenta uma escolha distinta: aprender a construir e controlar essas ferramentas agentes para automatizar seus fluxos de trabalho, ou competir contra os engenheiros que o fazem.

Vamos nos Conectar!

• Website: callmeizzy.dev
• YouTube: Call Me Izzy
• GitHub: @MrItzreal
• X / Twitter: @fullstackizzy
• LinkedIn: Israel (Izzy) Santana