MCP Pacemaker

mcp-pacemaker

Um supervisor de processos local e ponte de transporte para seus servidores MCP. Gerencie o ciclo de vida do servidor fora do seu editor ou CLI, com pré-aquecimento opcional e compartilhamento de sessão compatível. A ponte de longa duração não tem dependências de runtime de terceiros; a CLI de configuração e os painéis têm suas próprias dependências.

Instalar a partir do npm · Relatar um problema · Notas de versão

Este README descreve 2.1.0. Verifique sua disponibilidade no npm antes de instalar; uma branch de origem ou tag do GitHub não é prova de publicação. Consulte as alterações da versão.

Hosts MCP — editores (VS Code, Cursor, Claude Desktop) e CLIs (Claude Code, Copilot CLI, Codex, Gemini) — executam servidores MCP stdio como processos filhos. Quando o host reinicia, falha ou sai (a cada execução de CLI de uso único), esses servidores morrem. mcp-pacemaker executa seus servidores como filhos de uma ponte pequena e de longa duração e expõe cada um sobre o transporte MCP HTTP+SSE / Streamable HTTP. Vários hosts usam uma ponte, com um filho isolado por sessão por padrão. Opte pelo pré-aquecimento ou reutilize um filho inicializado para sessões de ferramentas sem estado compatíveis com o modo compartilhado. Conecte hosts a uma ponte ou dê a cada um a sua própria. Um supervisor multiplataforma + inicialização automática do SO mantêm a própria ponte viva em reinicializações e suspensão/ativação, e uma camada de autenticação conectável injeta um token novo por solicitação para servidores HTTP.

Após uma reinicialização, um cliente que retorna pode reutilizar um ID de sessão registrado para restabelecer seu handshake contra um servidor novo. Isso não restaura estado arbitrário de ferramentas nem preserva conexões TCP. Clientes que param de tentar após uma conexão perdida ainda podem precisar de um recarregamento; a transferência de socket é um trabalho planejado separado.

Início rápido

Instale mcp-pacemaker 2.1.0 a partir do npm. Use uma versão mantida do Node.js 22 ou 24; o Windows também precisa do PowerShell 7 e do Windows Script Host. Consulte requisitos de instalação antes da configuração.

npm view mcp-pacemaker@2.1.0 version
npm install -g mcp-pacemaker@2.1.0
mcp-pacemaker --version

A verificação de versão imprime 2.1.0 sem executar a configuração.

Execute como um usuário comum. A partir da 2.1.0, a ponte, o supervisor e as atualizações padrão recusam um chamador privilegiado na inicialização — um terminal não administrador no Windows e uma sessão não root no Linux/macOS, incluindo o usuário padrão root na maioria dos contêineres. Uma inicialização recusada imprime User-runtime execution refused: …. Não há substituição; execute como um usuário normal. Consulte o contrato de runtime do usuário.

Antes da configuração, tenha um arquivo de configuração JSON legível contendo definições de servidor, ou prepare ~/.mcp-pacemaker/servers.json. As fontes de importação suportadas são vscode, cursor, claude (Claude Desktop), copilot-cli e gemini. Codex e Claude Code são destinos de conexão, não fontes de importação.

Em seguida, execute a configuração interativa:

mcp-pacemaker init

init detecta hosts suportados, importa um host de origem (ou reutiliza servers.json), pede confirmação antes de conectar os hosts selecionados, registra a inicialização automática do SO e inicia a ponte. Recarregue ou reinicie os hosts selecionados depois.

A configuração altera a configuração local e a inicialização automática. A importação pode criar ou atualizar servers.json antes da confirmação de conexão. Arquivos de host JSON/TOML existentes recebem um .bak antes da substituição; registros nativos do Claude Code não. Mantenha seu próprio backup de configuração protegido, especialmente antes de repetir a configuração.

--from escolhe a fonte de importação; --client escolhe os destinos de conexão. Por exemplo, mcp-pacemaker init --from vscode --client codex importa as definições do VS Code e conecta o Codex. Sem --from, a configuração prefere o primeiro host JSON detectado; ela não mescla cada host detectado. Omita --yes para manter o prompt de confirmação.

Verifique a ponte em execução:

mcp-pacemaker status     # status without entering first-run setup
mcp-pacemaker top        # live terminal dashboard
mcp-pacemaker doctor     # diagnose config, reachability, wiring

mcp-pacemaker import  --from <source>          # write servers.json from one JSON host config
mcp-pacemaker plan    --client <host>          # dry run: show what install would change
mcp-pacemaker install --client <host>          # wire one host (--port N gives it its own bridge)
mcp-pacemaker start                            # start the bridge

# e.g. import from Cursor, then wire three hosts to the same bridge
mcp-pacemaker import  --from cursor
mcp-pacemaker install --client cursor
mcp-pacemaker install --client claude-code
mcp-pacemaker install --client gemini

Qual modo de compartilhamento de processo?

Compartilhar uma ponte não compartilha automaticamente um processo de servidor.

Clientes compartilhados devem enviar parâmetros de inicialização idênticos, incluindo clientInfo, e capacidades de cliente vazias. Não é compartilhamento automático entre editores. Consulte limites do modo compartilhado antes de habilitá-lo.

Escolhendo uma ferramenta de transporte

Documentação verificada em 27 de setembro de 2026; este é um guia de casos de uso, não um benchmark de recursos.

Esses projetos têm capacidades sobrepostas. Reconectar a um servidor novo não é recuperação de estado arbitrário de aplicativo, e uma ponte de transporte não é uma sandbox para ferramentas não confiáveis.

Hosts suportados

Editores e CLIs são detectados automaticamente e conectados à ponte. A maioria dos hosts recebe Streamable HTTP (/<name>/mcp); Cursor e Claude Desktop são conectados via SSE (/<name>/sse) até que Streamable HTTP seja verificado lá. A ponte centraliza a autenticação, então os hosts falam com ela sem autenticação via loopback.

