MCP Server Starter

Um modelo inicial em TypeScript para construir servidores Model Context Protocol (MCP).

Documentação

O que é MCP?

O Model Context Protocol (MCP) é um framework especializado projetado para simplificar o processo de permitir que agentes de IA interajam com uma ampla variedade de ferramentas. Este template inicial ajuda você a construir rapidamente um servidor Model Context Protocol (MCP) usando TypeScript. Ele fornece uma base robusta que você pode facilmente estender para criar ferramentas MCP avançadas e integrá-las perfeitamente com diversas plataformas de IA.

Componentes Principais

Servidores MCP: Esses servidores atuam como pontes, expondo APIs, bancos de dados e bibliotecas de código para hosts de IA externos. Ao implementar um servidor MCP em TypeScript, os desenvolvedores podem compartilhar fontes de dados ou lógica computacional de forma padronizada usando JSON-RPC 2.0.
Clientes MCP: São o lado voltado ao consumidor do MCP, comunicando-se com servidores para consultar dados ou executar ações. Os clientes MCP usam SDKs TypeScript, garantindo interações type-safe e uma abordagem uniforme para o uso de ferramentas.
Hosts MCP: Sistemas como Claude, Cursor, Windsurf, Cline e outras plataformas baseadas em TypeScript coordenam solicitações entre servidores e clientes, garantindo um fluxo de dados contínuo. Um único servidor MCP pode assim ser acessado por múltiplos hosts de IA sem integrações personalizadas.

Implementação em TypeScript

O SDK TypeScript do MCP fornece classes principais para construir servidores:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "mcp-server-starter",
  version: "1.0.0",
  capabilities: {
    tools: {},      // Enable tools capability
    resources: {},  // Enable resource access
    prompts: {},    // Enable prompt handling
    streaming: true // Enable streaming responses
  }
});

// Connect transport
const transport = new StdioServerTransport();
await server.connect(transport);

Ao usar MCP, os desenvolvedores não precisam mais de código personalizado complexo para integrar novas ferramentas ou serviços. Em vez disso, eles constroem um servidor MCP e o disponibilizam para hosts compatíveis.

Pré-requisitos

Node.js (v18 ou posterior): Uma versão moderna do Node.js que aproveita os recursos mais recentes de JavaScript e melhorias de desempenho.
npm (v7 ou posterior): Garante compatibilidade para instalar e gerenciar pacotes.
VS Code com a extensão Dev Containers: Permite que você configure rapidamente um ambiente de desenvolvimento reproduzível, tornando a colaboração mais fácil e eficiente.

Estrutura do Projeto

Um layout de arquivos típico para o template do servidor MCP pode ser assim:

mcp-server/
├── .devcontainer/        # Dev container configuration
│   └── devcontainer.json
├── src/
│   ├── index.ts         # MCP Server main entry point
│   └── examples/        # Example tool implementations
│       ├── calculator.ts # Calculator tool example
│       └── rest-api.ts  # REST API tool example
├── package.json         # Project configuration
└── tsconfig.json        # TypeScript configuration

O diretório .devcontainer simplifica o desenvolvimento baseado em contêineres, enquanto a pasta src/ abriga a lógica principal do servidor e exemplos de ferramentas personalizadas. Essa estrutura mantém seu projeto organizado e fácil de navegar.

Início Rápido

Instalação via Smithery

Para instalar o MCP Server Starter para qualquer cliente compatível:

# For Claude
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client claude

# For Cursor
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client cursor

# For Windsurf
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client windsurf

# For Cline
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client cline

# For TypeScript
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client typescript

Clone este template: Obtenha os arquivos do repositório da sua fonte preferida.
Abra no VS Code com Dev Containers: Se você tiver a extensão Dev Containers instalada, será solicitado a abrir este projeto dentro de um contêiner.
Instale as dependências:
```
npm install
```
Este comando busca e instala todos os pacotes necessários para o servidor MCP.
Compile o projeto:
```
npm run build
```
Isso compila seu código TypeScript em JavaScript, preparando-o para execução.

Scripts de Desenvolvimento

Compilar o projeto:
```
npm run build
```
Compila seu código-fonte TypeScript e define permissões de arquivo para o ponto de entrada principal.
Modo de observação:
```
npm run watch
```
Recompila automaticamente os arquivos TypeScript sempre que alterações são feitas, ideal para desenvolvimento ativo.
Executar com inspetor:
```
npm run inspector
```
Inicia o servidor junto com uma ferramenta de depuração, permitindo rastrear problemas, definir pontos de interrupção e inspecionar variáveis em tempo real.

