Glaucia Lemos

Posted on Oct 21

Do Zero ao MCP: Criando um Servidor Model Context Protocol com TypeScript e a API do Star Wars

#tutorial #mcp #ai #typescript

Se você ainda não conhece o Model Context Protocol (MCP), está perdendo uma das tecnologias mais promissoras para integração de IA com dados e ferramentas externas. E se você é fã de Star Wars, essa live vai ser ainda mais especial! 🌟

Recentemente, fiz uma live completa onde expliquei desde os fundamentos teóricos até a implementação prática de um servidor MCP que conecta o Claude Desktop com a API pública do Star Wars (SWAPI). Neste artigo, vou resumir os principais pontos abordados e te dar um roteiro completo para você começar sua jornada com MCP.

🎥 Assista à Live Completa

Antes de mergulharmos no conteúdo, convido você a assistir à live completa no YouTube, onde demonstro passo a passo todo o processo de criação:

▶️ Assista à Live: Do Zero ao MCP com TypeScript

💡 A live está disponível com chapters para facilitar sua navegação entre os tópicos!

📚 O que é o Model Context Protocol (MCP)?

O MCP é um protocolo revolucionário que permite que modelos de linguagem (LLMs) acessem dados e ferramentas externas de forma segura e padronizada. Pense nele como uma ponte entre o modelo de IA e o mundo real.

Por que o MCP é importante?

Em vez de dar acesso direto à internet ou aos seus dados, o MCP atua como um tradutor controlado:

Usuário faz uma pergunta no MCP Client (ex: Claude Desktop)
MCP Client interpreta e envia ao MCP Server
MCP Server executa a ação (chamada HTTP à API)
API processa e retorna dados
MCP Server formata a resposta
Modelo de IA recebe e apresenta ao usuário

Tudo isso acontece via stdio (entrada e saída padrão), sem o modelo acessar diretamente a internet.

🏗️ Arquitetura do Projeto

O projeto que criamos na live é intencionalmente simples para facilitar o aprendizado:

swapi-mcp-server-app/
├── src/
│   ├── index.ts          # Servidor MCP + Lógica das Tools
│   └── types.ts          # Interfaces TypeScript (People, Planets, Films)
├── build/                # Arquivos JS compilados
├── package.json          # Dependências e scripts
├── tsconfig.json         # Configuração TypeScript
└── claude_desktop_config.json  # Configuração do MCP Client

Tecnologias Utilizadas

Node.js - Runtime JavaScript
TypeScript - Tipagem estática e segurança
MCP SDK (@modelcontextprotocol/sdk) - SDK oficial do MCP
Axios - Cliente HTTP para chamadas à API
Zod - Validação de esquemas e tipos
SWAPI - Star Wars API (API pública)
Claude Desktop - Para ser usado como MCP Client

🔧 Funcionalidades Implementadas

Tools (Ações)

Criamos 4 tools que o modelo pode executar:

search_characters - Busca personagens pelo nome
- Exemplo: "Busque informações sobre Luke Skywalker"
search_planets - Busca planetas pelo nome
- Exemplo: "Encontre dados sobre Tatooine"
search_films - Busca filmes pelo título
- Exemplo: "Procure pelo filme A New Hope"
get_character_by_id - Obtém personagem pelo ID
- Exemplo: "Busque o personagem com ID 4"

Resources (Dados)

Implementamos 1 resource para acesso direto a dados:

all_films - Lista todos os filmes ordenados por episódio

💻 Implementação Passo a Passo

1. Configuração Inicial

Primeiro, criamos o projeto e instalamos as dependências:

npm init -y
npm install @modelcontextprotocol/sdk axios zod
npm install --save-dev @types/node typescript

2. Configuração do `package.json`

Configuramos scripts essenciais e o bin para tornar o servidor executável:

{
  "name": "swapi-mcp-server-app",
  "type": "module",
  "bin": {
    "swapi-mcp-server": "./build/index.js"
  },
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch",
    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
  }
}

💡 Dica: O script inspector é ESSENCIAL para testar seu MCP antes de integrá-lo ao Claude Desktop!

3. Definindo os Tipos (`types.ts`)

Criamos interfaces TypeScript baseadas na documentação da SWAPI:

export interface People {
  name: string;
  height: string;
  mass: string;
  hair_color: string;
  eye_color: string;
  birth_year: string;
  gender: string;
  homeworld: string;
  films: string[];
  // ... outras propriedades
}

export interface SearchResponse<T> {
  count: number;
  next: string | null;
  previous: string | null;
  results: T[];
}

O SearchResponse<T> é genérico e pode ser reutilizado para diferentes tipos de dados.