Topologias: conecte cada host a uma ponte compartilhada (padrão) ou dê a cada host sua própria ponte (install --client X --port N) — ou qualquer combinação. status/doctor relatam todas as pontes + hosts conectados.

Instalação

Use uma versão mantida do Node.js 22 ou 24. O Node 20 continua sendo um alvo de compatibilidade, mas está em fim de vida, não é um runtime seguro recomendado. A ponte não tem dependências de runtime npm; a CLI de configuração e o painel têm suas próprias dependências.

Execute como um usuário comum. A partir da 2.1.0, a ponte, o supervisor e as atualizações padrão verificam o chamador antes de qualquer trabalho de runtime e recusam chamadores elevados ou root na inicialização com User-runtime execution refused: …. No Linux e macOS, isso inclui root, que é o usuário padrão na maioria das imagens de contêiner, então execute a ponte como uma conta normal lá. O contrato de runtime do usuário descreve o que é verificado e por quê; a administração explícita de contas do Windows tem um caminho controlador/trabalhador separado.

Instale o pacote publicado a partir do npm. O link do repositório deve apontar para girishkvs/mcp-pacemaker. Use uma versão exata para uma instalação reproduzível:

npm view mcp-pacemaker@2.1.0 version
npm install -g mcp-pacemaker@2.1.0
mcp-pacemaker --version

A linha atual usa o canal npm latest; a linha de manutenção usa legacy quando esse canal foi publicado. Verifique os valores reais do registro antes de escolher um canal:

npm view mcp-pacemaker dist-tags --json

Tags do GitHub e publicação no npm são separadas: uma tag não estabelece que a mesma versão ou canal está disponível no npm, nem que os bytes do pacote são idênticos. @1 e @2 são faixas de versão, não os canais mantidos. Elas podem selecionar uma versão retirada de um canal. upgrade --self resolve o canal da versão principal instalada e imprime um comando de versão exata; nunca instala ou faz downgrade de nada.

Use um diretório de instalação durável para um serviço de longa duração. Não registre a inicialização automática a partir de um cache npx: esse cache pode ser removido depois. A invocação CLI simples pode entrar no assistente de configuração; use --version para uma verificação de instalação somente leitura.

A configuração do Windows também precisa do PowerShell 7 (pwsh) e do Windows Script Host para seu launcher. Edições automáticas de configuração precisam do .NET Framework 4.6.2 ou mais recente. O helper incluído é não assinado; a proveniência npm não é assinatura Authenticode nem uma lista de permissões de controle de aplicativo. Windows ARM64 não é validado.

Compatibilidade de versão

Este README descreve 2.0.x. Para o comportamento de salvamento imediato da 1.3.x, consulte a documentação legada e a política de suporte. Esses documentos não estabelecem que uma versão legada está disponível no npm.

As linhas de base históricas permanecem 1.3.0 / 2.0.0. As evidências do par de patches anterior 1.3.1 / 2.0.1 não são transferíveis para uma nova versão. O par selecionado 1.3.1 / 2.0.2 exige novas portas de compatibilidade exata de bytes e de substituição de serviço. Um cliente 2.x lida com salvamentos imediatos legados. Um cliente 1.x não pode gravar configurações de agrupamento em uma ponte 2.x: atualize a CLI e atualize as abas antigas do painel. Antes de fazer downgrade, resolva transações pendentes ou interrompidas com 2.x. Consulte as portas de versão real para pares exatos; apenas os pares exatos executados são cobertos.

Referência de comandos

A instalação do pacote sozinha não atualiza um backend em execução. Use upgrade --to explícito para substituição gerenciada. upgrade puro mantém o comportamento antigo de reparo de host.

Ao iniciar, o pacemaker verifica a porta: ele adota uma ponte pacemaker existente e recusa colidir com um serviço estrangeiro (o assistente oferece outra porta).

Para um supervisor criado por estas versões de patch, stop --port N verifica a identidade de instalação/configuração correspondente, aguarda o desligamento e mantém o início automático gerenciado até um start --port N explícito. O desligamento normal do SO não cria essa retenção. Use a CLI da instalação correspondente. Pontes mais antigas ou iniciadas diretamente não têm registro de parada gerenciada e são recusadas em vez de relatadas como paradas; desative o início automático do SO e verifique o desligamento primeiro.

No Linux/macOS, o socket de controle fica ao lado da configuração, independente de TMPDIR. Seu caminho completo deve caber em 103 bytes UTF-8. install e init verificam isso antes de alterar a configuração ou o início automático; use um local de configuração mais curto em vez de depender de um fallback implícito de localização de socket.

Servidores stdio isolados e em pool suportam HTTP+SSE (/<name>/sse) e Streamable HTTP (/<name>/mcp). O modo compartilhado requer Streamable HTTP.

install faz backup de um arquivo de host JSON/TOML existente para .bak; repeti-lo substitui esse backup. uninstall restaura backups disponíveis de arquivos de host, deixa arquivos sem backup como estão e mantém servers.json. Registros nativos do Claude Code não são copiados ou restaurados automaticamente; registre suas definições originais separadamente e restaure-os através do Claude Code.

Substituindo ou revertendo uma instalação em execução

Estes comandos de atualização gerenciada requerem 2.1.0 ou mais recente. A versão 2.0.2 não os inclui.

Execute a ponte, o supervisor, as atualizações padrão e a recuperação como um usuário comum: um terminal normal, não administrador no Windows e uma sessão não root no Linux/macOS. O contrato de runtime do usuário rejeita chamadores privilegiados ou não verificados antes do trabalho de runtime, então uma substituição não herda autoridade diferente. Planos somente leitura permanecem disponíveis. A administração explícita de conta Windows tem um caminho de controlador/trabalhador separado e requisitos de qualificação.

Para uma instância gerenciada estável criada por esta implementação:

mcp-pacemaker upgrade --to <exact-version> --plan
mcp-pacemaker upgrade --to <exact-version>
# Noninteractive confirmation of the displayed local plan:
mcp-pacemaker upgrade --to <exact-version> --yes

# Keep the existing service and host wiring:
mcp-pacemaker upgrade --to <exact-version> --sxs
mcp-pacemaker upgrade --to <exact-version> --sxs --port 9001

--to requer SemVer estável canônico, não latest, um intervalo ou uma especificação Git/arquivo. Selecionar outra versão principal é explícito e impresso no plano; não é uma alegação de compatibilidade. O alvo deve fornecer o protocolo de admissão/prontidão gerenciado. Alvos mais antigos sem esse protocolo são rejeitados antes da interrupção, incluindo para portas SxS automáticas.

Atualizações normais preservam a porta selecionada: --port é válido somente com --sxs. Sem uma porta SxS, o novo listener de loopback real vincula a porta 0 e permanece aberto; a porta selecionada pelo SO é exibida e salva para inícios posteriores. O plano somente leitura diz "atribuída pelo SO", não uma porta adivinhada. Uma porta ocupada explicitamente solicitada falha sem adoção. SxS obtém configuração, nonce, logs e arquivos de sessão separados. Preserva o diretório de trabalho da fonte para comandos de servidor relativos e não reconecta nenhum host nem habilita pooling.

Quando a descoberta encontra várias instâncias, use o diretório exato impresso pela configuração/atualização:

mcp-pacemaker upgrade --instance <directory> --to <exact-version> --plan
mcp-pacemaker start --instance <directory>
mcp-pacemaker stop --instance <directory>

--instance <directory> e --instance=<directory> funcionam antes ou depois do comando. A seleção é normalizada uma vez, incluindo caminhos com espaços; seletores conflitantes ou substituições de porta/configuração são rejeitados antes de uma ação. Texto após -- não é interpretado como um seletor. Uma seleção explícita inválida nunca recai para a instância padrão. Opções de porta da CLI usam inteiros decimais canônicos de 1 a 65535; notação científica, hex, sinais, espaços ao redor e grafias com zeros à esquerda são rejeitados antes de solicitações.

start selecionado, stop, reload, prewarm, status, doctor, top, logs, dashboard, versão/ajuda e comandos de atualização usam o mesmo contexto de instância. A tecla de reciclagem do TUI usa a porta e diretório de nonce dessa instância; logs usam seu diretório de configuração. mcp-pacemaker --instance <directory> puro mostra status mesmo quando SxS não tem estado de conexão de host. Comandos de configuração/remoção de host (init, import, install, uninstall) são recusados com --instance; a seleção sozinha não autoriza reescrever a configuração de host ou alterar o início automático. Comandos gerados de Cancelar/Desfazer de pré-aquecimento retêm a instância e configuração selecionadas, então resolvem a mesma versão de CLI e diretório de nonce. Comandos Windows usam um launcher PowerShell codificado com uma lista de argumentos nativa explícita para preservar espaços, aspas e caracteres de shell; comandos --config não gerenciados permanecem suportados.

O launcher estável por instância seleciona diretórios de versão verificados. Atualizações nunca substituem um pacote em execução nem reescrevem tarefas de início automático por versão. A seleção anterior e o pacote são retidos. O ponto de entrada de comando existente despacha para a CLI da versão confirmada e suas próprias dependências: --version comum, status, update-check e o próximo upgrade usam essa versão. Uma ativação inacabada mantém a CLI anterior disponível para recuperação; a reversão restaura essa seleção de CLI. SxS não altera a CLI padrão. Use --instance <directory> para selecionar sua CLI explicitamente.

As dependências do alvo são resolvidas em um lock privado e restauradas com as verificações de integridade de arquivo npm antes da interrupção. Tanto o lock quanto os arquivos de dependência instalados entram no inventário de versão verificado. A inicialização e a versão da CLI alvo são verificadas antes de silenciar. O arquivo alvo e as dependências de CLI resolvidas requerem metadados de integridade SHA-512. Informações de integridade somente SHA-1 ou ausentes são rejeitadas antes da interrupção; o atualizador não rebaixa suas verificações para acomodar um registro. A aquisição usa o registro npm configurado, ou --registry explícito, sem fallback de registro ou alterações globais no npm. Permissões npm existentes, TLS, política de idade de lançamento e mapeamento de prefixo de URL permanecem em vigor; scripts de ciclo de vida são desativados para aquisição. Para espelhos npm 12, use seu mapeamento aprovado de prefixo de URL completo replace-registry-host local ao comando de volta através desse registro—não um URL de espelho codificado ou bypass de registro público.

Download, integridade de arquivo, verificações de pacote/engine/binário nativo e uma verificação de inicialização de pacote próprio terminam antes da interrupção. A admissão então fecha e aguarda até oito segundos para que o trabalho seguro seja drenado. Sessões MCP abertas e transações de configuração não resolvidas atualmente causam uma recusa; feche/resolva-as e tente novamente. Nenhuma chamada de ferramenta incerta ou commit de configuração falho é reproduzido. Este é um reinício curto, não handoff de socket ou zero tempo de inatividade. Clientes e abas de painel podem precisar de um recarregamento.

O supervisor persiste a retenção de admissão antes de encaminhar o silenciamento. Uma resposta perdida, drenagem falha, falha de ponte ou child de substituição não a libera. Somente retomada/recuperação explícita ou uma ativação verificada abre a admissão novamente. A parada de atualização está vinculada à geração drenada; qualquer geração de substituição deve permanecer retida.

