MCP Hub

Um servidor gerenciador para servidores MCP que lida com gerenciamento de processos e roteamento de ferramentas.

Documentação

MCP Hub

O MCP Hub atua como um coordenador central para servidores e clientes MCP, fornecendo duas interfaces principais:

Interface de Gerenciamento (/api/*): Gerencie múltiplos servidores MCP através de uma API REST unificada e interface web
Interface de Servidor MCP (/mcp): Conecte QUALQUER cliente MCP para acessar TODAS as capacidades dos servidores através de um único endpoint

Essa abordagem de interface dupla significa que você pode gerenciar servidores através da interface do Hub enquanto clientes MCP (Claude Desktop, Cline, etc.) precisam apenas se conectar a um endpoint (localhost:37373/mcp) para acessar todas as capacidades. Implementa a especificação MCP 2025-03-26.

Suporte a Recursos

Categoria	Recurso	Suporte	Observações
Transporte
	streamable-http	✅	Protocolo de transporte principal para servidores remotos
	SSE	✅	Transporte alternativo para servidores remotos
	STDIO	✅	Para executar servidores locais
Autenticação
	OAuth 2.0	✅	Com fluxo PKCE
	Cabeçalhos	✅	Para chaves/tokens de API
Capacidades
	Ferramentas	✅	Listar ferramentas
	🔔 Lista de Ferramentas Alterada	✅	Atualizações em tempo real
	Recursos	✅	Suporte completo
	🔔 Lista de Recursos Alterada	✅	Atualizações em tempo real
	Modelos de Recursos	✅	Modelos de URI
	Prompts	✅	Suporte completo
	🔔 Lista de Prompts Alterada	✅	Atualizações em tempo real
	Roots	❌	Não suportado
	Sampling	❌	Não suportado
	Completion	❌	Não suportado
Marketplace
	Descoberta de Servidores	✅	Navegar pelos servidores disponíveis
	Instalação	✅	Configuração automática
Tempo Real
	Atualizações de Status	✅	Estado do servidor e da conexão
	Atualizações de Capacidade	✅	Atualização automática
	Streaming de Eventos para clientes	✅	Baseado em SSE
	Reconexão Automática	✅	Com backoff
Desenvolvimento
	Hot Reload	✅	Reinício automático de um servidor MCP em alterações de arquivos com modo `dev`
Configuração
	Sintaxe `${}`	✅	Variáveis de ambiente e execução de comandos em todos os campos
	Compatibilidade com VS Code	✅	Suporte para chave `servers`, `${env:}`, `${input:}`, variáveis predefinidas
	Suporte a JSON5	✅	Comentários e vírgulas finais em arquivos de configuração

Configuração Simplificada do Cliente

Configure todos os clientes MCP com apenas um endpoint:

{
    "mcpServers" : {
        "Hub": {
            "url" : "http://localhost:37373/mcp"  
        }
    }
}

O Hub automaticamente:

Cria namespaces para capacidades para evitar conflitos (ex.: filesystem__search vs database__search)
Roteia solicitações para o servidor apropriado
Atualiza capacidades em tempo real quando servidores são adicionados/removidos
Gerencia autenticação e gerenciamento de conexões

Recursos Principais

Endpoint Unificado de Servidor MCP (/mcp):
- Endpoint único para TODOS os clientes MCP se conectarem
- Acesse capacidades de todos os servidores gerenciados através de uma conexão
- Namespacing automático previne conflitos entre servidores
- Atualizações de capacidade em tempo real quando servidores mudam
- Configuração simplificada do cliente - apenas um endpoint em vez de vários
Gerenciamento Dinâmico de Servidores:
- Iniciar, parar, habilitar/desabilitar servidores sob demanda
- Atualizações de configuração em tempo real com reconexão automática do servidor
- Suporte para servidores MCP locais (STDIO) e remotos (streamable-http/SSE)
- Monitoramento de saúde e recuperação automática
- Autenticação OAuth com fluxo PKCE
- Autenticação por token baseada em cabeçalhos
API REST Unificada:
- Execute ferramentas de qualquer servidor conectado
- Acesse recursos e modelos de recursos
- Atualizações de status em tempo real via Server-Sent Events (SSE)
- Operações CRUD completas para gerenciamento de servidores
Eventos em Tempo Real e Monitoramento:
- Status de servidor ao vivo e atualizações de capacidade
- Rastreamento de conexões de clientes
- Notificações de alteração de lista de ferramentas e recursos
- Logging JSON estruturado com saída em arquivo
Gerenciamento de Conexões de Clientes:
- Conexões simples de clientes baseadas em SSE via /api/events
- Limpeza automática de conexões ao desconectar
- Desligamento automático opcional quando não há clientes conectados
- Monitoramento de estado de conexão em tempo real
Gerenciamento do Ciclo de Vida de Processos:
- Tratamento gracioso de inicialização e desligamento
- Limpeza adequada das conexões do servidor
- Recuperação de erros e reconexão
Gerenciamento de Workspace:
- Rastreie instâncias ativas do MCP Hub em diferentes diretórios de trabalho
- Cache global de workspace no diretório de estado compatível com XDG
- Atualizações de workspace em tempo real via eventos SSE
- Endpoints de API para listar e monitorar workspaces ativos

Componentes

Servidor Hub

O servidor de gerenciamento principal que:

Mantém conexões com múltiplos servidores MCP
Fornece acesso unificado via API às capacidades do servidor
Gerencia o ciclo de vida do servidor e monitoramento de saúde
Gerencia conexões e eventos SSE de clientes
Processa atualizações de configuração e reconexão do servidor

Servidores MCP

Serviços conectados que:

Fornecem ferramentas, recursos, modelos e prompts
Suportam dois modos de conectividade:
- Servidores STDIO baseados em script para operações locais
- Servidores remotos (streamable-http/SSE) com suporte a OAuth
Implementam atualizações de capacidade em tempo real
Suportam recuperação automática de status
Mantêm interface consistente entre tipos de transporte

Instalação

npm install -g mcp-hub

Uso Básico

Inicie o servidor hub:

mcp-hub --port 3000 --config path/to/config.json

# Or with multiple config files (merged in order)
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

Opções de CLI

Options:
  --port            Port to run the server on (required)
  --config          Path to config file(s). Can be specified multiple times. Merged in order. (required)
  --watch           Watch config file for changes, only updates affected servers (default: false)
  --auto-shutdown   Whether to automatically shutdown when no clients are connected (default: false)
  --shutdown-delay  Delay in milliseconds before shutting down when auto-shutdown is enabled (default: 0)
  -h, --help       Show help information

Configuração

O MCP Hub usa arquivos de configuração JSON para definir servidores gerenciados com sintaxe universal de placeholder ${} para variáveis de ambiente e execução de comandos.

Compatibilidade de Configuração com VS Code

O MCP Hub fornece compatibilidade perfeita com o formato de configuração .vscode/mcp.json do VS Code, permitindo que você use os mesmos arquivos de configuração tanto no VS Code quanto no MCP Hub.

Recursos Suportados

Chaves de Configuração do Servidor

Ambas as chaves mcpServers e servers são suportadas:

{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "perplexity": {
      "command": "npx", 
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "API_KEY": "${env:PERPLEXITY_API_KEY}"
      }
    }
  }
}

Substituição de Variáveis

O MCP Hub suporta substituição de variáveis no estilo VS Code:

Variáveis de Ambiente: ${env:VARIABLE_NAME} ou ${VARIABLE_NAME}
Variáveis de Workspace: ${workspaceFolder}, ${userHome}, ${pathSeparator}
Execução de Comandos: ${cmd: command args}

Variáveis Predefinidas Suportadas:

${workspaceFolder} - Diretório onde o mcp-hub está sendo executado
${userHome} - Diretório home do usuário
${pathSeparator} - Separador de caminho do SO (/ ou )
${workspaceFolderBasename} - Apenas o nome da pasta
${cwd} - Alias para workspaceFolder
${/} - Abreviação do VS Code para pathSeparator

Variáveis de Entrada do VS Code

Para variáveis ${input:} usadas em configurações do VS Code, use a variável de ambiente MCP_HUB_ENV:

# Set input variables globally
export MCP_HUB_ENV='{"input:api-key":"your-secret-key","input:database-url":"postgresql://..."}'

# Then use in config
{
  "servers": {
    "myserver": {
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}

Migração do VS Code

Arquivos .vscode/mcp.json existentes funcionam diretamente com o MCP Hub. Basta apontar o MCP Hub para sua configuração do VS Code:

mcp-hub --config .vscode/mcp.json --port 3000

Múltiplos Arquivos de Configuração

O MCP Hub suporta carregar múltiplos arquivos de configuração que são mesclados em ordem. Isso permite gerenciamento flexível de configuração:

Configuração Global: Configurações de todo o sistema (ex.: ~/.config/mcphub/global.json)
Configuração do Projeto: Configurações específicas do projeto (ex.: ./.mcphub/project.json)
Configuração de Ambiente: Substituições específicas do ambiente

Quando múltiplos arquivos de configuração são especificados, eles são mesclados com arquivos posteriores substituindo os anteriores:

# Global config is loaded first, then project config overrides
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

Comportamento de Mesclagem:

Seções mcpServers são mescladas (definições de servidor de arquivos posteriores substituem as anteriores)
Outras propriedades de nível superior são completamente substituídas por arquivos posteriores
Arquivos de configuração ausentes são ignorados silenciosamente

Sintaxe Universal de Placeholder

${ENV_VAR} ou ${env:ENV_VAR} - Resolve variáveis de ambiente
${cmd: command args} - Executa comandos e usa a saída
${workspaceFolder} - Diretório onde o mcp-hub está sendo executado
${userHome} - Diretório home do usuário
${pathSeparator} - Separador de caminho do SO
${input:variable-id} - Resolve de MCP_HUB_ENV (compatibilidade com VS Code)
null ou "" - Recorre a process.env

Exemplos de Configuração

Servidor STDIO Local

{
  "mcpServers": {
    "local-server": {
      "command": "${MCP_BINARY_PATH}/server",
      "args": [
        "--token", "${API_TOKEN}",
        "--database", "${DB_URL}",
        "--secret", "${cmd: op read op://vault/secret}"
      ],
      "env": {
        "API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
        "DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
        "DB_PASSWORD": "${cmd: op read op://vault/db/password}",
        "FALLBACK_VAR": null
      },
      "dev": {
        "enabled": true,
        "watch": ["src/**/*.js", "**/*.json"],
        "cwd": "/absolute/path/to/server/directory"
      }
    }
  }
}

Servidor Remoto

{
  "mcpServers": {
    "remote-server": {
      "url": "https://${PRIVATE_DOMAIN}/mcp",
      "headers": {
        "Authorization": "Bearer ${cmd: op read op://vault/api/token}",
        "X-Custom-Header": "${CUSTOM_VALUE}"
      }
    }
  }
}

Opções de Configuração

O MCP Hub suporta tanto servidores STDIO quanto servidores remotos (streamable-http/SSE). O tipo de servidor é detectado automaticamente a partir da configuração. Todos os campos suportam a sintaxe universal de placeholder ${}.

Opções de Servidor STDIO

Para executar servidores MCP baseados em script localmente:

command: Comando para iniciar o executável do servidor MCP (suporta ${VARIABLE} e ${cmd: command})
args: Matriz de argumentos de linha de comando (suporta placeholders ${VARIABLE} e ${cmd: command})
env: Variáveis de ambiente com resolução de placeholder e fallback do sistema
cwd: O cwd para o processo que inicia o servidor MCP
dev: Configuração do modo de desenvolvimento (opcional)
- enabled: Habilita/desabilita o modo de desenvolvimento (padrão: true)
- watch: Matriz de padrões glob para monitorar alterações (padrão: ["/*.js", "/.ts", "**/.json"])
- cwd: Obrigatório caminho absoluto para o diretório de trabalho do servidor para monitoramento de arquivos

Variáveis de Ambiente Globais (`MCP_HUB_ENV`)

O MCP Hub procurará a variável de ambiente MCP_HUB_ENV (uma string JSON) em seu próprio ambiente de processo. Se definida, todos os pares chave-valor desta variável serão injetados no ambiente de cada servidor MCP gerenciado (tanto stdio quanto remoto). Isso é útil para passar segredos, tokens ou outras configurações compartilhadas para todos os servidores sem repeti-los em cada configuração de servidor.

Campos env específicos do servidor sempre substituem valores de MCP_HUB_ENV.

Exemplo de uso:

MCP_HUB_ENV='{"DBUS_SESSION_BUS_ADDRESS":"/run/user/1000/bus","MY_TOKEN":"abc"}' mcp-hub --port 3000 --config path/to/config.json

Opções de Servidor Remoto

Para conectar a servidores MCP remotos:

url: URL do endpoint do servidor (suporta placeholders ${VARIABLE} e ${cmd: command})
headers: Cabeçalhos de autenticação (suporta placeholders ${VARIABLE} e ${cmd: command})

Detecção de Tipo de Servidor

O tipo de servidor é determinado por:

Servidor STDIO → Tem campo command
Servidor remoto → Tem campo url

Nota: Uma configuração de servidor não pode misturar campos de servidor STDIO e remoto.

Ordem de Resolução de Placeholders

Comandos Primeiro: ${cmd: command args} são executados primeiro
Variáveis de Ambiente: ${VAR} são resolvidas do objeto env, depois process.env
Fallback: Valores null ou "" recorrem a process.env
Multi-passagem: Dependências entre variáveis são resolvidas automaticamente

Nix

Instalação via Nixpkgs

em breve...

Instalação via Flake

Basta adicioná-lo ao seu flake.nix do NixOS ou home-manager:

inputs = {
  mcp-hub.url = "github:ravitemer/mcp-hub";
  ...
}

Para integrar o mcp-hub à sua configuração do NixOS/Home Manager, adicione o seguinte ao seu environment.systemPackages ou home.packages respectivamente:

inputs.mcp-hub.packages."${system}".default

Uso sem instalação

Se você quiser usar o mcphub.nvim sem ter o servidor mcp-hub no seu PATH, você pode vincular o servidor nos bastidores adicionando o caminho do store nix do mcp-hub ao comando cmd na configuração do plugin como

Exemplo Nixvim:

{ mcphub-nvim, mcp-hub, ... }:
{
  extraPlugins = [mcphub-nvim];
  extraConfigLua = ''
    require("mcphub").setup({
        port = 3000,
        config = vim.fn.expand("~/mcp-hub/mcp-servers.json"),
        cmd = "${mcp-hub}/bin/mcp-hub"
    })
  '';
}

# where
{
  # For nixpkgs (not available yet)
  mcp-hub = pkgs.mcp-hub;

  # For flakes
  mcp-hub = inputs.mcp-hub.packages."${system}".default;
}

Exemplos de Integração

Integração com Neovim

O plugin ravitemer/mcphub.nvim fornece integração perfeita com Neovim, permitindo interação direta com o MCP Hub a partir do seu editor:

Execute ferramentas MCP diretamente do Neovim
Acesse recursos MCP dentro do seu fluxo de trabalho de edição
Atualizações de status em tempo real no Neovim
Instalação automática de servidores MCP com adição ao marketplace

API REST

Saúde e Status

Verificação de Saúde

GET /api/health

O endpoint de saúde fornece informações abrangentes de status incluindo:

Estado atual do hub (starting, ready, restarting, restarted, stopping, stopped, error)
Status e capacidades dos servidores conectados
Detalhes de conexões SSE ativas
Métricas detalhadas de conexão
Detalhes do estado de erro, se aplicável

Resposta:

{
  "status": "ok",
  "state": "ready",
  "server_id": "mcp-hub",
  "version": "4.1.1",
  "activeClients": 2,
  "timestamp": "2024-02-20T05:55:00.000Z",
  "servers": [],
  "connections": {
    "totalConnections": 2,
    "connections": [
      {
        "id": "client-uuid",
        "state": "connected",
        "connectedAt": "2024-02-20T05:50:00.000Z",
        "lastEventAt": "2024-02-20T05:55:00.000Z"
      }
    ]
  },
  "workspaces": {
    "current": "40123",
    "allActive": {
      "40123": {
        "cwd": "/path/to/project-a",
        "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
        "pid": 12345,
        "port": 40123,
        "startTime": "2025-01-17T10:00:00.000Z",
        "state": "active",
        "activeConnections": 2,
        "shutdownStartedAt": null,
        "shutdownDelay": null
      }
    }
  }
}

Listar Servidores MCP

GET /api/servers

Obter Informações do Servidor

POST /api/servers/info
Content-Type: application/json

{
  "server_name": "example-server"
}

Atualizar Capacidades do Servidor

POST /api/servers/refresh
Content-Type: application/json

{
  "server_name": "example-server"
}

Resposta:

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "capabilities": {
      "tools": ["tool1", "tool2"],
      "resources": ["resource1", "resource2"],
      "resourceTemplates": []
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Atualizar Todos os Servidores

POST /api/refresh

Resposta:

{
  "status": "ok",
  "servers": [
    {
      "name": "example-server",
      "capabilities": {
        "tools": ["tool1", "tool2"],
        "resources": ["resource1", "resource2"],
        "resourceTemplates": []
      }
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Iniciar Servidor

POST /api/servers/start
Content-Type: application/json

{
  "server_name": "example-server"
}

Resposta:

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "connected",
    "uptime": 123
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Parar Servidor

POST /api/servers/stop?disable=true|false
Content-Type: application/json

{
  "server_name": "example-server"
}

O parâmetro de consulta opcional disable pode ser definido como true para desabilitar o servidor na configuração.

Resposta:

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "disconnected",
    "uptime": 0
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Gerenciamento de Workspaces

Listar Workspaces Ativos

GET /api/workspaces

Resposta:

{
  "workspaces": {
    "40123": {
      "cwd": "/path/to/project-a",
      "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
      "pid": 12345,
      "port": 40123,
      "startTime": "2025-01-17T10:00:00.000Z",
      "state": "active",
      "activeConnections": 2,
      "shutdownStartedAt": null,
      "shutdownDelay": null
    },
    "40567": {
      "cwd": "/path/to/project-b",
      "config_files": ["/home/user/.config/mcphub/global.json"],
      "pid": 54321,
      "port": 40567,
      "startTime": "2025-01-17T10:05:00.000Z",
      "state": "shutting_down",
      "activeConnections": 0,
      "shutdownStartedAt": "2025-01-17T10:15:00.000Z",
      "shutdownDelay": 600000
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Integração com Marketplace

Listar Servidores Disponíveis

GET /api/marketplace

Parâmetros de Consulta:

search: Filtrar por nome, descrição ou tags
category: Filtrar por categoria
tags: Filtrar por tags separadas por vírgula
sort: Ordenar por "newest", "stars" ou "name"

Resposta:

{
  "servers": [
    {
      "id": "example-server",
      "name": "Example Server",
      "description": "Description here",
      "author": "example-author",
      "url": "https://github.com/user/repo",
      "category": "search",
      "tags": ["search", "ai"],
      "stars": 100,
      "featured": true,
      "verified": true,
      "lastCommit": 1751257963,
      "updatedAt": 1751265038
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Obter Detalhes do Servidor

POST /api/marketplace/details
Content-Type: application/json

{
  "mcpId": "example-server"
}

Resposta:

{
  "server": {
    "id": "example-server",
    "name": "Example Server",
    "description": "Description here",
    "author": "example-author",
    "url": "https://github.com/user/repo",
    "category": "search",
    "tags": ["search", "ai"],
    "installations": [],
    "stars": 100,
    "featured": true,
    "verified": true,
    "lastCommit": 1751257963,
    "updatedAt": 1751265038
  },
  "readmeContent": "# Server Documentation...",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Operações do Servidor MCP

Executar Ferramenta

POST /api/servers/tools
Content-Type: application/json

{
  "server_name": "example-server",
  "tool": "tool_name",
  "arguments": {},
  "request_options" : {}
}

Acessar Recurso

POST /api/servers/resources
Content-Type: application/json

{
  "server_name": "example-server",
  "uri": "resource://uri",
  "request_options" : {}
}

Obter Prompt

POST /api/servers/prompts
Content-Type: application/json

{
  "server_name": "example-server",
  "prompt": "prompt_name",
  "arguments": {},
  "request_options" : {}
}

Resposta:

{
  "result": {
    "messages": [
      {
        "role": "assistant",
        "content": {
          "type": "text",
          "text": "Text response example"
        }
      },
      {
        "role": "assistant",
        "content": {
          "type": "image",
          "data": "base64_encoded_image_data",
          "mimeType": "image/png"
        }
      }
    ]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Reiniciar o Hub

POST /api/restart

Recarrega o arquivo de configuração e reinicia todos os servidores MCP.

Resposta:

{
  "status": "ok",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Sistema de Eventos em Tempo Real

O MCP Hub implementa um sistema abrangente de eventos em tempo real usando Server-Sent Events (SSE) em /api/events. Este endpoint fornece atualizações ao vivo sobre status do servidor, mudanças de configuração, atualizações de capacidades e muito mais.

Estados do Hub

O servidor hub transita por vários estados durante seu ciclo de vida:

Estado	Descrição
`starting`	Inicialização inicial, carregando configuração
`ready`	Servidor em execução e pronto para lidar com solicitações
`restarting`	Recarregando configuração/reconectando servidores
`restarted`	Recarga de configuração concluída
`stopping`	Desligamento gracioso em andamento
`stopped`	Servidor totalmente parado
`error`	Estado de erro (inclui detalhes do erro)

Você pode monitorar esses estados através do endpoint /health ou eventos SSE.

Tipos de Eventos

O MCP Hub emite vários tipos de eventos:

Eventos Principais

heartbeat - Verificação periódica de saúde da conexão

{
  "connections": 2,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

hub_state - Mudanças de estado do servidor hub

{
  "state": "ready",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "pid": 12345,
  "port": 3000,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

log - Mensagens de log do servidor

{
  "type": "info",
  "message": "Server started",
  "data": {},
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Eventos de Assinatura

config_changed - Mudanças detectadas no arquivo de configuração

{
  "type": "config_changed",
  "newConfig": {},
  "isSignificant": true,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

servers_updating - Atualizações de servidores em andamento

{
  "type": "servers_updating",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

servers_updated - Atualizações de servidores concluídas

{
  "type": "servers_updated",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

tool_list_changed - Lista de ferramentas do servidor atualizada

{
  "type": "tool_list_changed",
  "server": "example-server",
  "tools": ["tool1", "tool2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

resource_list_changed - Recursos/modelos do servidor atualizados

{
  "type": "resource_list_changed",
  "server": "example-server",
  "resources": ["resource1", "resource2"],
  "resourceTemplates": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

prompt_list_changed - Lista de prompts do servidor atualizada

{
  "type": "prompt_list_changed",
  "server": "example-server",
  "prompts": ["prompt1", "prompt2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

workspaces_updated - Workspaces ativos alterados

{
  "type": "workspaces_updated",
  "workspaces": {
    "40123": {
      "cwd": "/path/to/project-a",
      "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
      "pid": 12345,
      "port": 40123,
      "startTime": "2025-01-17T10:00:00.000Z",
      "state": "active",
      "activeConnections": 2,
      "shutdownStartedAt": null,
      "shutdownDelay": null
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Gerenciamento de Conexões

Cada conexão SSE recebe um ID único
Conexões são limpas automaticamente ao desconectar o cliente
Estatísticas de conexão disponíveis via endpoint /health
Desligamento automático opcional quando não há clientes conectados

Registro de Logs

O MCP Hub usa logs JSON estruturados para todos os eventos. Os logs são gravados tanto no console quanto em arquivo, seguindo a Especificação de Diretório Base XDG:

Compatível com XDG: $XDG_STATE_HOME/mcp-hub/logs/mcp-hub.log (tipicamente ~/.local/state/mcp-hub/logs/mcp-hub.log)
Fallback legado: ~/.mcp-hub/logs/mcp-hub.log (para compatibilidade reversa)

Exemplo de entrada de log:

{
  "type": "error",
  "code": "TOOL_ERROR",
  "message": "Failed to execute tool",
  "data": {
    "server": "example-server",
    "tool": "example-tool",
    "error": "Invalid parameters"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Os níveis de log incluem:

info: Mensagens operacionais normais
warn: Condições de aviso
debug: Informações detalhadas de depuração (inclui mudanças de configuração)
error: Condições de erro (inclui código de erro e rastreamento de pilha)

Os logs são rotacionados diariamente e mantidos por 30 dias por padrão.

Cache de Workspaces

O MCP Hub mantém um cache global de workspaces para rastrear instâncias ativas em diferentes diretórios de trabalho com gerenciamento de ciclo de vida em tempo real:

Localização do Cache: $XDG_STATE_HOME/mcp-hub/workspaces.json (tipicamente ~/.local/state/mcp-hub/workspaces.json)
Propósito: Previne conflitos de porta, permite descoberta de workspaces e fornece rastreamento de ciclo de vida em tempo real
Conteúdo: Mapeia números de porta (como chaves) para informações do processo hub com estado detalhado do ciclo de vida
Limpeza: Remove automaticamente entradas obsoletas quando os processos não estão mais em execução

Estrutura do Cache

{
  "40123": {
    "cwd": "/path/to/project-a",
    "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
    "pid": 12345,
    "port": 40123,
    "startTime": "2025-01-17T10:00:00.000Z",
    "state": "active",
    "activeConnections": 2,
    "shutdownStartedAt": null,
    "shutdownDelay": null
  },
  "40567": {
    "cwd": "/path/to/project-b", 
    "config_files": ["/home/user/.config/mcphub/global.json"],
    "pid": 54321,
    "port": 40567,
    "startTime": "2025-01-17T10:05:00.000Z",
    "state": "shutting_down",
    "activeConnections": 0,
    "shutdownStartedAt": "2025-01-17T10:15:00.000Z",
    "shutdownDelay": 600000
  }
}

Tratamento de Erros

O MCP Hub implementa um sistema abrangente de tratamento de erros com classes de erro personalizadas para diferentes tipos de erros:

Classes de Erro

ConfigError: Erros relacionados à configuração (config inválida, campos ausentes)
ConnectionError: Problemas de conexão do servidor (conexões falhas, erros de transporte)
ServerError: Problemas de inicialização/inicialização do servidor
ToolError: Falhas na execução de ferramentas
ResourceError: Problemas de acesso a recursos
ValidationError: Erros de validação de solicitações

Cada erro inclui:

Código de erro para fácil identificação
Mensagem de erro detalhada
Contexto adicional no objeto de detalhes
Rastreamento de pilha para depuração

Exemplo de estrutura de erro:

{
  "code": "CONNECTION_ERROR",
  "message": "Failed to communicate with server",
  "details": {
    "server": "example-server",
    "error": "connection timeout"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Arquitetura

Ciclo de Vida do Servidor Hub

sequenceDiagram
    participant C as Client
    participant H as Hub Server
    participant M1 as MCP Server 1
    participant M2 as MCP Server 2

    Note over H: Server Start (state: starting)
    activate H
    
    Note over H: Config Loading
    H->>H: Load & Validate Config
    H->>H: Watch Config File
    H->>H: Initialize SSE Manager
    
    Note over H: Server Connections (state: ready)
    H->>+M1: Connect
    M1-->>-H: Connected + Capabilities
    H->>+M2: Connect
    M2-->>-H: Connected + Capabilities
    H-->>C: hub_state (ready)

    Note over C,H: Client Setup
    C->>H: Connect to /api/events (SSE)
    H-->>C: connection_opened
    
    Note over C,H: Client Operations
    C->>H: Execute Tool (HTTP)
    H->>M1: Execute Tool
    M1-->>H: Tool Result
    H-->>C: HTTP Response
    
    Note over H,C: Real-time Updates
    H->>H: Detect Config Change
    H-->>C: servers_updating (SSE)
    H->>M1: Reconnect with New Config
    M1-->>H: Updated Capabilities
    H-->>C: servers_updated (SSE)

    Note over H,C: Server Events
    M2->>H: Tool List Changed
    H-->>C: tool_list_changed (SSE)
    
    Note over H: Shutdown Process
    Note over C,H: Client Disconnects
    H-->>C: hub_state (stopping) (SSE)
    H->>M1: Disconnect
    H->>M2: Disconnect
    H-->>C: hub_state (stopped) (SSE)
    deactivate H

O Servidor Hub coordena a comunicação entre clientes e servidores MCP:

Inicia e conecta aos servidores MCP configurados
Gerencia conexões SSE de clientes e eventos
Roteia solicitações de ferramentas e recursos para os servidores apropriados
Monitora a saúde do servidor e mantém capacidades
Gerencia processos graciosos de inicialização/desligamento

Gerenciamento de Servidores MCP

flowchart TB
    A[Hub Server Start] --> B{Config Available?}
    B -->|Yes| C[Load Server Configs]
    B -->|No| D[Use Default Settings]
    
    C --> E[Initialize Connections]
    D --> E
    
    E --> F{For Each MCP Server}
    F -->|Enabled| G[Attempt Connection]
    F -->|Disabled| H[Skip Server]
    
    G --> I{Connection Status}
    I -->|Success| J[Fetch Capabilities]
    I -->|Failure| K[Log Error]
    
    J --> L[Store Server Info]
    K --> M[Mark Server Unavailable]
    
    L --> N[Monitor Health]
    M --> N
    
    N --> O{Health Check}
    O -->|Healthy| P[Update Capabilities]
    O -->|Unhealthy| Q[Attempt Reconnect]
    
    Q -->|Success| P
    Q -->|Failure| R[Update Status]
    
    P --> N
    R --> N

O Servidor Hub gerencia ativamente os servidores MCP através de:

Inicialização de servidores baseada em configuração
Descoberta de conexão e capacidades
Monitoramento de saúde e rastreamento de status
Tentativas automáticas de reconexão
Gerenciamento de estado do servidor

Tratamento de Solicitações

sequenceDiagram
    participant C as Client
    participant H as Hub Server
    participant M as MCP Server
    
    Note over C,H: Tool Execution
    C->>H: POST /api/servers/tools (HTTP)
    H->>H: Validate Request & Server
    
    alt Server Not Connected
        H-->>C: 503 Server Unavailable (HTTP)
    else Server Connected
        H->>M: Execute Tool
        
        alt Success
            M-->>H: Tool Result
            H-->>C: Result Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Resource Access
    C->>H: POST /api/servers/resources (HTTP)
    H->>H: Validate URI & Template
    
    alt Invalid Resource
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Request Resource
        
        alt Success
            M-->>H: Resource Data
            H-->>C: Resource Content (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Prompt Execution
    C->>H: POST /api/servers/prompts (HTTP)
    H->>H: Validate Prompt & Args
    
    alt Invalid Prompt
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Execute Prompt
        
        alt Success
            M-->>H: Messages Array
            H-->>C: Messages Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end

Todas as solicitações de clientes seguem um fluxo padronizado:

Validação da solicitação
Verificação do status do servidor
Roteamento da solicitação para o servidor MCP apropriado
Tratamento de resposta e gerenciamento de erros

Requisitos

Node.js >= 18.0.0

Registro MCP

O MCP Hub agora usa o sistema MCP Registry para funcionalidade de marketplace. Isso fornece:

Descoberta Descentralizada de Servidores: Registro hospedado no GitHub Pages para maior confiabilidade
Integração Direta com GitHub: Documentação README buscada diretamente dos repositórios
Metadados Aprimorados: Informações abrangentes do servidor incluindo estrelas, categorias e instruções de instalação
Melhor Cache: Sistema de cache aprimorado com TTL de 1 hora para atualizações frequentes
Suporte a Fallback: Fallback automático para curl quando fetch falha (útil para ambientes com proxy/VPN)

O registro é atualizado regularmente com novos servidores e melhorias nas entradas existentes.

Todo

Implementar marketplace personalizado em vez de depender do mcp-marketplace
TUI como mcphub.nvim
Interface web para gerenciar servidores

Agradecimentos

ravitemer/mcp-registry - Por fornecer os endpoints do marketplace de servidores MCP que alimentam a integração de marketplace do MCP Hub

MCP Hub

Documentação

MCP Hub

Suporte a Recursos

Configuração Simplificada do Cliente

Recursos Principais

Componentes

Servidor Hub

Servidores MCP

Instalação

Uso Básico

Opções de CLI

Configuração

Compatibilidade de Configuração com VS Code

Recursos Suportados

Chaves de Configuração do Servidor

Substituição de Variáveis

Variáveis de Entrada do VS Code

Migração do VS Code

Múltiplos Arquivos de Configuração

Sintaxe Universal de Placeholder

Exemplos de Configuração

Servidor STDIO Local

Servidor Remoto

Opções de Configuração

Opções de Servidor STDIO

Variáveis de Ambiente Globais (MCP_HUB_ENV)

Opções de Servidor Remoto

Detecção de Tipo de Servidor

Ordem de Resolução de Placeholders

Nix

Instalação via Nixpkgs

Instalação via Flake

Uso sem instalação

Exemplos de Integração

Integração com Neovim

API REST

Saúde e Status

Verificação de Saúde

Listar Servidores MCP

Obter Informações do Servidor

Atualizar Capacidades do Servidor

Atualizar Todos os Servidores

Iniciar Servidor

Parar Servidor

Gerenciamento de Workspaces

Listar Workspaces Ativos

Integração com Marketplace

Listar Servidores Disponíveis

Obter Detalhes do Servidor

Operações do Servidor MCP

Executar Ferramenta

Acessar Recurso

Obter Prompt

Reiniciar o Hub

Sistema de Eventos em Tempo Real

Estados do Hub

Tipos de Eventos

Eventos Principais

Eventos de Assinatura

Gerenciamento de Conexões

Registro de Logs

Cache de Workspaces

Estrutura do Cache

Tratamento de Erros

Classes de Erro

Arquitetura

Ciclo de Vida do Servidor Hub

Gerenciamento de Servidores MCP

Tratamento de Solicitações

Requisitos

Registro MCP

Todo

Agradecimentos

Variáveis de Ambiente Globais (`MCP_HUB_ENV`)