4. Criando o Servidor MCP (`index.ts`)

4.1 Instanciando o Servidor

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

class SwapiMcpServer {
  private server: McpServer;
  private axiosInstance;

  constructor() {
    this.server = new McpServer({
      name: "swapi-mcp-server",
      version: "1.0.0",
    });

    this.axiosInstance = axios.create({
      baseURL: "https://swapi.dev/api",
      timeout: 10000,
    });

    this.setupTools();
    this.setupResources();
  }
}

4.2 Registrando uma Tool

private setupTools(): void {
  this.server.registerTool(
    "search_characters",
    {
      title: "Buscar Personagens",
      description: "Busca personagens do Star Wars por nome",
      inputSchema: {
        search: z.string().describe("Nome do personagem para buscar"),
      },
    },
    async ({ search }) => {
      try {
        const response = await this.axiosInstance.get<SearchResponse<People>>(
          "/people/",
          { params: { search } }
        );

        if (response.data.results.length === 0) {
          return {
            content: [{
              type: "text" as const,
              text: `Nenhum personagem encontrado com o nome "${search}".`,
            }],
          };
        }

        const charactersInfo = response.data.results
          .map((char) => `Nome: ${char.name}\nAltura: ${char.height}cm\n...`)
          .join("\n---\n\n");

        return {
          content: [{
            type: "text" as const,
            text: `Encontrados ${response.data.results.length} personagem(ns):\n\n${charactersInfo}`,
          }],
        };
      } catch (error) {
        return this.handleError(error, "buscar personagens");
      }
    }
  );
}

4.3 Conectando via Stdio

async run(): Promise<void> {
  const transport = new StdioServerTransport();
  await this.server.connect(transport);
  console.error("SWAPI MCP Server rodando em stdio");
}

const server = new SwapiMcpServer();
server.run().catch((error) => {
  console.error("Erro fatal ao iniciar o servidor:", error);
  process.exit(1);
});

🧪 Testando com o MCP Inspector

Antes de integrar com o Claude Desktop, SEMPRE teste com o Inspector:

npm run build
npm run inspector

O Inspector abre uma interface web onde você pode:

✅ Listar todas as tools disponíveis
✅ Testar cada tool individualmente
✅ Visualizar e testar os resources criados
✅ Debugar problemas de conexão
✅ Ver logs em tempo real

Exemplo de teste:

Clique em "Connect"
Vá em "Tools" → "search_characters"
Digite "Darth Vader" no campo search
Clique em "Run Tool"
Veja a resposta formatada!

🔌 Conectando ao Claude Desktop

1. Localize o arquivo de configuração

No Windows:

%APPDATA%\Claude\claude_desktop_config.json

2. Adicione a configuração do MCP Server

{
  "mcpServers": {
    "swapi-mcp-server": {
      "command": "node",
      "args": [
        "C:/Users/SEU_USUARIO/caminho/para/swapi-mcp-server-app/build/index.js"
      ]
    }
  }
}

⚠️ IMPORTANTE: Use o caminho absoluto para o arquivo build/index.js!

3. Reinicie o Claude Desktop

Feche completamente e abra novamente o Claude Desktop.

4. Teste com perguntas naturais

Agora você pode fazer perguntas como:

"Busque informações sobre Luke Skywalker"
"Encontre dados sobre o planeta Tatooine"
"Liste todos os filmes de Star Wars"
"Qual é o personagem com ID 4?"

O Claude vai identificar automaticamente qual tool usar e chamar seu MCP Server! 🎉

🎯 Principais Aprendizados da Live

1. MCP vs Acesso Direto à Internet

O MCP oferece:

✅ Controle granular sobre o que a IA pode acessar
✅ Segurança - sem acesso direto a dados sensíveis
✅ Padronização - mesmo protocolo para diferentes fontes
✅ Validação - Zod garante tipos corretos (TypeScript)

2. Tools vs Resources

Aspecto	Tools	Resources
Propósito	Ações dinâmicas	Dados prontos
Entrada	Requer parâmetros do usuário	Sem entrada
Exemplo	Buscar personagem por nome	Listar todos os filmes
Registro	`server.registerTool()`	`server.registerResource()`

3. Boas Práticas

❌ NÃO FAÇA:

Deixar URLs de APIs expostas no código (use .env)
Esquecer de validar entradas com Zod
Pular o teste com Inspector

✅ FAÇA:

Use variáveis de ambiente para dados sensíveis
Valide todas as entradas
Teste exaustivamente antes de integrar
Documente suas tools claramente

🌟 Possibilidades Infinitas

