Toolkit MCP Server

---

Ferramentas

Sete ferramentas. Cinco estão sempre ativas e não precisam de configuração — utilitários de computação pura, além de uma consulta de IP sem SSRF. Duas sondam o host do servidor e permanecem ausentes do tools/list até que você opte por ativá-las, com falha segura.

Ferramenta	Descrição
toolkit_hash_value	Gere um digest criptográfico (sha256/sha512/sha1/md5) ou compare um valor contra um digest esperado em tempo constante.
toolkit_generate_id	Gere identificadores criptograficamente aleatórios — UUIDv4, UUIDv7 ou ULID — individualmente ou em lotes de até 1000.
toolkit_generate_qr	Codifique texto ou URL em um QR code como markup SVG, PNG base64 ou string renderizável em terminal.
toolkit_encode_value	Codifique ou decodifique um valor em base64, base64url, hex ou percent-encoding de URL, em qualquer direção.
toolkit_geolocate_ip	Resolva um IP público ou hostname para metadados geográficos e de rede — país, cidade, coordenadas, ASN, fuso horário.
toolkit_check_network	Controlado, desativado por padrão. Diagnósticos de rede somente leitura do host do servidor — ping, traceroute, conectividade TCP ou detecção de IP de saída.
toolkit_check_system	Controlado, desativado por padrão. Relate uma faceta do estado do sistema do host do servidor — SO, CPU, memória, load average ou interfaces de rede.

toolkit_hash_value

Gere um digest ou verifique um valor contra um esperado em tempo constante.

• operation: generate (digest em hex minúsculo) ou compare (verificação segura em tempo via timingSafeEqual)
• Algoritmos: sha256 (padrão) e sha512 para segurança; sha1 e md5 são expostos apenas para compatibilidade de checksum e integridade de arquivos — nunca para senhas ou assinaturas
• inputEncoding lê value como utf8 (padrão), hex ou base64, então blobs binários pulam uma ida e volta de decodificação
• Uso canônico: comparar um download contra um checksum publicado pelo fornecedor

---

toolkit_generate_id

Gere identificadores criptograficamente aleatórios a partir do CSPRNG da plataforma — a fonte correta para IDs que devem ser imprevisíveis, ao contrário de valores inventados por modelos.

• type: uuid_v4 (aleatório, padrão), uuid_v7 (ordenado por tempo, classificável por criação) ou ulid (Crockford base32 de 26 caracteres, classificável lexicograficamente)
• count gera um lote de até 1000 em uma única chamada; o array ids retornado sempre contém exatamente count valores
• Lotes de uuid_v7 e ulid são monotônicos — estritamente crescentes mesmo dentro do mesmo milissegundo — então ids permanece em ordem de criação classificada
• Somente leitura — gerar não altera nada — mas nunca idempotente, então um cliente não armazenará em cache nem deduplicará um lote

---

toolkit_generate_qr

Codifique texto ou URL em um QR code.

• format: svg (markup inline), png_base64 (bytes raster com mimeType e byteLength) ou terminal (string de blocos Unicode)
• errorCorrection (L/M/Q/H) troca capacidade de dados por tolerância a danos; margin define a largura da zona de silêncio; scale define pixels por módulo para saída raster
• O version retornado (1–40) reflete o quão denso é o dado codificado
• png_base64 também chega como um bloco de conteúdo de imagem MCP, então um cliente lendo content[] pode renderizar o código sem decodificar structuredContent
• Um PNG renderizado é limitado a 2048 px por lado — (modules + 2 × margin) × scale — então um símbolo denso em um scale alto é rejeitado com um erro tipado raster_too_large nomeando uma escala que cabe; svg e terminal são ilimitados
• data é limitado a 2953 bytes — o teto absoluto (versão 40, nível L, modo byte); a capacidade utilizável é menor em níveis de errorCorrection mais altos, então entrada acima da capacidade é rejeitada com um erro tipado data_too_large em vez de uma falha genérica

---

toolkit_encode_value

Codifique ou decodifique um valor, em qualquer direção.

• encoding: base64, base64url (alfabeto seguro para URL), hex ou url (percent-encoding)
• operation: encode (UTF-8 bruto → codificação) ou decode (valor codificado → texto)
• Entrada de decodificação malformada retorna um erro tipado decode_failed com uma dica de recuperação, não um melhor esforço silencioso

---

toolkit_geolocate_ip

Resolva um IP público ou hostname para metadados geográficos e de rede.