O diário de ativação bloqueia inícios não supervisionados após uma transição interrompida. Seleção e intenção de lançamento são transições duráveis separadas. Um alvo selecionado que foi comprovadamente nunca lançado pode recuperar usando o recibo exato da geração parada anterior. Após a intenção de lançamento, uma porta vazia sozinha não é prova de desligamento. A recuperação analisa identidades limitadas de instância/diário antes de verificar bytes executáveis. Ela verifica e executa completamente a CLI de recuperação retida, então um arquivo alvo danificado ou ausente não pode impedir uma reversão segura pré-lançamento. Um pacote anterior danificado, identidade desatualizada ou diário desconhecido ainda causa uma recusa.

A reversão automática é restrita a falha de inicialização antes da admissão do alvo, com bytes de configuração inalterados, identidade e segurança e desligamento verificado. Se a admissão pode ter ocorrido, a recuperação recusa em vez de sobrescrever o estado do usuário.

mcp-pacemaker upgrade --recover --instance <directory> --yes

Uma falha pode deixar upgrade.lock. A recuperação não o rouba com base em um PID reutilizável. Verifique se o atualizador original saiu, preserve o diário e remova apenas o lock dessa instância antes da recuperação. Mantenha pacotes, configuração e arquivos de transação. Escritas no diário são liberadas em arquivo e renomeadas atomicamente; durabilidade de entrada de diretório Windows através de perda de energia não é garantida.

Migração única de reinício Windows 1.3

A confirmação normal upgrade --to <exact-version> também suporta a forma exata conhecida 1.3.0 do supervisor/launcher Windows e tarefa por usuário, com uma porta no estado de instalação existente. Invoque uma CLI capaz de atualização a partir de um pacote durável separado; não sobrescreva o pacote 1.3 em execução primeiro. --plan permanece somente leitura. Esta transição reinicia o Pacemaker, não o Windows. Pausa os chamadores antes de confirmar. A confirmação interativa informa que os clientes serão desconectados e que o 1.3 não pode drenar ou certificar cada resultado HTTP em andamento. Zero sessões relatadas ou PIDs filhos não prova que as chamadas HTTP terminaram. Invocações comuns de --yes e não assistidas recusam esta transição; não há flag de manutenção separada e nenhuma reprodução automática de chamadas.

O pacote alvo, as dependências de CLI, as identidades nativas e a inicialização empacotada são verificados antes do tempo de inatividade. Um broker separado retém identificadores para o supervisor selecionado, a ponte e um conjunto limitado de descendentes comprovadamente próprios. Apenas a tarefa selecionada e verificada é retida. A parada usa esses identificadores e verifica a saída deles antes de iniciar o alvo retido na mesma porta. Ela não usa kill por nome/PID nem assume que a desativação da tarefa interrompeu o supervisor em execução. Configuração, cabeamento do host e porta permanecem inalterados; o ponto de entrada de CLI existente despacha a CLI gerenciada recém-selecionada.

A preparação permanece fora da descoberta gerenciada até que a identidade da instância e o diário de recuperação sejam duráveis; o diretório preparado é então publicado junto. Uma falha de I/O pré-diário deixa a instalação antiga descobrível. A preparação com falha é retida, não presumida como segura para exclusão. Um candidato terminal com rollback/abortado é excluído apenas após seu diário limitado e a vinculação da fonte legada validarem, para que arquivos de destino danificados não impeçam a nova tentativa da instalação legada ainda em execução.

O proprietário do recurso e o descritor de segurança completo da tarefa são separados da conta de execução. O planejamento e cada operação de tarefa exigem inspeção de proprietário/grupo/DACL/SACL/integridade por meio do Agendador de Tarefas. Se a leitura de segurança necessária for negada ou não suportada, a migração recusa antes de tocar na tarefa; ela não habilita privilégios nem eleva. Atualizações de tarefas existentes preservam a segurança em vez de reatribuir o proprietário: elas limpam apenas o descritor incorporado da definição temporária, não passam descritor de segurança substituto, desabilitam edições automáticas de ACE de principal e verificam o descritor de recurso bruto completo novamente depois. Backups protegidos retêm o descritor bruto original e o XML. A restauração exige igualdade exata de todos os campos de registro/segurança não-XML e XML normalizado pelo Agendador de Tarefas, ignorando apenas a representação exata de Task/RegistrationInfo/SecurityDescriptor incorporada. Pré-condições de revisão bruta, backups e o XML/hash retornado real não são reescritos; outros metadados ou desvios de XML recusam. Alterações de segurança concorrentes ou incertas exigem inspeção, não reparo de permissão. O proprietário do recurso pode ser o usuário em tempo de execução ou os Administradores internos canônicos; isso não altera a conta de execução. O escopo padrão permanece usuário atual, mas a execução e a recuperação do Windows exigem um chamador comum recém-verificado antes de preparação ou mutação; um chamador elevado ou não verificado recusa em vez de iniciar um runtime com autoridade diferente. O planejamento somente leitura permanece inalterado. A administração explícita da conta original usa um controlador confiável somente de tarefa e um trabalhador de usuário original; consulte escopo e qualificação de atualização de conta. --all-users é explicitamente não suportado.

O recibo legado relata legacyRootStopVerified, observedDescendantsStopped e treeCompleteness: "unproven" separadamente. Isso não é a prova moderna de descendentes completos do Job Object. Processos órfãos históricos ou não capturados não podem ser totalmente atribuídos; eles são deixados intocados e a limitação é relatada sem alegar uma contagem de órfãos. O novo runtime gerenciado contém filhos futuros desde o nascimento.

Formas desconhecidas de pacote/tarefa, proprietário/geração/configuração alterados, uma parada de processo capturado com falha ou um listener estrangeiro impedem a ativação. Um listener estrangeiro nunca é interrompido. O código original e os backups protegidos de configuração/tarefa são retidos. Uma falha de destino pré-admissão verificada pode restaurar a CLI original e a tarefa com escopo e verificar um backend legado novo; resultados incertos de inicialização, registro ou admissão exigem recuperação explícita. Nenhuma configuração é excluída ou reproduzida.

