Huly

Huly MCP

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

Ele se conecta a implantações da Plataforma Huly e também deve funcionar com os forks Platform Collective e TraceX. Intabia 0.8.33 / modelo 0.8.4 foi testado quanto à compatibilidade; lacunas conhecidas são rastreadas na issue #279. O suporte a forks permanece não oficial.

Alternativa ao Huly CLI

Procurando por um Huly CLI, integração Huly nativa de terminal ou uma alternativa de script e automação para executar um servidor MCP? O Huly CLI é uma interface de linha de comando completa para Huly, publicada como @firfi/huly-cli, com paridade total de operações Huly com o Huly MCP. Ele expõe as mesmas operações 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 das operações alinhados. Consulte a documentação do Huly CLI para a referência completa de comandos gerada, ou navegue pelos exemplos de CLI, padrões de automação Huly e a comparação Huly MCP vs CLI.

Instalação

Requisito do Node.js

O Huly MCP requer Node.js 22.19.0 ou posterior. Os clientes MCP não fornecem um runtime Node.js: node, npx, e o executável do pacote #!/usr/bin/env node resolvem o Node.js a partir do ambiente no qual o cliente MCP é executado. Verifique esse ambiente antes da instalação:

node --version

Se um cliente MCP iniciar o Huly MCP com um runtime mais antigo, o Huly MCP inicializa uma superfície MCP somente de diagnóstico em vez de carregar o aplicativo incompatível. Suas instruções de servidor e a ferramenta get_huly_startup_diagnostic relatam o executável detectado e a versão necessária, e o mesmo diagnóstico unsupported Node.js runtime é gravado no stderr. Atualize o Node.js ou configure o comando do servidor MCP para usar o caminho absoluto de um executável Node.js compatível e reinicie o servidor MCP. As operações Huly permanecem indisponíveis até que o runtime seja atualizado.

A configuração padrão usa um token de API Huly e 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_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Prefira um token de API gerenciado criado nas configurações da conta Huly quando a implantação de destino for compatível. Tokens gerenciados são vinculados a um workspace, recebem uma expiração e podem ser revogados sem alterar a senha da conta. Eles ainda herdam os direitos completos da conta nesse workspace, portanto, use uma conta de integração dedicada com apenas a função do workspace, as associações de espaço e o acesso a dados que a automação precisa. Implantações Huly mais antigas podem não expor configurações de token gerenciado; a autenticação por e-mail/senha permanece disponível como fallback de compatibilidade.

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 ansiosa de 470 ferramentas. Sessões exatas de claude-code recebem ferramentas Huly nativas. Codex, Cursor, Windsurf, Copilot, OpenCode, clientes estilo Claude AI/Desktop e clientes desconhecidos recebem uma pequena superfície de proxy: 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 cada ferramenta Huly aparecer como primeira classe, ou use TOOLSETS / TOOLS para fixar ferramentas nativas usadas com frequência enquanto mantém a descoberta de proxy disponível.

codex mcp add huly \
  --env HULY_URL=https://your-huly-instance.example.com \
  --env HULY_TOKEN=your-huly-api-token \
  --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_TOKEN = "your-huly-api-token"
HULY_WORKSPACE = "yourworkspace"

claude mcp add huly \
  -e HULY_URL=https://your-huly-instance.example.com \
  -e HULY_TOKEN=your-huly-api-token \
  -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_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

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

pi install npm:pi-mcp-adapter

Atualização

A tag @latest pede ao executor do pacote 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:

Lançamento de Produção do Mantenedor

Publique a partir de um checkout master limpo e atual com o runtime Node.js certificado preferido:

mise exec node@24.15.0 -- pnpm local-release

Use este comando exato mesmo quando uma versão mais recente do Node.js estiver ativa no host. O build de lançamento aceita apenas as versões exatas do Node.js certificadas pelo CI; isso é intencionalmente mais restrito do que o requisito de runtime do pacote. Consulte o guia de lançamento de produção para verificações de pré-lançamento, comportamento de reexecução e verificação.

Transporte HTTP

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

HULY_URL=https://your-huly-instance.example.com \
HULY_TOKEN=your-huly-api-token \
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

