Antes de começarmos a construir servidores MCP, vamos garantir que você tenha tudo o que precisa. Não se preocupe - a configuração é simples!

Requisitos do Sistema

Você precisará de:

• Node.js 18.x ou superior (para recursos modernos de JavaScript)
• npm ou yarn (gerenciador de pacotes)
• Um editor de código (VS Code recomendado)
• Acesso ao terminal (para executar comandos)

Pré-requisitos de Conhecimento

Este módulo assume que você:

• Tem conhecimento básico de JavaScript/TypeScript
• Está confortável usando a linha de comando
• Entende comandos básicos do npm

Se você é novo no TypeScript, não se preocupe! Explicaremos os conceitos específicos do TypeScript conforme avançamos.

Vamos configurar seu ambiente de desenvolvimento passo a passo.

Passo 1: Verificar Instalação do Node.js

Primeiro, verifique se você tem o Node.js instalado:

<CodeExample title="Verificando a Versão do Node.js" language="bash" code={`# Verificar versão do Node.js (deve ser 18.x ou superior) node --version

Verificar versão do npm

npm --version

Se você precisar instalar o Node.js, visite:

https://nodejs.org/`}

/>

Se você precisar instalar ou atualizar o Node.js:

• Windows/Mac: Baixe de nodejs.org
• Linux: Use seu gerenciador de pacotes ou NodeSource
• Alternativa: Use nvm para gerenciamento de versões

Passo 2: Instalar Ferramentas Globais

Embora não sejam obrigatórias, essas ferramentas melhorarão sua experiência de desenvolvimento:

<CodeExample title="Ferramentas Globais Opcionais" language="bash" code={`# Compilador TypeScript (opcional - usaremos tsx para desenvolvimento) npm install -g typescript

MCP Inspector para testes

npm install -g @modelcontextprotocol/inspector`} />

Agora vamos criar seu primeiro projeto de servidor MCP do zero.

Passo 1: Inicializar o Projeto

<CodeExample title="Inicializar Projeto" language="bash" code={`# Criar diretório do projeto mkdir meu-primeiro-servidor-mcp cd meu-primeiro-servidor-mcp

Inicializar projeto npm

npm init -y

Instalar TypeScript e SDK MCP

npm install --save-dev typescript @types/node tsx npm install @modelcontextprotocol/sdk`} />

Passo 2: Configurar TypeScript

Crie um arquivo tsconfig.json para configurar o TypeScript para desenvolvimento MCP:

<CodeExample title="Configuração do TypeScript" language="json" fileName="tsconfig.json" code={{ "compilerOptions": { "target": "ES2022", "module": "Node16", "moduleResolution": "Node16", "lib": ["ES2022"], "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "resolveJsonModule": true, "declaration": true, "declarationMap": true, "sourceMap": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] }} highlightLines={[3, 4, 5, 9]} />

Passo 3: Atualizar package.json

Adicione configurações importantes ao seu package.json:

<CodeExample title="Configuração do Package" language="json" fileName="package.json" code={{ "name": "meu-primeiro-servidor-mcp", "version": "1.0.0", "type": "module", "main": "dist/index.js", "scripts": { "dev": "tsx watch src/index.ts", "build": "tsc", "start": "node dist/index.js" }, // ... dependências }} highlightLines={[4, 6, 7, 8, 9]} />

Passo 4: Criar Estrutura do Projeto

Configure uma estrutura de projeto limpa:

Seu projeto agora deve parecer com isto:

meu-primeiro-servidor-mcp/
├── node_modules/
├── src/
│   └── index.ts
├── package.json
├── package-lock.json
└── tsconfig.json

Depois de construir seu servidor, vamos testá-lo!

Usando Scripts npm

Adicione estes scripts úteis ao seu package.json:

<CodeExample title="Scripts do Package.json" language="json" fileName="package.json" code={{ "name": "meu-primeiro-servidor-mcp", "version": "1.0.0", "type": "module", "scripts": { "dev": "tsx watch src/index.ts", "build": "tsc", "start": "node dist/index.js", "test": "npx @modelcontextprotocol/inspector" }, // ... outros campos }} highlightLines={[5, 6, 7, 8, 9]} />

Testando com MCP Inspector

O MCP Inspector é uma ferramenta poderosa para testar seu servidor:

1. Inicie seu servidor em um terminal:

2. Execute o inspector em outro terminal:

3. Conecte-se ao seu servidor no inspector:

   • Selecione transporte "stdio"
   • Digite o comando: npm run dev
   • Clique em "Connect"

Problemas Comuns e Soluções

Problema: Erros "Cannot find module" Solução: Certifique-se de que todas as importações terminam com extensão .js (mesmo para arquivos TypeScript)

Problema: "Module not found" para SDK MCP Solução: Verifique se você está usando Node.js 18+ e tem "type": "module" no package.json

Problema: Servidor não responde no inspector Solução: Certifique-se de estar usando transporte stdio e que o servidor está rodando

Conforme seu servidor MCP cresce, uma boa estrutura se torna essencial. Aqui está uma abordagem recomendada:

<CodeExample title="Estrutura de Projeto Recomendada" language="text" code={meu-servidor-mcp/ ├── src/ │ ├── index.ts # Ponto de entrada principal do servidor │ ├── handlers/ # Manipuladores de requisição │ │ ├── resources.ts # Manipuladores de recursos │ │ └── tools.ts # Manipuladores de ferramentas │ ├── providers/ # Lógica de negócios │ │ ├── database.ts # Conexões de banco de dados │ │ └── files.ts # Operações do sistema de arquivos │ └── types/ # Definições de tipos TypeScript ├── dist/ # Saída compilada ├── tests/ # Arquivos de teste ├── .gitignore ├── package.json ├── tsconfig.json └── README.md} />

Dicas de Organização

1. Separar Responsabilidades: Mantenha manipuladores, provedores e tipos em diretórios separados
2. Responsabilidade Única: Cada arquivo deve ter um propósito claro
3. Nomenclatura Consistente: Use nomes descritivos que indiquem funcionalidade
4. Segurança de Tipos: Defina interfaces para todas as estruturas de dados

<CodeExample title="Exemplo de Organização de Manipulador" language="typescript" fileName="src/handlers/resources.ts" code={`import { Server } from '@modelcontextprotocol/sdk/server/index.js';

export function registerResourceHandlers(server: Server) { // Registrar todos os manipuladores relacionados a recursos server.setRequestHandler('resources/list', async () => { return { resources: [ ...await fileProvider.listResources(), ...await databaseProvider.listResources() ] }; });

server.setRequestHandler('resources/read', async (request) => { // Delegar ao provedor apropriado baseado no esquema URI const uri = request.params.uri;

if (uri.startsWith('file://')) {
  return fileProvider.readResource(uri);
} else if (uri.startsWith('db://')) {
  return databaseProvider.readResource(uri);
}

throw new Error('Tipo de recurso desconhecido');

}); }`} />

Parabéns! Você conseguiu:

✅ Configurar um ambiente de desenvolvimento TypeScript ✅ Configurar seu projeto para desenvolvimento MCP ✅ Criar seu primeiro servidor MCP ✅ Testá-lo com o MCP Inspector ✅ Aprender melhores práticas de organização de projeto

Seu ambiente de desenvolvimento está pronto! No próximo módulo, você aprenderá a:

• Implementar provedores de recursos poderosos
• Lidar com diferentes tipos de dados
• Criar listagens dinâmicas de recursos
• Construir integrações do mundo real

Importações Principais

Servidor Mínimo