De Comandos Slash ao MCP: A Evolução do Dio Explorer e o Significado para o Dev Moderno

Introdução

Todo projeto de software tem um momento de inflexão — um ponto em que a arquitetura que funcionou perfeitamente na fase inicial começa a mostrar os seus limites naturais.

Com o DIO Explorer, esse momento chegou quando a pergunta mudou de "como um desenvolvedor chama essas funções?" para "como um agente de IA chama essas funções?".

Este artigo documenta a jornada técnica do DIO Explorer da v1.0.0 (um sistema de comandos slash em TypeScript) até a v1.2.0 (um servidor MCP completo, acessível por qualquer agente de IA).

Vamos explorar o que mudou, por que mudou, quais foram os ganhos reais, e — com honestidade técnica — quais são as desvantagens e os cuidados que essa transição exige.

O Ponto de Partida: Comandos Slash (v1.0.0)

O DIO Explorer nasceu como um sistema de comandos slash interativos. A ideia era simples e elegante: uma interface de texto onde o usuário digita comandos como /trilha Python ou /desafio Java Intermediário e recebe uma resposta formatada em Markdown.

Como funcionava

// Interface central — commands/index.ts
import processarComando from './commands';

const resultado = processarComando('/trilha Python');
console.log(resultado);
// → Plano de estudos completo em Markdown

O roteador central commands/index.ts recebia uma string, fazia o parse do comando e dos argumentos, e despachava para a função correspondente:

/trilha Python
  │
  ▼ processarComando()
  │
  ├─► executarComandoTrilha('Python')      → Markdown
  ├─► executarComandoDesafio('Java', 'Intermediário') → Markdown
  └─► executarComandoCertificado('João', 'React')     → Markdown + arquivo .md

O que havia de bom nessa abordagem

A arquitetura v1.0.0 era sólida e bem testada:

• ✅ 101 testes automatizados, 100% aprovados
• ✅ Zero dependências externas — apenas fs e path nativos do Node.js
• ✅ Execução em 0,17 segundos para a suite completa
• ✅ Código limpo, modular e fácil de entender
• ✅ Sem configuração — npx ts-node commands/index.ts e funcionava

O limite que surgiu

O problema não estava no código — estava no consumidor. Os comandos slash só podiam ser chamados por código TypeScript que importasse processarComando() diretamente. Para um agente de IA como o IBM Bob ou o Claude interagir com o sistema, seria necessário que o agente gerasse e executasse código TypeScript a cada chamada — frágil, lento e impossível de padronizar.

A questão central era: como expor uma funcionalidade para que qualquer agente de IA possa usá-la, sem depender da linguagem ou do ambiente de execução do agente?

A resposta foi o MCP.

O Model Context Protocol (MCP): Conceito em 3 Minutos

O Model Context Protocol é um padrão aberto criado pela Anthropic que define como agentes de IA se comunicam com serviços externos. Funciona como um contrato: o servidor MCP declara quais ferramentas oferece (com nome, descrição e schema de entrada), e o agente chama essas ferramentas usando JSON-RPC via stdio.

┌─────────────┐         stdio (JSON-RPC)          ┌──────────────────┐
│   IBM Bob   │  ──────────────────────────────▶  │  Servidor MCP    │
│  (cliente)  │  ◀──────────────────────────────  │  (dio-explorer)  │
└─────────────┘                                    └──────────────────┘
    │                                                    │
"Busque a trilha de Python"              buscar_trilha({ tecnologia: "Python" })
    │                                                    │
    └──── resposta em Markdown ◀─────────────────────────┘

A vantagem imediata: o agente não precisa saber nada sobre TypeScript, Node.js ou a estrutura interna do projeto. Ele só precisa conhecer o nome da ferramenta e seus parâmetros — informações que o próprio servidor declara automaticamente.

A Transição: v1.0.0 → v1.0.1

O que foi criado

Um subprojeto independente mcp/ com quatro arquivos principais:

ArquivoResponsabilidademcp/src/index.tsServidor MCP — inicialização, roteamento, error handlingmcp/src/tools.tsSchemas Zod + definições + handlers das ferramentasmcp/src/services.tsLógica de negócio (espelha commands/, mas independente)mcp/src/types.tsInterfaces TypeScript compartilhadas

Mapeamento comando → ferramenta MCP

Antes (v1.0.0)Depois (v1.0.1)Parâmetros/trilha <tecnologia>buscar_trilha{ tecnologia: string }/desafio <tecnologia> [nivel]gerar_desafio{ tecnologia, nivel? }/certificado "<nome>" "<tech>"gerar_certificado{ nome, tecnologia }/helplistar_tecnologias{}

A diferença que o desenvolvedor sente

Antes — para chamar /trilha Python via agente de IA, o agente precisava:

1. Saber que existia um arquivo commands/index.ts
2. Importar ou executar o arquivo
3. Chamar processarComando('/trilha Python')
4. Capturar o console.log ou o retorno da função

Depois — o agente simplesmente pede em linguagem natural:

"Busque informações sobre a trilha de Python"

E o Bob chama automaticamente buscar_trilha({ tecnologia: "Python" }) — sem que o usuário precise saber nada sobre a implementação interna.

Mudança técnica mais relevante: validação centralizada

Na v1.0.0, cada comando fazia sua própria validação manualmente:

// commands/trilha.ts — validação manual
if (!tecnologia) {
return '❌ Por favor, especifique uma tecnologia.';
}

Na v1.0.1, toda validação passou a ser declarada com Zod schemas antes da execução:

// mcp/src/tools.ts — validação declarativa com Zod
export const buscarTrilhaSchema = z.object({
tecnologia: z.string().min(1)
  .describe('Nome da tecnologia ou trilha a buscar (ex: Python, Java, React)')
});

Essa mudança tem um efeito colateral valioso: a descrição do parâmetro vai direto para o agente de IA, que usa essa informação para preencher os argumentos corretamente.

A Evolução Continuou: v1.1.0 e v1.2.0

v1.1.0 — Flash Cards como novo comando

O comando /cards foi adicionado ao sistema de comandos slash, trazendo 24 flash cards de estudo para 4 tecnologias (Python, Java, JavaScript, React) com 16 categorias e 450 XP total disponível. Métricas de performance medidas em runtime:

MétricaValorTempo médio por chamada< 1 ms4.000 chamadas consecutivas2,06 sDependências externas novasNenhuma

v1.2.0 — gerar_cards completa a cobertura MCP

A quinta ferramenta foi adicionada ao MCP, expondo o /cards com um diferencial importante: o modo gerar. Nesse modo, a ferramenta não retorna dados estáticos — ela monta um prompt estruturado para que o próprio Bob gere novos flash cards em formato JSON:

{
"name": "gerar_cards",
"arguments": {
  "tecnologia": "Python",
  "categoria": "Asyncio",
  "quantidade": 3,
  "dificuldade": "Difícil",
  "modo": "gerar"
}
}

O Bob recebe o prompt, raciocina sobre o conteúdo técnico de Python/Asyncio e devolve os cards prontos para serem adicionados à base. Isso transforma o MCP num pipeline de geração de conteúdo via IA, não apenas de consulta.

Vantagens da Arquitetura MCP

1. Agnóstico de linguagem e ambiente

O servidor MCP fala JSON-RPC via stdio. Qualquer cliente que implemente o protocolo — Bob, Claude Desktop, uma aplicação própria — pode usar as ferramentas sem importar nada, sem conhecer TypeScript, sem saber onde os arquivos estão no disco.

2. Descoberta automática de ferramentas

O agente lista as ferramentas disponíveis chamando ListTools. O servidor responde com nome, descrição e schema de cada ferramenta. O Bob usa essas informações para decidir quando e como chamar cada tool sem instrução explícita do usuário.

Usuário: "Me ajude a aprender React"

