ipvolt Proxy Toolkit

npx add-mcp 'https://mcp.ipvolt.com/mcp'

ipvolt Proxy Toolkit

Um servidor MCP para encontrar documentação revisada sobre proxies, gerar exemplos de configuração testados e diagnosticar falhas estruturadas de proxies. As ferramentas públicas são executadas localmente com um catálogo integrado. Elas não precisam de chave de API nem de acesso a uma conta de proxy ipvolt.

O toolkit é separado do serviço comercial de proxy da ipvolt, que ainda não está aberto. Ele não provisiona proxies, compra tráfego, acessa dados de conta nem configura a rota de rede de outro agente.

Disponibilidade

A versão publicada no npm 0.1.0 e o serviço hospedado público oferecem quatro ferramentas usando um catálogo público integrado. Verifique o status de lançamento para confirmar a disponibilidade no npm, o endpoint hospedado e as listagens de registro. Builds a partir do código-fonte funcionam independentemente desses canais de distribuição. Os metadados de registro em server.json descrevem o lançamento pretendido e não são evidência de que um canal esteja ativo.

Ferramentas

Ferramenta	O que faz	Disponibilidade
search_proxy_docs	Pesquisa guias e artigos revisados; retorna links canônicos, trechos e uma revisão de conteúdo.	Hospedada e local
get_proxy_doc	Recupera um documento ou seção nomeado em blocos limitados, com cursores de continuação vinculados à revisão.	Hospedada e local
generate_proxy_config	Retorna um modelo de GET HTTPS de versão exata com espaços reservados de ambiente local. Não executa código.	Hospedada e local
diagnose_proxy_error	Interpreta observações estruturadas como CONNECT407, falha de TLS ou timeout ambíguo; indica incerteza e limites de nova tentativa.	Hospedada e local
check_proxy_route	Faz uma solicitação limitada por meio de um proxy local explicitamente configurado para o endpoint de eco fixo da ipvolt.	Local, explicitamente habilitada

Por exemplo, pesquise com {"query":"curl proxy","topic":"setup"} e depois recupere {"documentId":"/guides/curl-proxy-setup"}. Gere um exemplo síncrono de HTTPX com {"client":"httpx","version":"0.28.1"}. Diagnostique uma falha de autenticação de proxy com {"client":"httpx","version":"0.28.1","phase":"proxy_connect","status":407}. Uma observação 407 aponta para autenticação de proxy; ela não estabelece se uma senha, estado de conta ou política de acesso é a causa.

Use consultas curtas por tópico e observações estruturadas. Forneça credenciais apenas por meio do seu ambiente local ao executar um exemplo gerado ou habilitar o diagnóstico local. Nunca envie credenciais, URLs privadas ou logs brutos como argumentos de ferramenta.

Build e conexão local

Requer Node.js 24 ou mais recente e npm. A partir do diretório do repositório:

npm ci
npm run build
npm run check:content
node dist/transports/stdio.js --version

Para um cliente que aceita uma configuração mcpServers, use um caminho absoluto para a entrada compilada:

{
  "mcpServers": {
    "ipvolt": {
      "command": "node",
      "args": ["/absolute/path/to/proxy-toolkit-mcp/dist/transports/stdio.js"]
    }
  }
}

O servidor local padrão expõe quatro ferramentas, não envia telemetria e não faz solicitações de rede. Um cliente pode enviar resultados de ferramentas ao seu próprio provedor de modelo. O servidor não pode controlar o tratamento de dados desse cliente.

Para a distribuição npm, use a versão fixada do pacote após confirmar sua disponibilidade no status de lançamento:

{
  "mcpServers": {
    "ipvolt": {
      "command": "npx",
      "args": ["--yes", "@ipvolt/proxy-toolkit-mcp@0.1.0"]
    }
  }
}

Resultados exatos de aplicações e protocolos reais estão registrados em compatibilidade de clientes.

Exemplos de configuração testados

Cliente	Versão	Interface testada
curl	8.22.0	Linha de comando, macOS/OpenSSL
Requests	2.34.2	Session, Python 3.14.7
HTTPX	0.28.1	Client síncrono, Python 3.14.7
Playwright	1.63.0	APIRequestContext, Node 24.20.0

Os modelos usam um proxy HTTP com HTTPS CONNECT, verificam o TLS do destino, desativam redirecionamentos e novas tentativas automáticas e imprimem o status ou uma categoria limitada de falha. O destino e o proxy permanecem como variáveis locais TARGET_URL e PROXY_URL. Os timeouts de Requests e HTTPX são orçamentos de fase/inatividade; não são prazos totais de trabalho. O exemplo do Playwright usa sua API de solicitação, armazena a resposta em buffer e é destinado a pequenos alvos de diagnóstico. Ele não configura navegação no navegador.

