🤖 Template MCP Server - AI Agents

Este projeto é um template de servidor MCP (Model Context Protocol) que expõe ferramentas de agentes de IA como um servidor MCP. Com ele, você pode facilmente criar e expor ferramentas que podem ser consumidas por clientes compatíveis com MCP (como Claude Desktop, Cursor, etc.).

📋 Índice

• Visão Geral
• O que é MCP?
• Estrutura do Projeto
• Ferramentas Disponíveis
• Configuração
• Como Usar
• Criando Novas Ferramentas
• Scripts Disponíveis
• Tecnologias Utilizadas

🎯 Visão Geral

Este template fornece uma base sólida para construir servidores MCP que podem:

• Expor ferramentas para clientes MCP
• Integrar APIs externas (como Weather API, PokeAPI no exemplo)
• Expandir facilmente com novas funcionalidades
• Comunicar via stdio seguindo o protocolo MCP
• Centralizar ferramentas através de um serviço único

🔌 O que é MCP?

O Model Context Protocol (MCP) é um protocolo desenvolvido pela Anthropic que permite que modelos de IA acessem ferramentas e recursos externos de forma padronizada. Um servidor MCP:

• Comunica via stdio ou HTTP
• Expõe ferramentas (tools) que podem ser chamadas pelo cliente
• Pode expor recursos (resources) e prompts também
• Segue um protocolo JSON-RPC padronizado

📁 Estrutura do Projeto

src/
├── mcp-server.ts              # Servidor MCP principal
└── app/
    └── tools/                 # Ferramentas disponíveis
        ├── tool.service.ts    # Centralizador de ferramentas
        ├── weather/           # Ferramentas de clima
        │   ├── cityForecast.tool.ts
        │   └── cityFutureForecast.tool.ts
        └── pokemon/           # Ferramentas de Pokemon
            └── getPokemon.tool.ts

🔍 Detalhamento

/src/mcp-server.ts

• Configura o servidor MCP
• Utiliza o serviço centralizador de ferramentas
• Gerencia requisições de listagem e execução de ferramentas
• Comunica via stdio

/src/app/tools/tool.service.ts

• Centralizador de ferramentas: Gerencia todas as ferramentas disponíveis
• Fornece métodos para listar e obter instâncias de ferramentas
• Facilita a adição de novas ferramentas

/src/app/tools/[dominio]/

• Cada ferramenta é uma classe com:
  • getTool(): Retorna a definição da ferramenta no formato MCP
  • execute(): Executa a lógica da ferramenta

🛠️ Ferramentas Disponíveis

1. city_forecast

Obtém a previsão do tempo atual para uma cidade específica.

Parâmetros:

• city (string, obrigatório): Nome da cidade

2. city_future_forecast

Obtém a previsão do tempo futura para uma cidade específica.

Parâmetros:

• city (string, obrigatório): Nome da cidade
• days (number, opcional): Número de dias para previsão (1-14)

3. get_pokemon

Obtém informações sobre um Pokemon pelo nome ou ID.

Parâmetros:

• pokemon (string, obrigatório): Nome ou ID do Pokemon

⚙️ Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# Weather API Configuration (opcional, apenas para ferramentas de clima)
WEATHER_API_KEY=your_weather_api_key_here

Nota: A ferramenta get_pokemon não requer chave de API.

Instalação

# Instalar dependências
npm install

# Compilar o projeto
npm run build

# Executar o servidor MCP
npm start

🚀 Como Usar

1. Executar o Servidor MCP

O servidor MCP é executado via stdio e deve ser configurado em um cliente MCP compatível.

# Desenvolvimento (com tsx)
npm run dev

# Produção (compilado)
npm run build
npm start

2. Configurar no Claude Desktop

Adicione a configuração no arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "template-ai-agents": {
      "command": "node",
      "args": ["C:/caminho/para/seu/projeto/dist/mcp-server.js"],
      "env": {
        "WEATHER_API_KEY": "sua_chave_aqui"
      }
    }
  }
}

3. Configurar no Cursor

No Cursor, você pode configurar o servidor MCP através das configurações de MCP.

4. Testando o Servidor

Você pode testar o servidor diretamente via linha de comando:

# O servidor espera mensagens JSON-RPC via stdin
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npm start

🛠️ Criando Novas Ferramentas

Passo 1: Criar a Classe da Ferramenta

Crie um novo arquivo em /src/app/tools/[dominio]/[nome].tool.ts:

import { Tool } from '@modelcontextprotocol/sdk/types.js';

export class MinhaNovaTool {
  getTool(): Tool {
    return {
      name: 'minha_nova_tool',
      description: 'Descrição clara do que a ferramenta faz',
      inputSchema: {
        type: 'object',
        properties: {
          parametro: {
            type: 'string',
            description: 'Descrição do parâmetro',
          },
        },
        required: ['parametro'],
      },
    };
  }

  async execute(args: { parametro: string }): Promise<any> {
    // Sua lógica aqui
    // Pode chamar APIs externas, banco de dados, etc.
    return { resultado: 'dados processados' };
  }
}

Passo 2: Registrar no Centralizador de Ferramentas

Adicione a ferramenta em /src/app/tools/tool.service.ts:

import { MinhaNovaTool } from './dominio/minhaNovaTool.tool.js';

export class Tools {
  private minhaNovaTool: MinhaNovaTool;

  constructor() {
    // ... outras ferramentas
    this.minhaNovaTool = new MinhaNovaTool();
  }

  getTools(): Tool[] {
    return [
      // ... outras ferramentas
      this.minhaNovaTool.getTool(),
    ];
  }

  getToolInstance(name: string): any {
    switch (name) {
      // ... outros cases
      case 'minha_nova_tool':
        return this.minhaNovaTool;
      default:
        return null;
    }
  }
}

Pronto! A ferramenta será automaticamente disponibilizada pelo servidor MCP através do centralizador.

📜 Scripts Disponíveis

# Desenvolvimento
npm run dev          # Executa com tsx (hot-reload)

# Produção
npm run build        # Compila TypeScript para JavaScript
npm start            # Executa versão compilada

# Qualidade de Código
npm run lint         # Executa ESLint
npm run format       # Formata código com Prettier

🔧 Tecnologias Utilizadas

Core

• @modelcontextprotocol/sdk: SDK oficial do MCP para TypeScript
• TypeScript: Superset tipado do JavaScript
• dotenv: Gerenciamento de variáveis de ambiente

APIs Externas (Exemplos)

• Weather API: Para ferramentas de clima
• PokeAPI: Para informações de Pokemon

🎯 Próximos Passos

1. Adicione suas próprias ferramentas seguindo os exemplos
2. Integre com suas APIs internas criando ferramentas específicas
3. Adicione recursos (resources) se necessário
4. Adicione prompts para templates reutilizáveis
5. Implemente autenticação se necessário
6. Adicione logging e monitoramento
7. Configure CI/CD para deploy automatizado

📚 Recursos Adicionais

• Documentação oficial do MCP
• SDK TypeScript do MCP
• Exemplos de servidores MCP

---

Desenvolvido com ❤️ usando Model Context Protocol