Bob:  1. Chama listar_tecnologias() → confirma que React existe
    2. Chama buscar_trilha({ tecnologia: "React" }) → plano de estudos
    3. Chama gerar_cards({ tecnologia: "React" }) → flash cards de revisão
    4. Chama gerar_desafio({ tecnologia: "React", nivel: "Básico" }) → desafio prático

Nenhuma dessas etapas foi instruída explicitamente — o Bob as derivou a partir das descrições das ferramentas.

3. Validação antes da execução

Com Zod schemas declarados, erros de entrada são detectados e reportados antes que a lógica de negócio seja sequer chamada. O handler nunca recebe dados inválidos.

4. Separação de responsabilidades mais clara

CamadaResponsabilidadeArquivoProtocoloComunicação com o agentemcp/src/index.tsContratoSchemas e definições das toolsmcp/src/tools.tsNegócioLógica de consulta e geraçãomcp/src/services.tsTiposInterfaces compartilhadasmcp/src/types.ts

5. Extensibilidade sem regressão

Adicionar uma nova ferramenta ao MCP não afeta as ferramentas existentes. O contrato de cada tool é isolado — schema, handler e descrição são independentes entre si.

6. Reutilizável por múltiplos agentes simultaneamente

O mesmo servidor MCP pode ser conectado ao Bob no VS Code, ao Claude Desktop e a uma aplicação web ao mesmo tempo. Cada cliente recebe suas respostas de forma independente.

Desvantagens e Cuidados

Ser honesto sobre os custos de uma transição arquitetural é tão importante quanto celebrar os ganhos. Aqui estão os pontos que exigem atenção real.

1. Duplicação da lógica de negócio

O maior custo técnico desta transição foi ter de reimplementar a lógica que já existia em commands/ dentro de mcp/src/services.ts. Isso não é opcional: o servidor MCP é um processo Node.js separado (type: "module", ES Modules) enquanto o projeto raiz usa CommonJS. A incompatibilidade de sistemas de módulos impediu o require direto.

Risco concreto: quando a lógica muda em commands/, ela precisa ser atualizada manualmente também em mcp/src/services.ts. Sem um teste de paridade, as duas implementações podem divergir silenciosamente.

Mitigação: criar um teste de integração que executa o mesmo input nas duas implementações e compara os outputs.

2. Complexidade de ambiente aumentou

Itemv1.0.0v1.0.1+Versão Node.js>= 16>= 18 (MCP exige)Dependências0 externas8 pacotes (@mcp/sdk, Zod, Express, JWT…)Sistema de módulosCommonJSESM (type: "module")Processo em execuçãoNenhumServidor MCP rodando em backgroundConfiguração para usoNenhumaEditar mcp-settings.json do Bob

Para um desenvolvedor iniciante, essa diferença pode ser a barreira entre "funcionou na primeira tentativa" e "passei uma hora depurando caminhos absolutos".

3. Overhead de contexto no agente

Cada ferramenta MCP registrada ocupa tokens no overhead fixo do agente a cada turno (~300–500 tokens por tool, conforme documentação do IBM Bob). Com 5 ferramentas registradas, isso adiciona ~1.950 tokens ao custo de toda mensagem enviada ao Bob — mesmo que a mensagem não tenha nada a ver com o DIO Explorer.

Prática recomendada: desabilitar ferramentas MCP não utilizadas nas configurações do Bob para reduzir o overhead.

4. Depuração é menos intuitiva

Na v1.0.0, um erro produzia uma string de erro diretamente no terminal. Na v1.0.1, o fluxo de erro passa por: agente → protocolo MCP → handler → McpError → protocolo MCP → agente → usuário. Rastrear onde algo falhou exige conhecer esse pipeline.

5. O modo gerar é não-determinístico

A ferramenta gerar_cards no modo gerar retorna um prompt para o Bob, que então usa seu modelo de linguagem para criar os cards. Isso significa que duas chamadas idênticas podem produzir resultados diferentes. Para um sistema educacional, a qualidade e correção técnica dos cards gerados dependem do modelo e do contexto no momento da geração.