A matriz exata foi executada contra proxies autenticados controlados e origens HTTPS. Veja método de fixture e evidências. Outras versões, protocolos de proxy e plataformas não são declarados como testados. Revise o código gerado antes de executá-lo contra um destino autorizado.

Diagnóstico de rota local opcional

Defina IPVOLT_ENABLE_ROUTE_CHECK=1 e forneça o IPVOLT_PROXY_URL privado por meio do ambiente de segredos local do seu cliente MCP. Invoque check_proxy_route com {"profile":"default"}. A ferramenta não aceita URL de proxy, credencial ou argumento de destino. Habilitá-la não realiza nenhuma solicitação até que a ferramenta seja chamada.

A verificação usa um proxy CONNECT HTTP e TLS de destino verificado para solicitar apenas https://mcp.ipvolt.com/egress, com um nonce aleatório. Tem um prazo total de dez segundos, sem redirecionamento ou fallback direto, uma solicitação ativa, cabeçalhos/corpo limitados e limpeza em cancelamento. A conexão HTTP com o proxy não é criptografada; a autenticação de proxy HTTP pode ser observada nesse primeiro salto. Use uma rede confiável ou um túnel local adequado à sua configuração.

O sucesso relata o endereço de saída visto por essa única solicitação de eco. Não prova anonimato, país, tipo de proxy, propriedade ou o roteamento de um navegador, shell, SDK ou outra ferramenta de agente. Consome uma pequena quantidade de largura de banda do proxy. O serviço de eco recebe o endereço de saída da solicitação; o registro de acesso de aplicação está desativado. Configurações de depuração/TLS que possam expor credenciais ou enfraquecer a verificação são rejeitadas.

O diagnóstico requer que o serviço de eco hospedado esteja disponível. Verifique o status de lançamento antes de habilitá-lo. Verificações controladas de fixture não afirmam uma solicitação bem-sucedida por meio de um fornecedor ativo.

Serviço hospedado

A URL pública remota é https://mcp.ipvolt.com/mcp, usando Streamable HTTP. Selecione esse transporte no seu cliente MCP e insira a URL. HTTPS público, todas as quatro ferramentas em ambas as versões de protocolo suportadas e o endpoint de eco foram verificados em 14 de setembro de 2026; veja verificação hospedada. Ele expõe as quatro ferramentas públicas sem cadastro ou chave de API. O diagnóstico de rota local é omitido e tentativas diretas de chamá-lo são rejeitadas. Nenhuma configuração de proxy é aceita por este serviço.

Para uma instância de desenvolvimento local:

IPVOLT_MCP_PUBLIC_URL=http://127.0.0.1:3040/mcp npm start

O processo vincula-se ao loopback. Configuração de produção e rollback coordenado estão documentados em instruções de implantação. Limites padrão são corpos de solicitação de 32 KiB, cabeçalhos de 8 KiB, 16 solicitações concorrentes e 120 solicitações por minuto por endereço de peer observado. Origens exatas de navegador são permitidas na lista. Cabeçalhos de endereço de proxy reverso são confiáveis apenas com um proxy de loopback explicitamente configurado que os sobrescreve.

As métricas hospedadas contêm apenas o nome da ferramenta, status de sucesso/erro, duração e versão do toolkit. Argumentos de ferramenta, corpos de resultado, credenciais e endereços de saída não são registrados. A limitação de taxa retém hashes de endereço temporários por até 60 segundos; o uso local de stdio não é rastreado. Endpoints de máquina usam noindex e permanecem separados das análises controladas por consentimento do site público.

Manutenção e verificação

npm run typecheck
npm run build
npm test
npm run check:content
npm run check:manifest
npm run check:package
python3 -m unittest discover -s deploy -p 'test_*.py' -v

check:package inspeciona o tarball npm real, instala-o em um diretório de consumidor temporário e descobre/chama todas as quatro ferramentas com os caminhos de protocolo atual e legado. check:content -- --live compara cada documento Markdown integrado à sua exportação canônica pública; ele realiza apenas essas leituras públicas permitidas na lista.

O runtime não rastreia o site. Um mantenedor exporta apenas os catálogos revisados de guias/blogs públicos de uma fonte de site verificada usando scripts/export-content.ts, revisa o diff resultante e publica uma nova versão imutável do pacote. Rascunhos e aplicações operacionais privadas estão fora dessa lista de permissões. Valores SHA-256 de pacote e documento tornam mudanças de fonte observáveis.

O código é licenciado sob MIT. O conteúdo editorial integrado tem uma licença de conteúdo separada. Suporte pertence ao rastreador de problemas do repositório; omita credenciais e logs privados dos relatórios.