Huly

Huly MCP

Huly MCP é um servidor MCP completo para integração com Huly. Publicado no npm como @firfi/huly-mcp.

[!IMPORTANT] O Huly hospedado está sendo descontinuado. O README upstream do Huly indica que o encerramento está previsto para 20 de julho. Se você usa https://huly.app, exporte e migre seus dados o mais rápido possível. Consulte o guia de backup e restauração e o repositório de auto-hospedagem. Implantações auto-hospedadas não são afetadas.

Alternativa ao Huly CLI

Procurando uma CLI do Huly, integração nativa de terminal com o Huly, ou uma alternativa de script e automação para executar um servidor MCP? O Huly CLI é uma interface de linha de comando completa para o Huly, publicada como @firfi/huly-cli, com paridade total de operações do Huly com o Huly MCP. Ele expõe as mesmas operações do Huly como comandos nativos e cientes de esquema, com saída legível por humanos ou JSON, entradas baseadas em arquivos, uploads e downloads.

O Huly MCP e o Huly CLI são mantidos juntos neste monorepo e derivam do mesmo registro de operações compartilhado, mantendo entradas, saídas, avisos e falhas tipadas alinhados. Consulte a documentação do Huly CLI para a referência completa de comandos gerados, ou explore exemplos de CLI, padrões de automação do Huly e a comparação entre Huly MCP e CLI.

Instalação

Requer Node.js 22.19.0 ou posterior.

A configuração padrão funciona com a maioria dos clientes MCP:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Padrões de Exposição de Ferramentas

Por padrão (HULY_TOOL_MODE=auto), o Huly MCP otimiza para clientes MCP atuais evitando uma lista eager de 470 ferramentas. Sessões exatas de claude-code recebem ferramentas nativas do Huly. Clientes Codex, Cursor, Windsurf, Copilot, OpenCode, Claude AI/Desktop e clientes desconhecidos recebem uma superfície de proxy pequena: list_tool_categories, search_tools, get_tool_schema e invoke_tool.

Nomes exatos de ferramentas nativas ainda são despachados quando um cliente os chama diretamente, mas muitos clientes só chamam ferramentas retornadas por tools/list. Defina HULY_TOOL_MODE=native para fazer com que todas as ferramentas do Huly apareçam como primeira classe, ou use TOOLSETS / TOOLS para fixar ferramentas nativas usadas com frequência enquanto mantém a descoberta por proxy disponível.

codex mcp add huly \
  --env HULY_URL=https://your-huly-instance.example.com \
  --env HULY_EMAIL=your@email.com \
  --env HULY_PASSWORD=yourpassword \
  --env HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest

[mcp_servers.huly]
command = "npx"
args = ["-y", "@firfi/huly-mcp@latest"]

[mcp_servers.huly.env]
HULY_URL = "https://your-huly-instance.example.com"
HULY_EMAIL = "your@email.com"
HULY_PASSWORD = "yourpassword"
HULY_WORKSPACE = "yourworkspace"

claude mcp add huly \
  -e HULY_URL=https://your-huly-instance.example.com \
  -e HULY_EMAIL=your@email.com \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest

{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

{
  "mcp": {
    "huly": {
      "type": "local",
      "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

pi install npm:pi-mcp-adapter

Atualização

A tag @latest pede ao executor de pacotes a versão mais recente. Alguns clientes MCP mantêm processos de servidor ou instalações resolvidas ativos, então reinicie ou re-adicione o servidor ao atualizar:

Transporte HTTP

Por padrão, o servidor usa transporte stdio. Para transporte HTTP:

HULY_URL=https://your-huly-instance.example.com \
HULY_EMAIL=your@email.com \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @firfi/huly-mcp@latest

O servidor escuta em http://127.0.0.1:3000/mcp por padrão.

Configure com MCP_HTTP_PORT e MCP_HTTP_HOST:

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-mcp@latest

Suporte ao Protocolo MCP HTTP

Tanto stdio quanto HTTP implementam a interface MCP 2026-07-28 lançada e mantêm compatibilidade de propriedade do SDK para clientes MCP 2025-06-18. O stdio fixa cada conexão à era do protocolo selecionada pela sua troca de abertura; o HTTP atende solicitações legadas sem estado. HTTP moderno requer uma mensagem JSON-RPC por POST, Accept: application/json, text/event-stream, MCP-Protocol-Version: 2026-07-28, Mcp-Method, Mcp-Name específico do método e metadados de cliente _meta.io.modelcontextprotocol/* por solicitação. As credenciais do Huly são configuradas separadamente por meio de variáveis de ambiente ou cabeçalhos x-huly-* suportados.

Para implantações HTTP hospedadas ou em túnel, você pode exigir um token de portador do endpoint MCP:

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
npx -y @firfi/huly-mcp@latest

Os clientes HTTP devem então enviar:

Authorization: Bearer <MCP_AUTH_TOKEN>

MCP_AUTH_TOKEN protege apenas o endpoint MCP HTTP /mcp. Não está relacionado ao HULY_TOKEN, não autentica no Huly e não substitui HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN. As credenciais do Huly ainda são necessárias por meio de variáveis de ambiente do processo ou, para implantações de URL hospedadas, os cabeçalhos x-huly-* suportados. Implantações stdio não usam MCP_AUTH_TOKEN.

Configuração de Cabeçalhos HTTP Hospedados

Para implantações de URL hospedadas, mantenha o processo do servidor configurado com MCP_TRANSPORT=http. Uma camada de hospedagem pode encaminhar credenciais do Huly por sessão como cabeçalhos de solicitação, para que um servidor hospedado possa atender diferentes workspaces do Huly sem variáveis de ambiente HULY_* em todo o processo.

Cabeçalhos v1 suportados:

Se qualquer cabeçalho x-huly-* estiver presente, todos os cabeçalhos obrigatórios devem estar presentes. Valores ausentes não são preenchidos a partir de variáveis de ambiente. Autenticação por e-mail/senha não é suportada na configuração de cabeçalhos hospedados v1.

Para um exemplo de esquema de publicação Smithery, consulte docs/SMITHERY_URL_PUBLISH.md.

Variáveis de Ambiente

*Auth: Forneça HULY_EMAIL + HULY_PASSWORD ou HULY_TOKEN.

Ferramentas de Diagnóstico Integradas

get_version retorna a versão atual do servidor e a versão mais recente do npm.

get_huly_context retorna contexto de runtime/configuração sanitizado para a sessão MCP atual sem conectar ao Huly. Ele informa versão do pacote, transporte, modo de autenticação, origem/host/protocolo da URL Huly sanitizada, workspace, tempo limite, fontes de configuração, filtragem de escopo de ferramentas nativas e exposição resolvida de ferramentas nativas/proxy. Tokens, senhas, valores de e-mail, cabeçalhos de credenciais, caminhos de URL, strings de consulta de URL e credenciais de URL nunca são retornados.

Recursos MCP

O servidor expõe Recursos MCP somente leitura como contexto JSON para clientes que suportam resources/read.

resources/list retorna recursos de projeto ativos concretos. Recursos de issue são baseados em modelo: use resources/templates/list para descobrir modelos de URI de issue suportados e depois leia uma URI de issue conhecida.

Backlog

Notas de backlog de funcionalidades e paridade com SDK estão em docs/BACKLOG.md.

Ferramentas Disponíveis

Quando a exposição de ferramentas resolvida é proxy, os clientes veem as ferramentas integradas mais estas meta-ferramentas de proxy. As ferramentas nativas do Huly são então descobertas e invocadas por meio do catálogo de candidatos a proxy. Nomes exatos de ferramentas nativas também são despachados quando um cliente os chama diretamente, sujeitos às regras de escopo PROXY_OUTPUT_STRICT, mas ferramentas nativas ocultas não são anunciadas por meio de tools/list.

Meta-Ferramentas de Proxy

TOOLSETS categorias: projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, associations, activity, notifications, workspace, approvals, boards, cards, collaborators, custom-fields, drive, inventory, labels, leads, mail, templates, model-administration, planner, preferences, processes, recruiting, sdk-discovery, security-administration, sequence-administration, spaces, support, tag-categories, tags, task-management, test-management, user-statuses, views, virtual-office, workbench, workflow-statuses

Projetos

Issues

Comentários

Marcos

Documentos

Armazenamento

Anexos

Contatos

Canais

Calendário

Controle de Tempo

Pesquisa

Associações

Atividade

Notificações

Workspace

Approvals

Boards

Cards

Collaborators

Campos Personalizados

Drive

Inventário

Rótulos

Leads

E-mail

Modelos

Model-Administration

Planejador

Preferências

Processos

Recrutamento

Sdk-Discovery

Administração de Segurança

Administração de Sequências

Espaços

Suporte

Categorias de Tags

Tags

Gerenciamento de Tarefas

Gerenciamento de Testes

Status de Usuários

Visualizações

Escritório Virtual

Workbench

Status de Workflow

Solução de Problemas

Senhas com caracteres especiais

Se a sua senha do Huly contiver caracteres como *, %, ! ou #, passá-la via flags de ambiente da CLI como -e ou --env pode falhar porque o shell interpreta esses caracteres antes que eles cheguem ao processo.

Solução: Edite o arquivo de configuração do MCP diretamente em vez de passar a senha pelo shell:

• Codex: ~/.codex/config.toml
• Claude Code: ~/.claude.json (escopo do usuário) ou .mcp.json (escopo do projeto)
• Claude Desktop: claude_desktop_config.json no local listado na seção de instalação
• VS Code e Cursor: use o local de configuração do cliente da seção de instalação; evite commitar arquivos do workspace que contenham credenciais reais
• Windsurf: edite o arquivo de configuração MCP do Windsurf diretamente
• OpenCode: ~/.config/opencode/opencode.json

Para a configuração JSON do Claude, os caracteres sensíveis ao shell acima podem ser escritos diretamente. Caracteres reservados do JSON, como " e \, ainda precisam de escape JSON normal:

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://your-huly-instance.com",
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "p@ss*w0rd!#%",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

Alternativamente, use HULY_TOKEN em vez de e-mail/senha para ignorar a autenticação por senha completamente (veja Variáveis de Ambiente).

Cliente MCP mostra "Falha ao reconectar"

Após alterar a configuração do MCP, alguns clientes (incluindo Claude Code) exigem uma reinicialização completa — não apenas uma reconexão. Saia completamente do aplicativo e reabra-o.

Você pode verificar se a conexão funciona de forma independente com:

claude mcp list  # Should show "Connected"

Huly auto-hospedado: conta bloqueada após tentativas de login falhas

O Huly bloqueia o login por senha após 5 tentativas de autenticação de API falhas. Isso geralmente acontece durante a configuração inicial quando a senha está mal configurada. O bloqueio persiste no banco de dados entre reinicializações do serviço.

Sintomas: erro PasswordLoginLocked do servidor MCP, e a interface web do Huly mostra "O login por senha está bloqueado devido a muitas tentativas falhas. Use um método de login OTP para desbloquear sua conta." (OTP não funcionará sem SMTP configurado.)

Correção — redefina o contador de bloqueio no CockroachDB:

# Find your account UUID and check lock status
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "SELECT uuid, failed_login_attempts FROM global_account.account;"

# Reset the counter
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "UPDATE global_account.account SET failed_login_attempts = 0 WHERE uuid = '<your_account_uuid>';"

As credenciais do CockroachDB podem ser encontradas no seu Huly compose.yml ou via docker exec <cockroach_container> env | grep COCKROACH.

Notas específicas para Windows

• Scripts de wrapper Bash (sourcing de arquivos .env) podem não funcionar de forma confiável quando iniciados por clientes MCP no Windows. Prefira definir variáveis de ambiente diretamente no JSON de configuração do MCP.
• Pulls do Docker via SSH podem falhar no Windows devido a problemas no gerenciador de credenciais. Baixe as imagens do desktop do servidor, se necessário.