Cuidado: cards gerados por IA devem ser revisados antes de serem adicionados à base de dados permanente. Nunca automatize a ingestão sem revisão humana.

Quando Usar Cada Abordagem

A resposta honesta: as duas arquiteturas coexistem no projeto e têm casos de uso distintos.

CenárioUse comandos slashUse MCPScript standalone, sem agente✅❌Teste unitário da lógica de negócio✅❌Agente de IA conversacional❌✅Integração com VS Code (Bob)❌✅Ambiente com Node.js 16✅❌Múltiplos clientes simultâneos❌✅Geração de conteúdo dinâmico via IA❌✅Onboarding de time sem configuração✅❌O Que Aprendemos: Lições para Seu Próximo Projeto

1. Projete para o consumidor, não para a implementação

A transição para MCP não foi motivada por um problema no código — foi motivada por uma mudança no perfil do consumidor. Antes de decidir uma arquitetura, pergunte: quem vai chamar isso? Um humano via CLI? Um agente de IA? Uma API REST? A resposta muda tudo.

2. Mantenha a lógica de negócio isolada

O maior custo desta migração foi a duplicação de lógica. Se a lógica de negócio tivesse sido isolada desde o início em um pacote separado (ex: @dio/explorer-core), tanto os comandos slash quanto o servidor MCP poderiam importá-lo sem duplicação.

3. Schemas são documentação e contrato ao mesmo tempo

Os schemas Zod em mcp/src/tools.ts servem três propósitos simultâneos: validação em runtime, tipagem TypeScript em tempo de compilação, e documentação legível pelo agente de IA. Investir em schemas bem descritos tem retorno imediato.

4. Testes são o seguro da transição

Os 101 testes escritos na v1.0.0 foram o que garantiu que a lógica de negócio estava correta antes da migração. Migrar código sem testes é como reformar a fundação de um prédio sem saber quais paredes são estruturais.

5. MCP é uma camada de protocolo, não um substituto

O servidor MCP não substituiu os comandos slash — adicionou uma nova interface sobre a mesma lógica. Os comandos continuam funcionando independentemente. MCP é uma camada de protocolo, assim como HTTP é uma camada de protocolo sobre TCP. Ele não muda o que você faz — muda como você expõe o que faz.

Linha do Tempo Final

v1.0.0             v1.0.1               v1.1.0            v1.2.0
 │                  │                    │                  │
CLI puro      MCP Server              /cards             gerar_cards
4 comandos    4 tools via stdio       Flash Cards        no MCP
101 testes    Bob + Claude            24 cards           modo gerar
100% ✅       Zod schemas             < 1ms/call         prompt IA
0 deps ext.   8 novas deps            0 deps novas       100% cobertura

Conclusão

A transição do DIO Explorer de um sistema de comandos slash para um servidor MCP é um microcosmo de uma decisão que muitos desenvolvedores enfrentarão nos próximos anos: como tornar suas ferramentas acessíveis para agentes de IA sem abrir mão do controle, da testabilidade e da clareza arquitetural?

O MCP não é a resposta para todos os projetos. Mas para projetos que precisam ser consumidos por agentes de IA de forma confiável, com validação de entrada, descoberta automática de capacidades e separação de responsabilidades — ele é, hoje, o padrão mais maduro disponível.

O DIO Explorer demonstra que é possível fazer essa transição de forma incremental, mantendo a compatibilidade, preservando os testes existentes e adicionando capacidades genuinamente novas — como a geração de flash cards via IA — que simplesmente não seriam possíveis na arquitetura original.

💬 "A melhor arquitetura não é a mais inteligente — é a que resolve o problema certo para o consumidor certo."

Código-fonte do projeto: DIO Explorer no GitHub

Documentação MCP: modelcontextprotocol.io

Formação IBM com Bob: dio.me

Artigo produzido como parte do Projeto Final da Formação IBM com Bob — Digital Innovation One.

Made with IBM Bob ❤️

Ps. Gastei todos os meus BobCoins !