• Retorna país, região, cidade, latitude/longitude, ASN, organização proprietária e fuso horário
• proxy, hosting e mobile sinalizam quando o endereço é um proxy/VPN/saída Tor, uma rede de datacenter ou uma operadora móvel — um true em qualquer um deles significa que as coordenadas descrevem infraestrutura, não uma pessoa. Ausente quando o provedor não os reporta
• Um hostname é resolvido via DNS primeiro; resolvedIp ecoa o IP realmente localizado, e source nomeia o provedor que respondeu
• Livre de SSRF — o servidor chama o provedor, nunca o alvo; o IP resolvido é re-verificado contra faixas privadas, e endereços privados/reservados são rejeitados (eles não têm geolocalização pública)
• Melhor esforço e limitado pelo provedor: VPNs, proxies, NAT móvel e anycast todos derrotam IP-para-localização, a precisão é no máximo nível de cidade, e campos ausentes são reportados como desconhecidos em vez de inventados
• Strings fornecidas pelo provedor são truncadas e limpas de caracteres de controle antes de chegarem à resposta, então texto controlado por registro (org, isp, as) não pode inundar ou formatar o contexto de um modelo
• Sem chave por padrão (camada gratuita do ip-api, que é HTTP texto puro — veja TOOLKIT_GEO_BASE_URL); resultados são armazenados em cache em memória por IP resolvido sob um limite fixo de entradas

---

toolkit_check_network

Controlado — registrado apenas quando TOOLKIT_ENABLE_NET_DIAGNOSTICS=true. Diagnósticos de rede somente leitura do host do servidor.

• mode: ping (ida e volta ICMP), traceroute (caminho de saltos até o alvo), connectivity (conexão TCP bruta para target em port) ou public_ip (o IP de saída do próprio host)
• Um host que não responde é reportado como reachable: false — um resultado válido, não um erro
• Diagnostica a rede do próprio servidor, então é útil em uma implantação local ou auto-hospedada; alcançar um alvo privado/reservado/interno adicionalmente requer TOOLKIT_ALLOW_PRIVATE_NETWORK=true, o que mantém o endpoint de metadados de nuvem bloqueado por padrão

---

toolkit_check_system

Controlado — registrado apenas quando TOOLKIT_ENABLE_SYSTEM_INFO=true. Relate uma faceta do estado do sistema do host do servidor, somente leitura.

• what: os, cpu, memory, load ou interfaces
• Exatamente um objeto de faceta é preenchido por chamada, correspondendo a what
• Descreve o host em que este servidor roda, não o cliente chamador — significativo em uma implantação local ou auto-hospedada; desativado por padrão porque os e interfaces divulgam topologia do host e detalhes de versão

Recursos

Construído sobre @cyanheads/mcp-ts-core:

• Definições declarativas de ferramentas — um arquivo por ferramenta, o framework lida com registro e validação
• Tratamento unificado de erros — handlers lançam, o framework captura, classifica e formata
• Contratos de erro tipados — cada ferramenta falível declara seus motivos de falha com dicas de recuperação que o agente pode usar
• Autenticação plugável: none, jwt, oauth
• Logging estruturado com rastreamento OpenTelemetry opcional
• Transportes STDIO e Streamable HTTP

Específicos do Toolkit:

• Controle com falha segura — as duas ferramentas de sondagem de host estão ausentes do tools/list a menos que explicitamente habilitadas, então uma instância hospedada não expõe superfície de SSRF ou divulgação de informações
• Portão de rede em dois níveis — mesmo com diagnósticos habilitados, alvos privados/reservados/loopback/link-local (incluindo o endpoint de metadados de nuvem) permanecem bloqueados até que um segundo sinalizador os permita
• Primitivas baseadas em CSPRNG — identificadores e digests vêm da fonte criptográfica da plataforma, e a comparação de hash é em tempo constante via timingSafeEqual
• Geolocalização livre de SSRF — o servidor chama o provedor, depois re-verifica o IP resolvido via DNS contra faixas privadas antes da consulta, então um hostname não pode contrabandear uma solicitação para um endereço interno

Saída amigável ao agente:

• Proveniência — geolocalização ecoa o IP resolvido e nomeia o provedor que respondeu; campos upstream ausentes são reportados como desconhecidos, nunca inventados
• Resultados válidos mas inativos — um host inalcançável retorna reachable: false em vez de um erro, então chamadores ramificam com base em dados, não em texto de exceção
• Motivos de falha tipados — falhas de decodificação, digests ausentes e alvos privados bloqueados cada um carregam um motivo estruturado mais uma dica de próximo passo para recuperação

Começando

Instância Pública Hospedada

Uma instância pública está disponível em https://toolkit.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "streamable-http",
      "url": "https://toolkit.caseyjhand.com/mcp"
    }
  }
}

Auto-hospedado / Local

Adicione o seguinte ao arquivo de configuração do seu cliente MCP. Nenhuma chave de API é necessária — as cinco ferramentas sempre ativas e a camada de geolocalização sem chave padrão funcionam imediatamente.

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/toolkit-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Ou com npx (sem necessidade de Bun):

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/toolkit-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Ou com Docker:

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/toolkit-mcp-server:latest"]
    }
  }
}