Uma migração interrompida também pode deixar o legacy-upgrade/upgrade.lock do perfil. Verifique se esse upgrader exato saiu antes de remover seu bloqueio; nunca o roube por adivinhação de PID. Preserve o diário e os arquivos de backup.

Este adaptador não suporta pontes não registradas diretas, outras versões legadas, várias portas legadas, registros Linux/macOS ou SxS de fonte legada. Os alvos devem declarar legacyRestartProtocol: 1; alvos publicados mais antigos sem ele recusam antes do tempo de inatividade legado.

O SxS gerenciado mantém sua própria cópia de pacote verificada, bem como estado de runtime separado. Se ocorrer uma falha durante a inicialização da porta 0 antes que a porta seja registrada de forma durável, a recuperação relata um resultado de inicialização desconhecido em vez de marcá-lo como abortado com segurança. Preserve essa instância e seu diário até que a prontidão ou o desligamento possam ser verificados.

Para uma instalação mais antiga que exige uma migração manual verificada separadamente:

Não sobrescreva um diretório de pacote enquanto seu supervisor ou ponte estiver em execução. Trabalhadores e helpers nativos podem carregar depois, e os ativos do dashboard são lidos do disco: a substituição pode misturar código antigo e novo mesmo quando o processo original ainda relata sua versão antiga.

Identifique a porta selecionada, o diretório de instalação, o diretório de configuração e a entrada de inicialização automática do SO primeiro. Liquide ou cancele lotes 2.x, recupere transações interrompidas com 2.x e mantenha um backup de configuração protegido. Desative a entrada de inicialização automática selecionada e pare seu supervisor e ponte antes de substituir arquivos; prove que eles não podem reiniciar durante a substituição. Mantenha a instalação conhecida como boa até que a versão e a identidade da instância do novo backend sejam confirmadas. Re-registre o caminho de inicialização automática pretendido, atualize as abas do dashboard e confirme o cabeamento do host.

Um prefixo npm global contém uma versão de pacote e seus nomes de comando compartilhados. Instalar a outra versão principal lá a substitui. Portas separadas não isolam credenciais, nonces, logs ou arquivos de sessão: a operação manual lado a lado precisa de raízes de código duráveis separadas e diretórios de configuração separados, além de estado de host/HOME separado para configuração gerenciada por CLI. init/import --config seleciona uma configuração de host de origem, não um perfil de runtime isolado. Não há switch de pacote --profile ou MCP_HOME; o SxS gerenciado usa diretórios de instância explícitos. Não use uma operação de parada/desinstalação sem escopo quando outra instância deve permanecer em execução.

Dashboards

Duas visualizações do mesmo estado ativo. Nenhuma é obrigatória — a ponte roda sem cabeça — mas ambas são úteis para responder "este servidor está realmente ativo e quem o está usando?"

Dashboard web

mcp-pacemaker dashboard, ou abra http://127.0.0.1:<port>/ui. Ele transmite via SSE, então atualiza sozinho sem polling ou refresh.

Por servidor, mostra o transporte (stdio / http), a política de compartilhamento (pool quando pré-aquecido), sessões ativas contra o limite, contagem de solicitações, os PIDs reais do SO, a contagem do pool aquecido, há quanto tempo foi usado pela última vez e quais clientes estão conectados — acima, um servidor é compartilhado por VS Code e Claude Code enquanto outros são mantidos por Copilot, Cursor e Codex. Recycle reinicia os processos desse servidor; está desabilitado para servidores sem sessão para reiniciar. O log ao vivo na parte inferior é o log da própria ponte, filtrável.

Controles de pré-aquecimento

A aba Pré-aquecimento coloca cada candidato stdio, pool atual e servidor compartilhado em uma tabela. Ela mostra p50/p95 de inicialização a frio, picos de sessão observados, inicializações de processo, contagens aquecidas/alvo, estado de filho compartilhado e trabalho pendente, e uma ação. Proxies HTTP são excluídos porque a ponte não inicia seus processos.

Escolha Habilitar pré-aquecimento (N) em um cartão de servidor lento ou na tabela. O botão mostra a contagem exata de aquecimento e o custo extra de processos residentes antes de você clicar. Nada o habilita automaticamente. Desabilitar pré-aquecimento remove filhos aquecidos ociosos sem matar sessões ativas após a alteração ser aplicada.

As alterações são agrupadas em uma cópia pendente completa de servers.json. Cada alteração aceita reinicia uma contagem regressiva de cinco segundos. Quando a edição para, o recarregamento valida a cópia pendente, retém o original como servers.previous.json, coloca o arquivo pendente no lugar e ativa as novas configurações. O dashboard mostra Pendente ou Aplicando até que isso tenha sucesso; o modo ativo e as contagens de aquecimento não são alterados antecipadamente. Recarregar agora libera o mesmo lote imediatamente.

Cancelar lote descarta um lote pendente sem alterar as configurações ativas. Desfazer lote prepara a configuração anterior completa para outro lote de cinco segundos, somente se nenhuma edição interveniente do arquivo ativo tiver ocorrido. Essas ações afetam o lote inteiro; o dashboard nomeia todos os servidores afetados. Um lote pendente não relacionado deve ser cancelado ou aplicado antes de Desfazer.

Os mesmos controles estão disponíveis sem um navegador:

mcp-pacemaker prewarm --port 8791
mcp-pacemaker prewarm --port 8791 --enable filesystem --count 2
mcp-pacemaker prewarm --port 8791 --disable filesystem
# Changes are queued; the printed command cancels a pending batch or undoes it after application.