Formato de Resposta das Ferramentas

As ferramentas MCP devem retornar respostas em um formato específico para garantir comunicação adequada com os hosts de IA. Aqui está a estrutura:

interface ToolResponse {
  content: ContentItem[];
  isError?: boolean;
  metadata?: Record<string, unknown>;
}

interface ContentItem {
  type: string;
  text?: string;
  mimeType?: string;
  data?: unknown;
}

Os tipos de conteúdo suportados incluem:

text: Conteúdo de texto simples
code: Trechos de código com especificação opcional de linguagem
image: Imagens codificadas em Base64 com tipo MIME
file: Conteúdo de arquivo com tipo MIME
error: Mensagens de erro (quando isError for verdadeiro)

Exemplo de resposta:

return {
  content: [
    {
      type: "text",
      text: "Operation completed successfully"
    },
    {
      type: "code",
      text: "console.log('Hello, World!')",
      mimeType: "application/javascript"
    }
  ]
};

Boas Práticas de Segurança

Ao desenvolver ferramentas MCP, siga estas diretrizes de segurança:

Validação de Entrada:
- Sempre valide os parâmetros de entrada usando esquemas Zod
  - Implemente verificação de tipos estrita
  - Sanitize as entradas do usuário antes do processamento
  - Use a opção strict() nos esquemas para evitar propriedades extras
Tratamento de Erros:
- Nunca exponha detalhes internos de erros aos clientes
  - Implemente limites de erro adequados
  - Registre erros de forma segura
  - Retorne mensagens de erro amigáveis ao usuário
Gerenciamento de Recursos:
- Implemente procedimentos de limpeza adequados
  - Trate sinais de término de processo
  - Feche conexões e libere recursos
  - Implemente timeouts para operações de longa duração
Segurança de API:
- Use protocolos de transporte seguros
  - Implemente limitação de taxa
  - Armazene dados sensíveis de forma segura
  - Use variáveis de ambiente para configuração

Exemplo de implementação segura de ferramenta:

const SecureSchema = z.object({
  input: z.string()
    .min(1)
    .max(1000)
    .transform(str => str.trim())
    .pipe(z.string().regex(/^[a-zA-Z0-9\s]+$/))
});

server.tool(
  "secure_tool",
  SecureSchema.shape,
  async (params) => {
    try {
      // Implement rate limiting
      await rateLimiter.checkLimit();

      // Process validated input
      const result = await processSecurely(params.input);

      return {
        content: [{
          type: "text",
          text: result
        }]
      };
    } catch (error) {
      // Log error internally
      logger.error(error);

      // Return safe error message
      return {
        content: [{
          type: "text",
          text: "An error occurred processing your request"
        }],
        isError: true
      };
    }
  }
);

Recursos Avançados

Respostas em Streaming

O MCP suporta respostas em streaming para operações de longa duração:

server.tool(
  "stream_data",
  StreamSchema.shape,
  async function* (params) {
    for (const chunk of dataStream) {
      yield {
        content: [{
          type: "text",
          text: chunk
        }]
      };
    }
  }
);

Tipos de Conteúdo Personalizados

Você pode definir tipos de conteúdo personalizados para dados especializados:

interface CustomContent extends ContentItem {
  type: "custom";
  data: {
    format: string;
    value: unknown;
  };
}

Execução Assíncrona de Ferramentas

Implemente o tratamento assíncrono adequado:

server.tool(
  "async_operation",
  AsyncSchema.shape,
  async (params) => {
    const operation = await startAsyncOperation();

    while (!operation.isComplete()) {
      await operation.wait();
    }

    return {
      content: [{
        type: "text",
        text: await operation.getResult()
      }]
    };
  }
);

Testes e Depuração

Testes Unitários

Use Jest para testar suas ferramentas:

describe('Calculator Tool', () => {
  let server: McpServer;

  beforeEach(() => {
    server = new McpServer({
      name: "test-server",
      version: "1.0.0"
    });
    registerCalculatorTool(server);
  });

  test('adds numbers correctly', async () => {
    const result = await server.executeTool('calculate', {
      a: 5,
      b: 3,
      operation: 'add'
    });

    expect(result.content[0].text).toBe('8');
  });
});

Ferramentas de Depuração

