Custom MCP Server

Um servidor MCP versátil construído com Next.js, oferecendo uma variedade de ferramentas e utilitários com gerenciamento de estado Redis.

GitHubExperimente este MCPPatrocinado

Documentação

Custom MCP Server 🤖

Um servidor Model Context Protocol (MCP) construído com Next.js, fornecendo ferramentas e utilitários úteis através de transportes HTTP e Server-Sent Events (SSE).

🚀 Recursos

🔧 Ferramentas Disponíveis

  • echo - Ecoa qualquer mensagem de volta (perfeito para testes)
  • get-current-time - Obtém o timestamp atual e a data ISO
  • calculate - Realiza cálculos matemáticos básicos com segurança

🌐 Métodos de Transporte

  • Transporte HTTP (/mcp) - Requisições HTTP sem estado (funciona sem Redis)
  • Transporte SSE (/sse) - Server-Sent Events com Redis para gerenciamento de estado

🔒 Recursos de Segurança

  • Limitação de taxa (100 requisições por minuto)
  • Avaliação segura de expressões matemáticas
  • Sanitização e validação de entrada

🏃‍♂️ Início Rápido

Pré-requisitos

  • Node.js 18+
  • npm ou yarn
  • Docker (opcional, para Redis local)

Configuração

  1. Clone e instale as dependências:

    npm install

  2. Execute a configuração automatizada:

    npm run setup

    Isso irá:

    • Criar a configuração de ambiente
    • Configurar o Redis (Docker) se disponível
    • Iniciar o servidor de desenvolvimento automaticamente

  3. Início manual (alternativa):

    npm run dev

O servidor estará disponível em http://localhost:3000

🧪 Testes

Testes Rápidos

# Test HTTP transport
npm run test:http

# Test SSE transport (requires Redis)
npm run test:sse

# Test with Claude Desktop protocol
npm run test:stdio

# Comprehensive tool testing
npm run test:tools

Testes Manuais

Você pode testar o servidor MCP manualmente usando curl:

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call the echo tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello World!"
      }
    }
  }'

# Calculate an expression
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "calculate",
      "arguments": {
        "expression": "15 * 4 + 10"
      }
    }
  }'

🔧 Configuração

Variáveis de Ambiente

Crie um arquivo .env.local:

# Local Redis (Docker)
REDIS_URL=redis://localhost:6379

# Upstash Redis (Production)
UPSTASH_REDIS_REST_URL=your-upstash-url
UPSTASH_REDIS_REST_TOKEN=your-upstash-token

Configuração do Redis

O servidor detecta e usa automaticamente o Redis nesta ordem de prioridade:

  1. Upstash Redis (se UPSTASH_REDIS_REST_URL e UPSTASH_REDIS_REST_TOKEN estiverem definidos)
  2. Redis Local (se REDIS_URL estiver definido)
  3. Sem Redis (apenas transporte HTTP)

Redis Local com Docker

# The setup script handles this automatically, but you can also run manually:
docker run -d --name redis-mcp -p 6379:6379 redis:alpine

Upstash Redis (Recomendado para Produção)

  1. Crie um banco de dados Upstash Redis em upstash.com
  2. Adicione os detalhes de conexão ao seu .env.local
  3. O servidor detectará e usará automaticamente

🖥️ Integração com Ferramentas de IA

Claude Desktop

Adicione à configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "custom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

Locais dos arquivos de configuração:

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

IDE Cursor

Para Cursor 0.48.0 ou posterior (suporte direto a SSE):

{
  "mcpServers": {
    "custom-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Para versões anteriores do Cursor:

{
  "mcpServers": {
    "custom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

🛠️ Desenvolvimento

Estrutura do Projeto

custom-mcp-server/
├── app/
│   ├── [transport]/
│   │   └── route.ts          # Main MCP server logic
│   ├── layout.tsx            # Root layout
│   └── page.tsx              # Home page
├── lib/
│   └── redis.ts              # Redis utilities
├── scripts/
│   ├── setup.mjs             # Automated setup
│   ├── test-http-client.mjs  # HTTP transport tests
│   ├── test-sse-client.mjs   # SSE transport tests
│   └── test-tools.mjs        # Comprehensive tool tests
├── package.json
├── next.config.ts
└── README.md

Adicionando Novas Ferramentas

  1. Defina a ferramenta em app/[transport]/route.ts:
const tools = {
  // ... existing tools
  myNewTool: {
    name: "my-new-tool",
    description: "Description of what your tool does",
    inputSchema: {
      type: "object",
      properties: {
        param1: {
          type: "string",
          description: "Description of parameter"
        }
      },
      required: ["param1"]
    }
  }
};
  1. Adicione o manipulador:
const toolHandlers = {
  // ... existing handlers
  "my-new-tool": async ({ param1 }: { param1: string }) => {
    // Your tool logic here
    return {
      content: [
        {
          type: "text",
          text: `Result: ${param1}`
        }
      ]
    };
  }
};

Testando Suas Alterações

# Run all tests
npm run test:tools

# Test specific functionality
npm run test:http
npm run test:sse

📝 Referência da API

Tools/List

Obtenha todas as ferramentas disponíveis:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Tools/Call

Chame uma ferramenta específica:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "tool-name",
    "arguments": {
      "param": "value"
    }
  }
}

🚀 Implantação

Vercel (Recomendado)

  1. Implante na Vercel:

    vercel

  2. Adicione variáveis de ambiente no painel da Vercel:

    • UPSTASH_REDIS_REST_URL
    • UPSTASH_REDIS_REST_TOKEN

  3. Atualize as configurações das suas ferramentas de IA para usar a URL implantada:

    https://your-app.vercel.app/mcp
https://your-app.vercel.app/sse

Outras Plataformas

O servidor é uma aplicação Next.js padrão e pode ser implantado em qualquer plataforma que suporte Node.js:

  • Netlify
  • Railway
  • Render
  • DigitalOcean App Platform

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso: git checkout -b feature/my-new-feature
  3. Faça suas alterações e adicione testes
  4. Execute a suíte de testes: npm run test:tools
  5. Faça commit das suas alterações: git commit -am 'Add some feature'
  6. Envie para o branch: git push origin feature/my-new-feature
  7. Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🆘 Solução de Problemas

Problemas Comuns

Servidor não iniciando:

  • Verifique se a porta 3000 está disponível
  • Garanta que todas as dependências estejam instaladas: npm install

Problemas de conexão com Redis:

  • Verifique se o Docker está em execução: docker ps
  • Verifique o status do contêiner Redis: docker ps -a | grep redis-mcp
  • Reinicie o Redis: docker restart redis-mcp

Ferramenta de IA não detectando o servidor:

  • Garanta que o servidor esteja em execução e acessível
  • Verifique a sintaxe do arquivo de configuração (JSON válido)
  • Reinicie sua ferramenta de IA após alterações na configuração
  • Verifique se a URL do servidor está correta

Chamadas de ferramentas falhando:

  • Verifique os logs do servidor para mensagens de erro
  • Teste as ferramentas manualmente com npm run test:tools
  • Verifique se os parâmetros da ferramenta correspondem ao esquema esperado

Modo de Depuração

Ative o registro de depuração definindo a variável de ambiente:

DEBUG=1 npm run dev

📞 Suporte

  • Crie um issue no GitHub para relatar bugs
  • Verifique os issues existentes para problemas comuns
  • Revise os scripts de teste para exemplos de uso