Use --config <path> quando a configuração da ponte e o nonce administrativo estiverem fora do diretório padrão. --json retorna o snapshot medido. A CLI e a UI usam os mesmos dados de elegibilidade e recomendação de servidor; uma amostra de latência ausente não é relatada como uma inicialização de custo zero. A CLI retorna após o preparo, então comandos consecutivos podem entrar no mesmo lote. prewarm mostra configurações pendentes separadamente dos valores ativos. A configuração permanece JSON estrito, não JSONC; a cópia pendente preserva JSON não relacionado e exige uma revisão ativa correspondente. Conflitos são relatados em vez de sobrescrever a edição de outra pessoa.

No Windows, as gravações são executadas com a conta normal da ponte e usam auditoria herdada de diretório. O dashboard dá um aviso não bloqueante: regras de auditoria personalizadas por arquivo podem não ser transferidas para a nova cópia ativa. O original retido mantém seus metadados originais. Nenhum privilégio de leitura de auditoria, prompt de UAC ou ponte permanentemente elevada é necessário.

Isso não permite acesso mais amplo aos dados de configuração. Os candidatos devem ter restrições de acesso apropriadas antes que qualquer byte de configuração seja gravado, e as proteções de integridade suportadas devem ser retidas. A negação real de gravação na fonte ou proteção não suportada permanece um erro. As operações de configuração são executadas em um trabalhador serializado para que a inspeção de arquivos não bloqueie o tráfego MCP.

A inspeção de segurança do Windows usa o helper .NET Framework empacotado e de código-fonte próprio, em vez de iniciar o PowerShell ou compilar código a cada gravação. Edições automáticas exigem .NET Framework 4.6.2 ou posterior; o Windows moderno o inclui. O código-fonte do helper, instruções de build e metadados de integridade estão incluídos no pacote. A execução do Windows ARM64 ainda não foi validada.

Solicitações de preparo e confirmações de arquivo têm cada uma um orçamento de execução limitado; o atraso de agrupamento de cinco segundos reconhecido não mantém a solicitação HTTP original aberta. Uma confirmação já em andamento pode terminar após seu prazo. O resultado distingue uma falha pré-confirmação de um resultado confirmado ou desconhecido; ele nunca tenta novamente automaticamente nem alega que uma gravação com tempo esgotado foi revertida. As duas movimentações de arquivo não são uma troca atômica. O reload as coordena com estado de recuperação validado e posicionamento de destino sem substituição. O tráfego MCP existente continua usando a configuração anterior em memória durante a troca; um leitor externo pode brevemente encontrar o caminho ativo ausente. A recuperação não deve sobrescrever um arquivo criado por um editor externo. Releia as configurações após um resultado incerto.

Atualizando da versão 1.3.0

A versão 2.0.0 altera o protocolo de salvamento de configuração; ela não exige um novo formato de servers.json. Atualize a ponte e a CLI juntos, depois recarregue quaisquer páginas de dashboard abertas. Um cliente 1.3.0 com um nonce atual recebe HTTP 409 antes do staging, com uma instrução para atualizar o cliente. Uma aba já aberta mantém o nonce antigo após um reinício da ponte e recebe HTTP 401; atualize-a para carregar o novo dashboard e a sessão de administração.

Clientes de API personalizados devem enviar x-mcp-pooling-batch: 1. Trate HTTP 202 como aceitação, não conclusão, e siga o ID de lote retornado em prewarm.batches até que seja aplicado, cancelado ou falhe. Scripts de CLI devem igualmente aguardar a aplicação antes de confiar nas novas configurações. Desfazer agora restaura o lote completo e pode afetar vários servidores. Clientes atualizados ainda entendem a resposta HTTP 200 imediata de uma ponte 1.3.0.

Antes de fazer downgrade, cancele ou aplique alterações pendentes com 2.0 e resolva qualquer transação interrompida usando a recuperação 2.0. Pare essa ponte antes de iniciar 1.3.0 com a configuração ativa. Não use um binário 1.3.0 para recuperar arquivos de transação 2.0 nem exclua esses arquivos para contornar um erro de recuperação. Mantenha um backup protegido da configuração antes de mudar de versão. Se o worker de escrita sair, edições automáticas adicionais são recusadas até a ponte reiniciar; sessões MCP existentes continuam.

Saúde

A aba Health executa as mesmas verificações que mcp-pacemaker doctor, então você pode vê-las sem um terminal.

Ela verifica a versão do Node, se a configuração faz parse, cada definição de servidor (incluindo um servidor stdio cujo caminho relativo não será resolvido a partir do diretório em que ele rodaria — uma falha que de outra forma é silenciosa até um cliente chamá-lo pela primeira vez, e um servidor nomeado após uma das próprias rotas da ponte, que é inalcançável), qualquer servidor atualmente falhando, e se o arquivo de nonce de administração existe.

Dashboard de terminal

mcp-pacemaker top são os mesmos dados que uma TUI Ink, para quando um navegador é inconveniente:

🫀 mcp-pacemaker top                                     ● :8850 · up 176s · v1.1.0
SERVER            TYPE   HEALTH  SESS  WARM  REQ    PID       TOKEN   ERROR / CLIENTS
filesystem        stdio  ok      2     1/1   8      186276,12 -       ⇄ Visual Studio Code,Claude Code
github            stdio  ok      1     -     2      146436    -       ⇄ GitHub Copilot
sqlite            stdio  ok      1     -     2      102108    -       ⇄ Cursor
slow-tool         stdio  ok      1     -     2      103776    -       ⇄ Codex CLI
search-api        http   FAIL×3  0     -     4      -         42m     upstream rejected the crede
docs-api          http   ?       0     -     0      -         -
↑↓ select · r recycle · q quit

HEALTH é ok quando a última requisição àquele servidor teve sucesso, FAIL×n após n falhas consecutivas, e ? quando nada o chamou ainda — deliberadamente não ok, já que ausência de evidência não é o mesmo que funcionando. WARM mostra warm/minWarm para servidores em pool e - para o resto, TOKEN o tempo restante em uma credencial em cache, e a última coluna ou os clientes conectados ou o último erro. ↑↓ seleciona uma linha e r a recicla.