Ambos os transportes são implementados com o servidor MCP e adaptadores de protocolo do Effect AI. O servidor configura o protocolo sem estado MCP 2026-07-28 lançado e o protocolo de compatibilidade MCP 2025-06-18. HTTP moderno requer uma mensagem JSON-RPC por POST, Accept: application/json, text/event-stream, MCP-Protocol-Version: 2026-07-28, Mcp-Method, metadados de cliente Mcp-Name específicos do método e _meta.io.modelcontextprotocol/* por solicitação. HTTP legado suporta sessões inicializadas usando o Mcp-Session-Id retornado e chamadas sem estado nuas com bindings locais à solicitação. As credenciais Huly são configuradas separadamente por meio de variáveis de ambiente ou cabeçalhos x-huly-* suportados.

Consulte arquitetura e certificação de transporte MCP para o limite de implementação e o registro de verificação atual.

Para implantações HTTP hospedadas ou em túnel, você pode exigir um token de portador de 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 a HULY_TOKEN, não autentica no Huly e não substitui HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN. As credenciais 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.

Perfis compartilhados de CLI e stdio

Salve um perfil com huly auth login --profile work e depois defina HULY_PROFILE=work no ambiente do servidor MCP stdio. Ambos os processos devem ser executados sob o mesmo usuário do SO e diretório de configuração. O stdio nunca segue o perfil CLI ativo implicitamente. Tokens salvos são vinculados à sua URL de instância e workspace; alterações exigem login novamente ou injeção completa de credenciais de ambiente. Consulte as instruções de perfil CLI. A configuração HTTP permanece inalterada.

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 Huly por sessão como cabeçalhos de solicitação, para que um servidor hospedado possa atender diferentes workspaces Huly sem variáveis de ambiente HULY_* em todo o processo.

Cabeçalhos v1 suportados:

Se qualquer cabeçalho x-huly-* suportado estiver presente, todos os cabeçalhos obrigatórios devem estar presentes e cabeçalhos x-huly-* não suportados são rejeitados. Solicitações com apenas cabeçalhos x-huly-* não suportados (por exemplo, um ID de rastreamento de proxy) usam a configuração de ambiente do processo. 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çalho hospedado v1.

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

Variáveis de Ambiente

*Auth: Prefira HULY_TOKEN. Use HULY_EMAIL + HULY_PASSWORD somente quando a implantação Huly não suportar um token de API gerenciado ou outra restrição de compatibilidade exigir autenticação por senha.

Ferramentas de Diagnóstico Integradas

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

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 problema são baseados em modelo: use resources/templates/list para descobrir modelos de URI de problema suportados e, em seguida, leia um URI de problema conhecido.

Backlog

Notas de backlog de recursos e paridade de 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. Ferramentas nativas Huly são então descobertas e invocadas através do catálogo de candidatos a proxy. Nomes exatos de ferramentas nativas também são despachados quando um cliente as chama diretamente, sujeitos às regras de escopo PROXY_OUTPUT_STRICT, mas ferramentas nativas ocultas não são anunciadas através de tools/list.

Meta-Ferramentas de Proxy

Categorias TOOLSETS: projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, associations, activity, notifications, workspace, approvals, boards, cards, collaborators, custom-fields, drive, hr, 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

Problemas

Comentários

Marcos

Documentos

Armazenamento

Anexos

Contatos

Canais

Calendário

Controle de Tempo

Busca

Associações

Atividade

Notificações

Workspace

Aprovações

Quadros

Cartões

Colaboradores

Campos-Personalizados

Drive

Hr

Inventário

Rótulos

Leads

Mail

Templates

Model-Administration

Planner

Preferências

Processos

Recrutamento

Sdk-Discovery

Security-Administration

Sequence-Administration

Spaces

Support

Tag-Categories

Tags

Gerenciamento de Tarefas

Gerenciamento de Testes

Status de Usuário

Visualizações

Escritório Virtual

Workbench

Workflow-Statuses

Solução de problemas

Fallback de senha com caracteres especiais

Se sua senha Huly contiver caracteres como *, %, ! ou #, passá-la via sinalizadores de ambiente CLI como -e ou --env pode falhar porque o shell interpreta esses caracteres antes de chegarem ao processo.

Solução: Edite seu arquivo de configuração 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 de espaço de trabalho que contenham credenciais reais
• Windsurf: edite seu arquivo de configuração MCP do Windsurf diretamente
• OpenCode: ~/.config/opencode/opencode.json

Para configuração JSON do Claude, os caracteres sensíveis ao shell acima podem ser escritos diretamente. Caracteres reservados em 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"
      }
    }
  }
}

Prefira HULY_TOKEN em vez deste fallback de senha quando a implantação suportar tokens de API gerenciados (veja Variáveis de Ambiente).

Cliente MCP mostra "Falha ao reconectar"

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

Você pode verificar se a conexão funciona independentemente 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 acontece comumente 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 "Password login is locked due to too many failed attempts. Please use an OTP login method to unlock your account." (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 compose.yml Huly ou via docker exec <cockroach_container> env | grep COCKROACH.

Notas específicas para Windows

• Scripts de wrapper Bash (originando 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 MCP.
• Pulls do Docker via SSH podem falhar no Windows devido a problemas no gerenciador de credenciais. Puxe imagens do servidor desktop, se necessário.