Para habilitar as ferramentas controladas de sondagem de host, adicione seus sinalizadores a env (ou -e para Docker):

"env": {
  "MCP_TRANSPORT_TYPE": "stdio",
  "TOOLKIT_ENABLE_NET_DIAGNOSTICS": "true",
  "TOOLKIT_ENABLE_SYSTEM_INFO": "true"
}

Para Streamable HTTP, defina o transporte e inicie o servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Pré-requisitos

• Bun v1.3.0 ou superior (ou Node.js v24+).
• Nenhuma chave de API necessária — geolocalização usa a camada gratuita sem chave do ip-api por padrão.

Instalação

1. Clone o repositório:

git clone https://github.com/cyanheads/toolkit-mcp-server.git

2. Navegue para o diretório:

cd toolkit-mcp-server

3. Instale as dependências:

bun install

Configuração

Toda variável é opcional. Opções específicas do servidor são validadas na inicialização via o schema Zod em src/config/server-config.ts.

Variável	Descrição	Padrão
TOOLKIT_ENABLE_NET_DIAGNOSTICS	Registra a ferramenta toolkit_check_network controlada. Deixe desativado para implantações hospedadas ou compartilhadas.	false
TOOLKIT_ENABLE_SYSTEM_INFO	Registra a ferramenta toolkit_check_system controlada. Relevante apenas em uma implantação local ou auto-hospedada.	false
TOOLKIT_ALLOW_PRIVATE_NETWORK	Com diagnósticos de rede ativados, permite alvos privados/reservados/loopback. O segundo bloqueio explícito.	false
TOOLKIT_GEO_API_KEY	Chave de API para o endpoint de geolocalização, se ele exigir uma.	nenhum
TOOLKIT_GEO_BASE_URL	URL base para um endpoint de geolocalização compatível com ip-api. O padrão é HTTP em texto puro — o endpoint HTTPS do ip-api não faz parte do nível gratuito sem chave e responde 403 SSL unavailable for this endpoint sem uma chave paga. Aponte para um endpoint HTTPS (com TOOLKIT_GEO_API_KEY) para criptografar a solicitação ao provedor.	http://ip-api.com
TOOLKIT_GEO_CACHE_TTL_SECONDS	TTL do cache de geolocalização em memória, em segundos.	3600
TOOLKIT_GEO_RATE_LIMIT_PER_MIN	Máximo de solicitações de geolocalização por minuto.	45
MCP_TRANSPORT_TYPE	Transporte: stdio ou http.	stdio
MCP_HTTP_PORT	Porta para o servidor HTTP.	3010
MCP_AUTH_MODE	Modo de autenticação: none, jwt ou oauth.	none
MCP_LOG_LEVEL	Nível de log (RFC 5424).	info
OTEL_ENABLED	Ativa a instrumentação OpenTelemetry (spans, métricas, logs de conclusão).	false

Consulte .env.example para a lista completa de substituições opcionais.

Executando o servidor

Desenvolvimento local

• Compilar e executar:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Executar verificações e testes:

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t toolkit-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 toolkit-mcp-server

O Dockerfile usa como padrão transporte HTTP, modo de sessão sem estado e registra logs em /var/log/toolkit-mcp-server. As dependências de pares do OpenTelemetry são instaladas por padrão — compile com --build-arg OTEL_ENABLED=false para omiti-las.

Estrutura do projeto

Diretório	Finalidade
src/index.ts	Ponto de entrada do createApp() — registra ferramentas e inicializa serviços, com bloqueio fail-closed para as duas ferramentas de sondagem de host.
src/config	Análise e validação de variáveis de ambiente específicas do servidor com Zod.
src/mcp-server/tools	Definições de ferramentas (*.tool.ts). Sete ferramentas — cinco sempre ativas, duas controladas.
src/services/geo	Serviço de geolocalização — resolução de DNS, chamada ao provedor com nova tentativa/backoff, normalização, cache em memória.
src/services/network	Serviço de diagnóstico de rede, além do validador de alvos compartilhado e do classificador de faixas privadas.
tests/	Testes unitários e de integração que espelham a estrutura do src/.

Guia de desenvolvimento

Consulte CLAUDE.md / AGENTS.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

• Handlers lançam exceções, o framework captura — sem try/catch na lógica das ferramentas
• Use ctx.log para registro de logs no escopo da solicitação, ctx.state para armazenamento no escopo do locatário
• Registre novas ferramentas nos arrays createApp() em src/index.ts
• As duas ferramentas de sondagem de host são registradas atrás de suas flags de ativação; o bloqueio de alvos de rede valida após a resolução de DNS — nunca fabrique um resultado para um alvo não localizável ou inacessível

Contribuindo

Issues e pull requests são bem-vindos. Execute verificações e testes antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — consulte LICENSE para detalhes.