Lendo logs duráveis

mcp-pacemaker logs --since 2h --server filesystem
mcp-pacemaker logs --follow --grep timeout
mcp-pacemaker logs --config /path/to/servers.json --since 2026-09-07T12:00:00Z

logs lê bridge.log.1 e depois bridge.log ao lado da configuração selecionada, inclusive quando a ponte está parada. --since aceita durações em segundos/minutos/horas/dias ou um timestamp ISO com fuso horário. --server corresponde ao nome exato do servidor no cabeçalho do log; --grep é uma correspondência literal sem diferenciar maiúsculas/minúsculas, não uma expressão regular. Registros multilinha correspondentes mantêm seu cabeçalho e contexto.

--follow lida com linhas completas novas, escritas UTF-8 divididas, truncamento e rolagem até ser interrompido. Ele avisa se a rotação já descartou uma geração não lida. Apenas o histórico retido está disponível; ele não pode recuperar logs que a ponte excluiu. Linhas individuais acima de 1 MiB falham explicitamente em vez de serem truncadas silenciosamente.

Editando servers.json enquanto ele roda

Salve o arquivo e a ponte o capta. Servidores cuja definição não mudou são deixados completamente intactos — mesmos processos, mesmas sessões ativas — então adicionar um servidor não custa os quatorze que já estavam funcionando:

$ mcp-pacemaker reload           # or just save the file; the bridge watches it
✓ reloaded /Users/you/.mcp-pacemaker/servers.json on :8850
·   added:   postgres
·   changed: github
·   2 session(s) restarted; untouched servers kept theirs

Um arquivo que não faz parse, ou um servidor sem command nem url, é rejeitado inteiro — a ponte registra o motivo e continua servindo a última configuração boa, então um salvamento pela metade não pode derrubar seus servidores. Defina MCP_CONFIG_WATCH=0 para exigir um reload explícito em vez de monitorar.

Saúde do servidor

Cada servidor carrega um veredito de saúde em /api/status, doctor, top e no dashboard:

Isso é passivo e gratuito — é derivado do tráfego que a ponte já está fazendo proxy. Um erro JSON-RPC do servidor conta como saudável (ele respondeu); um 401/403, um 5xx, uma falha de spawn ou uma saída não zero conta como falha, e o estado limpa no momento em que uma requisição tem sucesso novamente.

Um servidor que ninguém chama permanece unknown para sempre, o que é honesto mas não muito útil se sua credencial expira silenciosamente durante a noite. MCP_HEALTH_INTERVAL_MS adiciona uma sondagem periódica para servidores HTTP para que eles recebam um veredito sem esperar por um cliente:

MCP_HEALTH_INTERVAL_MS=300000 mcp-pacemaker start    # probe every 5 minutes

Está desligado por padrão porque uma sondagem é uma requisição real ao serviço de outra pessoa. Defina "healthIntervalMinutes": 0 em um servidor para excluir apenas aquele, ou um número para dar a ele seu próprio intervalo. Servidores stdio não são sondados: uma sondagem significaria criar um processo, o que custa mais do que a requisição que ela pretende antecipar.

API HTTP

Tudo o que os dashboards mostram é HTTP simples na mesma porta de loopback, então você pode fazer script. Endpoints de leitura não precisam de autenticação; escritas administrativas exigem um nonce.

Mutações de pooling exigem x-mcp-pooling-batch: 1. Uma alteração preparada retorna HTTP 202 com pending: true, um ID de lote, um recibo privado de cancelamento/desfazer, e o snapshot público. Aceitação não é ativação. prewarm.batches no snapshot relata resultados pendentes, em aplicação e concluídos limitados; ele não expõe tokens de recibo nem configurações completas. Clientes sem o cabeçalho de lote são rejeitados antes que uma alteração seja enfileirada, em vez de deixar um cliente mais antigo relatar um salvamento enfileirado como já habilitado. Snapshots ricos carregam um snapshotVersion com escopo de instância para que uma resposta HTTP atrasada ou um frame SSE mais antigo não possa substituir configurações ativas mais novas nem expirar prematuramente um recibo de lote.

# is a server actually running, and who is using it?
curl -s http://127.0.0.1:8850/api/status | jq '.servers[] | {name, sessions, pids, clients}'

# watch the bridge log
curl -N http://127.0.0.1:8850/api/logs

# force a restart of one server (nonce is written next to servers.json)
curl -X POST http://127.0.0.1:8850/admin/recycle/filesystem \
  -H "x-mcp-nonce: $(cat ~/.mcp-pacemaker/admin.nonce)"