Inspetor MCP:
```
npm run inspector
```
Fornece inspeção em tempo real de:
- Registro de ferramentas
  - Fluxo de solicitação/resposta
  - Tratamento de erros
  - Métricas de desempenho

Registro de Logs:

function logMessage(level: 'info' | 'warn' | 'error', message: string) {
  console.error(\`[${level.toUpperCase()}] ${message}\`);
}

Rastreamento de Erros:

process.on('uncaughtException', (error: Error) => {
  logMessage('error', \`Uncaught error: ${error.message}\`);
  // Implement error reporting
});

Configuração de Transporte

O MCP suporta múltiplos protocolos de transporte:

Transporte stdio

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

const transport = new StdioServerTransport();
await server.connect(transport);

Transporte WebSocket

import { WebSocketServerTransport } from "@modelcontextprotocol/sdk/server/websocket.js";

const transport = new WebSocketServerTransport({
  port: 3000
});
await server.connect(transport);

Transporte Personalizado

import { Transport } from "@modelcontextprotocol/sdk/server/transport.js";

class CustomTransport implements Transport {
  // Implement transport methods
}

Capacidades do Servidor

Configure as capacidades do servidor:

const server = new McpServer({
  name: "mcp-server",
  version: "1.0.0",
  capabilities: {
    tools: {}, // Enable tools capability
    streaming: true, // Enable streaming support
    customContent: ["myFormat"], // Define custom content types
    metadata: true // Enable metadata support
  }
});

Integração com Hosts MCP

Suporte a Múltiplos Clientes

Este template de servidor MCP suporta várias plataformas de IA prontas para uso:

Claude Desktop:
- Fornece um ambiente baseado em chat
  - Suporta todas as capacidades do MCP
  - Ideal para interações de IA conversacional
Cursor:
- Ambiente de desenvolvimento com IA
  - Suporte completo à integração de ferramentas
  - Perfeito para assistência de codificação
Windsurf:
- Plataforma moderna de desenvolvimento com IA
  - Suporte completo ao protocolo MCP
  - Integração simplificada de fluxo de trabalho
Cline:
- Interface de IA por linha de comando
  - Interações focadas em ferramentas
  - Uso eficiente baseado em terminal
TypeScript:
- Suporte nativo a TypeScript
  - Desenvolvimento de ferramentas type-safe
  - Integração perfeita com SDK

Cada cliente pode ser configurado usando o comando apropriado da CLI Smithery:

npx -y @smithery/cli run @TheSethRose/mcp-server-starter --client [client-name]

Substitua [client-name] por um dos seguintes: claude, cursor, windsurf, cline ou typescript.

Integração com Smithery

Uma maneira conveniente de executar este servidor MCP é através do Smithery, uma plataforma centralizada para descobrir e publicar servidores MCP. O Smithery simplifica a implantação e garante que seu servidor possa ser integrado a vários fluxos de trabalho de IA.

Execução Rápida

Você pode executar imediatamente este servidor via CLI do Smithery:

npx -y @smithery/cli@latest run mcp-server-template --config "{}"

O Smithery busca, instala e executa automaticamente o servidor a partir de sua versão mais recente, exigindo configuração mínima de sua parte.

Publicando Sua Própria Versão

Se você desenvolveu novas ferramentas ou fez modificações locais e deseja compartilhá-las, considere publicar seu servidor personalizado:

Crie uma conta no Smithery.
Siga as instruções de implantação deles para empacotar e publicar seu servidor MCP.
Outros usuários podem então executar seu servidor através do Smithery referenciando seu nome de pacote exclusivo.

O Smithery oferece:

Um registro centralizado para descobrir e compartilhar servidores MCP.
Implantação simplificada, eliminando configurações repetitivas.
Uma abordagem orientada pela comunidade, onde desenvolvedores contribuem com ferramentas diversas.
Integração fácil com hosts populares de IA.

Para orientação adicional:

Integração com Cursor

O Cursor é outro ambiente de desenvolvimento de IA que suporta MCP. Para incorporar seu servidor ao Cursor:

Compile seu servidor:
```
npm run build
```
Garanta que um index.js executável seja gerado no diretório build.
No Cursor, vá para Settings > Features > MCP: Adicione um novo servidor MCP.
Registre seu servidor:
- Selecione stdio como o tipo de transporte.
  - Forneça um Name descritivo.
  - Defina o comando, por exemplo: node /path/to/your/mcp-server/build/index.js.
Salve sua configuração.

O Cursor então detecta e lista suas ferramentas. Durante sessões de codificação assistidas por IA ou interações baseadas em prompts, ele chamará suas ferramentas MCP sempre que relevante. Você também pode instruir a IA a usar uma ferramenta específica pelo nome.

Integração com Claude Desktop

O Claude Desktop fornece um ambiente baseado em chat onde você pode aproveitar as ferramentas MCP. Para incluir seu servidor:

Compile seu servidor:
```
npm run build
```
Confirme que nenhum erro ocorre e que o script principal é gerado em build.

Modifique claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-server/build/index.js"
      ]
    }
  }
}

Forneça o caminho para seu arquivo principal compilado junto com quaisquer argumentos adicionais.

Reinicie o Claude Desktop para carregar a nova configuração.

Ao interagir com o Claude Desktop, ele agora pode invocar as ferramentas MCP que você registrou. Se a solicitação de um usuário estiver alinhada com a funcionalidade de qualquer uma de suas ferramentas, o Claude solicitará o uso dessa ferramenta.

Boas Práticas de Desenvolvimento

Use TypeScript para melhor verificação de tipos, organização de código mais clara e manutenção mais fácil ao longo do tempo.
Adote padrões consistentes para implementar ferramentas:
- Mantenha cada ferramenta em seu próprio arquivo
  - Use esquemas descritivos com documentação adequada
  - Implemente tratamento abrangente de erros
  - Retorne conteúdo formatado corretamente
Inclua documentação completa:
- Adicione comentários JSDoc para explicar a funcionalidade
  - Documente parâmetros e tipos de retorno
  - Inclua exemplos quando útil
Aproveite o inspetor para depuração:
```
npm run inspector
```
Isso ajuda você a:
- Testar a funcionalidade das ferramentas
  - Depurar o fluxo de solicitação/resposta
  - Verificar a validação de esquemas
  - Verificar o tratamento de erros
Teste de forma abrangente antes da implantação:
- Verifique a validação de entrada
  - Teste cenários de erro
  - Verifique a formatação das respostas
  - Garanta a integração adequada com os hosts
Siga as boas práticas do MCP:
- Use tipos de conteúdo adequados
  - Implemente tratamento de erros adequado
  - Valide todas as entradas e saídas
  - Trate solicitações de rede com segurança
  - Formate as respostas de forma consistente

Saiba Mais

Para mais informações sobre o ecossistema MCP, consulte:

Documentação do Model Context Protocol: Cobertura detalhada da arquitetura do MCP, princípios de design e exemplos de uso mais avançados.
Smithery - Registro de Servidores MCP: Diretrizes para publicar suas ferramentas no Smithery e boas práticas para o registro delas.
Documentação do SDK TypeScript do MCP: Documentação abrangente do SDK TypeScript.
Diretrizes de Segurança do MCP: Boas práticas e recomendações detalhadas de segurança.

Conclusão

Seguindo este template e as boas práticas, você pode construir rapidamente um servidor MCP robusto que abre suas ferramentas para uma ampla gama de hosts de IA. Essa abordagem expandida garante manutenção mais fácil, melhor segurança de tipos e uma experiência de usuário fluida ao aproveitar as capacidades dos sistemas modernos de IA.

Créditos

Template criado por Seth Rose:

Website: https://www.sethrose.dev
𝕏 (Twitter): https://x.com/TheSethRose
🦋 (Bluesky): https://bsky.app/profile/sethrose.dev

Boas Práticas

Segurança de Tipos:
- Aproveite o sistema de tipos do TypeScript para definições robustas de ferramentas
  - Use esquemas Zod para validação em tempo de execução
  - Defina interfaces claras para parâmetros e respostas das ferramentas
Seleção de Transporte:
- Use StdioServerTransport para comunicação com processos locais
  - Implemente WebSocketServerTransport para ferramentas baseadas em rede
  - Considere transportes personalizados para casos de uso específicos
Gerenciamento de Capacidades:
- Defina claramente as capacidades do servidor durante a inicialização
  - Implemente negociação adequada de capacidades
  - Trate erros específicos de capacidade de forma graciosa
Considerações de Segurança:
- Implemente fluxos de consentimento do usuário para operações sensíveis
  - Valide todas as entradas usando tipos TypeScript e esquemas Zod
  - Trate erros com segurança, sem expor detalhes internos