O que criamos na live é apenas o começo! Imagine aplicar MCP para:

Casos de Uso Empresariais

🏢 API Corporativa - Padronizar PRs no GitHub
📊 Dashboard Analytics - Consultar métricas em tempo real
🗄️ Banco de Dados - Queries naturais em SQL
📁 Documentação Interna - Busca semântica

Próximos Passos

✅ Adicionar mais tipos da SWAPI (vehicles, species, starships)
✅ Implementar cache com Redis
✅ Adicionar autenticação para APIs privadas
✅ Deploy em produção (Azure, AWS, etc.)
✅ Criar testes automatizados

📦 Repositório e Recursos

Todo o código da live está disponível no GitHub:

📂 Repositório: swapi-mcp-server-app

glaucia86 / swapi-mcp-server-app

An application for study purposes to understand more about MCP with TypeScript using Star Wars API

🌟 Star Wars MCP Server

Um servidor MCP (Model Context Protocol) que fornece acesso à Star Wars API (SWAPI) através do Claude Desktop

📖 Sobre o Projeto

Este projeto é um servidor MCP desenvolvido em TypeScript que integra a Star Wars API (SWAPI) com o Claude Desktop. Ele permite que você faça perguntas sobre o universo Star Wars e obtenha informações detalhadas sobre personagens, planetas, filmes e muito mais, diretamente através do Claude.

✨ Funcionalidades

🔧 Tools Disponíveis

search_characters - Busca personagens do Star Wars por nome
search_planets - Busca planetas do Star Wars por nome
search_films - Busca filmes do Star Wars por título
get_character_by_id - Obtém informações detalhadas de um personagem pelo ID

📚 Resources Disponíveis

all_films - Lista todos os filmes da saga Star Wars ordenados por episódio

🚀 Como Executar

Pré-requisitos

Node.js (versão 18 ou superior)
Claude Desktop instalado
npm ou yarn

1. Instalação

# Clone

…

View on GitHub

O que você encontra no repositório:

✅ Código completo e comentado
✅ README detalhado com instruções
✅ Exemplos de perguntas para testar
✅ Troubleshooting de problemas comuns
✅ Estrutura pronta para expandir
✅ E, explicação detalhada da parte teórica dada durante a live

⭐ Não esqueça de dar uma estrela no repositório!

🎓 Recursos Adicionais

Documentação Oficial

Próximas Lives

Já estou planejando uma série Zero to Hero sobre LangChain.js! Serão aproximadamente 23 vídeos cobrindo desde o básico até tópicos avançados incluindo: LangGraph e LangSmith.

📺 Inscreva-se no canal para não perder:

YouTube: @glaucialemos

🤔 Perguntas Frequentes

1. MCP funciona só com Claude Desktop?

Não! Você pode usar MCP com:

Claude Desktop ✅
Visual Studio Code (com extensões) ✅
Cursor ✅
Qualquer cliente que implemente o protocolo MCP

2. Preciso pagar para usar Claude Desktop?

Não! O Claude Desktop é gratuito e você pode usar MCPs localmente sem custo.

3. Como fazer deploy de um MCP Server?

Para produção, você precisará:

Hospedar o servidor (Azure, AWS, etc.)
Configurar variáveis de ambiente
Implementar autenticação
Usar Docker para containerização

(Ainda estou estudando a melhor abordagem - em breve farei uma live sobre isso!)

4. O MCP substitui APIs REST?

Não! O MCP complementa APIs REST, fornecendo uma camada de abstração que permite que modelos de IA interajam com elas de forma padronizada.

💬 Vamos Conversar!

Gostou do conteúdo? Tem dúvidas ou sugestões? Me encontre nas redes:

🐦 Twitter/X: @glaucia_lemos86
💼 LinkedIn: Glaucia Lemos
📺 YouTube: @glaucialemos
🐙 GitHub: @glaucia86

🎬 Call to Action

▶️ Assista à live completa no YouTube
⭐ Dê uma estrela no repositório
💬 Deixe suas dúvidas nos comentários
🔔 Inscreva-se no canal para a série LangChain.js

🌌 Conclusão

O Model Context Protocol está revolucionando a forma como integramos IA com sistemas externos. Com apenas algumas centenas de linhas de código TypeScript, criamos um servidor que permite ao Claude Desktop acessar toda a riqueza de dados do universo Star Wars de forma segura e controlada.

Agora é sua vez! Pegue o código, adapte para sua API favorita e explore as possibilidades infinitas do MCP.

May the Force (and the Code) be with you! ⭐✨

Top comments (1)

Synergy Shock • Oct 21

Tip: api-hub.org/apis/star-wars-api