/admin/* é protegido duas vezes: a requisição deve chegar em loopback, e carregar o nonce que a ponte escreve em admin.nonce ao lado da sua configuração na inicialização. O nonce é novo a cada início, então apenas ferramentas na mesma máquina que podem ler esse arquivo — a CLI, e o dashboard que a própria ponte serviu — podem mudar qualquer coisa.

servers.json

A configuração vive em ~/.mcp-pacemaker/servers.json. import a preenche a partir da sua configuração de cliente existente e transfere audience/auth/headers, então servidores HTTP geralmente não precisam de edição manual. Veja examples/servers.example.json.

{
  "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },

  "my-api": {
    "type": "http",
    "url": "https://my-service.example.com/mcp",
    "auth": { "type": "command", "command": "my-cli print-token", "refreshMinutes": 50 }
  }
}

Opções de autenticação (por servidor HTTP):

auth.type: "command" é deliberadamente apenas "execute isso e use o que imprimir", então funciona com o que quer que emita tokens no seu ambiente. Alguns exemplos — nenhum deles é tratado de forma especial:

// Azure
{ "type": "command", "command": "az account get-access-token --resource api://<id> --query accessToken -o tsv" }
// Google Cloud
{ "type": "command", "command": "gcloud auth print-access-token" }
// AWS (e.g. a signed token from your own helper)
{ "type": "command", "command": "aws-token-helper --profile prod" }
// HashiCorp Vault
{ "type": "command", "command": "vault read -field=token secret/my-api" }
// 1Password / any secret manager
{ "type": "command", "command": "op read op://vault/my-api/token" }
// A plain script
{ "type": "command", "command": "./scripts/get-token.sh" }

Por padrão o token é enviado como Authorization: Bearer <token>; defina header para enviá-lo em outro lugar (por exemplo { "header": "X-Api-Key" }).

Quanto tempo uma credencial é armazenada em cache. Se o comando retorna um JWT, sua reivindicação exp decide — refreshMinutes é apenas um limite superior e um fallback para credenciais opacas. Isso importa porque CLIs de token servem do próprio cache: az account get-access-token devolverá um token que cunhou antes e que pode estar quase esgotado, e confiar em uma janela fixa manteria um token morto em jogo. Se o upstream rejeitar uma credencial que a ponte forneceu, esse 401 é relatado no servidor (doctor, /api/status → lastError) e a credencial é descartada em vez de reutilizada — o cliente nunca é solicitado a fazer login para um servidor que a ponte autentica.

Atalho do Azure. Um "audience": "<res>" simples expande para az account get-access-token --resource <res> …. Isso é uma conveniência apenas para usuários do Azure — todos os outros provedores usam auth.command acima.

Segurança

• A ponte vincula apenas 127.0.0.1 (loopback local) — não alcançável fora da máquina.
• Tokens são cunhados da sua própria CLI já autenticada e armazenados em cache em memória; nunca gravados em disco.
• A ponte (o processo que roda 24/7) tem zero dependências de terceiros; a CLI de configuração usa commander / @clack/prompts / picocolors / smol-toml, e a TUI adiciona ink / react.

Controles de multi-agente e recursos

Vários hosts/agentes podem compartilhar uma ponte — cada um recebe sua própria sessão isolada por padrão, e servidores HTTP compartilham o token em cache entre todos eles. O dashboard, top, e mcp-pacemaker status mostram quais agentes estão conectados a cada servidor.

Medindo a rotatividade de processos

Para servidores stdio, /api/status relata spawn.total (inicializações de processo bem-sucedidas), spawn.attempts, spawn.failures, spawn.warmAdoptions, spawn.sessionStarts e spawn.sessionResumes. As inicializações incluem SSE clássico, Streamable HTTP, reabastecimento do pool aquecido e substituições após reciclagem ou retomada. Adotar um filho aquecido existente não conta como outra inicialização. A unidade é um processo iniciado pela ponte, não todos os seus descendentes.

Esses contadores cumulativos não compartilham o limite de latência de 50 amostras. Eles são redefinidos quando o processo da ponte reinicia; compare instantâneos apenas dentro do mesmo instanceId. startedAt identifica esse intervalo. Salve o instantâneo final antes de uma reinicialização planejada para uma comparação antes/depois. Servidores proxy HTTP não têm contadores de processo locais (spawn: null).

spawn.samples e p50/p95/max ainda descrevem as últimas 50 inicializações a frio bem-sucedidas diretamente observadas, não todas as inicializações. As latências são null até serem observadas; o tempo de vida ocioso de um filho aquecido não é uma amostra de inicialização a frio. A contagem existente de requests cobre solicitações HTTP roteadas, não apenas tools/call; não a rotule como uma contagem de chamadas de ferramenta.

Modo compartilhado

Defina "sharing": "shared" em um servidor stdio apenas quando suas ferramentas não têm estado, operam em entradas explícitas e usam um contexto de credencial comum. Isso é uma afirmação do operador, não algo que latência ou capacidades de correspondência possam provar. Deixe servidores dependentes de espaço de trabalho, conversa ou conta de cliente isolados.

Sessões compatíveis têm parâmetros de inicialização completos idênticos, incluindo clientInfo, e capacidades de cliente vazias. Um filho recebe uma inicialização real; cada sessão virtual recebe seus próprios IDs, progresso, cancelamento e cursores de listas de ferramentas. Apenas a capacidade real de ferramentas do upstream é exposta. Raízes, amostragem, elicitação, tarefas, assinaturas de recursos e outros métodos com estado não são suportados. Clientes incompatíveis falham explicitamente, sem recorrer silenciosamente a um modo diferente.

Excluir uma sessão deixa as outras em execução. O filho inicializado é retido entre reconexões compatíveis por até sharedLingerMs (30 minutos por padrão). A reciclagem drena o trabalho, então substitui a geração em uso posterior. Um tempo limite ou saída do filho nunca aciona reprodução automática de uma chamada de ferramenta potencialmente executada.

O servidor mantém seu provedor de credenciais existente e recycleMinutes configurado. O modo compartilhado não promete renovação silenciosa de credenciais. O painel e a CLI prewarm mostram o estado real do filho compartilhado, membros, trabalho em fila e inicializações de processo cumulativas. Consulte o contrato de sessão compartilhada para limites e semântica de falhas.

Desinstalação

mcp-pacemaker uninstall      # use the CLI from the matching installed version

Isso interrompe pontes gerenciadas, remove entradas de inicialização automática e restaura backups de arquivos de host disponíveis. Deixa arquivos sem backups e registros nativos do Claude Code inalterados. Não é limitado a uma porta; revise substituição e reversão primeiro se outra instância deve permanecer em execução. Não baixe uma CLI diferente com npx para remover uma instalação existente.

Após o serviço instalado ter sido removido com sucesso, remova o pacote npm global:

npm uninstall -g mcp-pacemaker

Projeto

• CHANGELOG.md — notas de versão
• CONTRIBUTING.md — configuração de desenvolvimento e como os testes de regressão devem ser comprovados
• SECURITY.md — modelo de ameaças e como relatar uma vulnerabilidade

Licença

MIT © Girish Konda