Huly MCP

Huly MCP

Huly MCP 是一款功能完备的 MCP 服务，可集成 Huly。该服务已发布至 npm，包名为 @firfi/huly-mcp。

它可连接到 Huly Platform 部署，也应兼容 Platform Collective 和 TraceX 分支。Intabia 0.8.33 / 模型 0.8.4 已通过兼容性测试；已知差异记录在 issue #279 中。对这些分支的支持仍属非官方支持。

Huly CLI 替代方案

正在寻找 Huly CLI、适用于终端的 Huly 集成，或可替代运行 MCP 服务的脚本编写与自动化方案？Huly CLI 是功能完备的 Huly 命令行界面，以 @firfi/huly-cli 为包名发布，其 Huly 操作能力与 Huly MCP 完全一致。它将相同的 Huly 操作作为原生、具备架构感知能力的命令提供，并支持人类可读或 JSON 格式的输出、基于文件的输入、上传和下载。

Huly MCP 和 Huly CLI 在同一个 monorepo 中共同维护，并基于同一共享操作注册表构建，因此操作输入、输出、警告和类型化错误保持一致。完整生成的命令参考请参阅 Huly CLI 文档，也可以浏览 CLI 示例、Huly 自动化模式和 Huly MCP 与 CLI 对比。

安装

Node.js 要求

Huly MCP 要求 Node.js 22.19.0 或更高版本。MCP 客户端不提供 Node.js 运行时：node、npx 以及 #!/usr/bin/env node 包可执行文件会从 MCP 客户端运行所在的环境中解析 Node.js。安装前请检查该环境：

node --version

如果 MCP 客户端使用较旧的运行时启动 Huly MCP，Huly MCP 会初始化仅用于诊断的 MCP 界面，而不会加载不兼容的应用程序。其服务说明和 get_huly_startup_diagnostic 工具会报告检测到的可执行文件和所需版本，并将相同的 unsupported Node.js runtime 诊断信息写入 stderr。请升级 Node.js，或将 MCP 服务命令配置为使用兼容的 Node.js 可执行文件的绝对路径，然后重启 MCP 服务。升级运行时前，Huly 操作仍不可用。

标准配置使用 Huly API 令牌，适用于大多数 MCP 客户端：

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "MCP_TRANSPORT": "stdio-resident",
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

如果目标部署支持，请优先使用在 Huly 账户设置中创建的托管 API 令牌。托管令牌仅绑定到一个工作区、设有到期时间，并且可以撤销，而无需更改账户密码。不过，它们仍继承账户在该工作区中的全部权限，因此请使用专用集成账户，并仅授予自动化所需的工作区角色、空间成员资格和数据访问权限。较旧的 Huly 部署可能不提供托管令牌设置；电子邮件/密码身份验证仍可作为兼容性回退方案。

工具暴露默认设置

默认情况下（HULY_TOOL_MODE=auto），Huly MCP 会避免一次性列出 470 个工具，以优化对当前 MCP 客户端的支持。精确匹配的 claude-code 会话会收到原生 Huly 工具。Codex、Cursor、Windsurf、Copilot、OpenCode、Claude AI/Desktop 风格的客户端以及未知客户端会收到一组精简的代理工具：list_tool_categories、search_tools、get_tool_schema 和 invoke_tool。

客户端直接调用时，精确匹配的原生工具名称仍会被分派，但许多客户端只会调用 tools/list 返回的工具。将 HULY_TOOL_MODE=native 设为让所有 Huly 工具都以一等工具的形式显示；或者使用 TOOLSETS / TOOLS 固定常用的原生工具，同时保留代理发现功能。

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

[mcp_servers.huly.env]
MCP_TRANSPORT = "stdio-resident"
HULY_URL = "https://your-huly-instance.example.com"
HULY_TOKEN = "your-huly-api-token"
HULY_WORKSPACE = "yourworkspace"

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

pi install npm:pi-mcp-adapter

更新

@latest 标签会让包运行器获取最新版本。某些 MCP 客户端会持续运行服务进程或保留已解析的安装，因此更新时请重启或重新添加服务：

维护者生产版本发布

使用干净且最新的 master 检出，并采用首选的、经过认证的 Node.js 运行时进行发布：

mise exec [email protected] -- pnpm local-release

即使主机上已启用更新版本的 Node.js，也请使用此准确命令。发布构建仅接受 CI 认证过的确切 Node.js 版本；这一范围有意比软件包的运行时要求更窄。有关发布前检查、重新运行行为和验证，请参阅生产版本发布指南。

共享常驻 stdio

设置示例会明确选择 MCP_TRANSPORT=stdio-resident。MCP 客户端仍使用 stdio，而同一操作系统用户下兼容的客户端会通过轻量级原生桥接共享一个 Node 后端。随附 Linux 和 macOS arm64/x64 二进制文件；无需安装 Rust。应用请求会在 30 秒的常驻启动时限内保持缓冲。启动失败时会启动普通 stdio，并分发一次已缓冲的应用输入。运行中的常驻服务一旦失败，便不会重新连接或重放应用请求。

省略 MCP_TRANSPORT 仍会选择普通 stdio，以保留现有安装的行为。显式设置 MCP_TRANSPORT=stdio，可让每个客户端使用独立后端。更改设置后，请重启 MCP 客户端。

手动常驻后端

实验性的手动常驻后端路径允许独立的 stdio 主机通过私有附加文件，明确选择一个已启动的本地后端。完整认证仍待完成。

HTTP 传输

服务器默认使用 stdio 传输。如需使用 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

服务器默认监听 http://127.0.0.1:3000/mcp。

使用 MCP_HTTP_PORT 和 MCP_HTTP_HOST 进行配置：

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

HTTP MCP 协议支持

两种传输方式均使用 Effect AI 的 MCP 服务和协议适配器实现。服务器配置了已发布的 MCP 2026-07-28 无状态协议以及 MCP 2025-06-18 兼容协议。现代 HTTP 要求每个 POST 只包含一条 JSON-RPC 消息，包含 Accept: application/json, text/event-stream、MCP-Protocol-Version: 2026-07-28、Mcp-Method、特定于方法的 Mcp-Name，以及每个请求的 _meta.io.modelcontextprotocol/* 客户端元数据。旧版 HTTP 支持使用返回的 Mcp-Session-Id 的已初始化会话，也支持使用请求本地绑定的无状态直接调用。Huly 凭据通过环境变量或受支持的 x-huly-* 标头单独配置。

有关实现边界和当前验证记录，请参阅 MCP 传输架构与认证。

对于托管或经隧道传输的 HTTP 部署，可以要求 MCP 端点使用 bearer 令牌：

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

此时，HTTP 客户端必须发送：

Authorization: Bearer <MCP_AUTH_TOKEN>

MCP_AUTH_TOKEN 仅保护 MCP HTTP /mcp 端点。它与 HULY_TOKEN 无关，不用于向 Huly 进行身份验证，也不能替代 HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN。仍须通过进程环境变量提供 Huly 凭据；对于托管 URL 部署，也可使用受支持的 x-huly-* 标头。stdio 部署不使用 MCP_AUTH_TOKEN。

共享 CLI 和 stdio 配置档案

使用 huly auth login --profile work 保存配置档案，然后在 stdio MCP 服务的环境中设置 MCP_TRANSPORT=stdio-resident 和 HULY_PROFILE=work。两个进程必须以同一操作系统用户身份运行，并使用同一配置目录。stdio 不会隐式沿用当前 CLI 配置档案。保存的令牌与其实例 URL 和工作区绑定；如有更改，必须重新登录或完整注入环境凭据。请参阅 CLI 配置档案说明。HTTP 配置保持不变。

托管 HTTP 标头配置

对于托管 URL 部署，请将服务进程配置为使用 MCP_TRANSPORT=http。托管层可以通过请求标头转发每个会话的 Huly 凭据，因此一个托管服务无需设置进程级 HULY_* 环境变量，即可为不同的 Huly 工作区提供服务。

支持的 v1 标头：

如果存在任何受支持的 x-huly-* 标头，则必须提供所有必需标头，并且不支持的 x-huly-* 标头会被拒绝。只有不受支持的 x-huly-* 标头的请求（例如代理跟踪 ID）会使用进程环境配置。缺失的值不会从环境变量中补齐。托管标头配置 v1 不支持电子邮件/密码身份验证。

Smithery 发布架构示例请参阅 docs/SMITHERY_URL_PUBLISH.md。

环境变量

*身份验证：首选 HULY_TOKEN。只有在 Huly 部署不支持托管 API 令牌，或其他兼容性限制要求使用密码身份验证时，才使用 HULY_EMAIL + HULY_PASSWORD。

启动和初始化

工具发现会读取生成的目录，而不会加载操作处理程序或等待 Huly。处理程序按需按工具组加载；并发调用会共享该组的加载过程。更改工具定义后，请运行 pnpm update-tool-catalog。如果目录已过时，构建将会失败。

对于 stdio，第一个工具列表请求会在后台启动由进程管理的 Huly 连接。需要完整 Huly 模型的调用会等待同一初始化过程。取消等待中的调用不会取消其他调用的初始化。模型初始化失败后，后续调用可以重试。项目列表通过单独的 REST 读取获取，不会等待完整模型。其他操作仍保留完整模型及其现有行为。

默认传输方式仍为 stdio：由 MCP 主机启动的每个进程都拥有自己的连接和模型。HTTP 允许客户端共享同一个运行中的服务。通过请求凭据标头创建的连接仅在需要时初始化模型；CLI 也采用这种按需策略。

内置诊断工具

get_version 返回当前服务版本和最新的 npm 版本。

get_huly_context 会返回当前 MCP 会话的脱敏运行时／配置上下文，且不会连接到 Huly。它会报告软件包版本、传输方式、身份验证模式、已脱敏的 Huly URL 来源／主机／协议、工作区、超时、配置来源、本机工具范围筛选，以及已解析的本机／代理工具公开情况。不会返回令牌、密码、电子邮件值、凭据标头、URL 路径、URL 查询字符串或 URL 凭据。

MCP 资源

对于支持 resources/read 的客户端，服务会以 JSON 上下文形式公开只读 MCP 资源。

resources/list 会返回具体的活跃项目资源。问题资源基于模板：使用 resources/templates/list 查找支持的问题 URI 模板，然后读取已知的问题 URI。

待办事项

功能待办事项和 SDK 对齐说明见 docs/BACKLOG.md。

可用工具

当解析后的工具公开模式为 proxy 时，客户端会看到内置工具以及这些代理元工具。随后，客户端会通过代理候选目录发现并调用本机 Huly 工具。客户端直接调用准确的本机工具名称时，也会进行分发，但须遵守 PROXY_OUTPUT_STRICT 范围规则；隐藏的本机工具不会通过 tools/list 公告。

代理元工具

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

项目

问题

评论

里程碑

文档

存储

附件

联系人

Channels

Calendar

时间跟踪

搜索

关联

活动

通知

工作区

审批

看板

卡片

协作者

自定义字段

云盘

Hr

Inventory

标签

潜在客户

邮件

模板

模型管理

规划器

偏好设置

流程

招聘

Sdk-Discovery

安全管理

序列管理

空间

支持

标签类别

标签

任务管理

测试管理

用户状态

视图

虚拟办公室

工作台

工作流状态

从源代码构建

已发布的软件包包含原生驻留桥接程序；Rust 是构建依赖项。 从源代码构建需要 Node.js、pnpm、Rustup、Python 3 和 Bash。请一次性准备好指定版本的 Rust 工具链、Zig 链接器和交叉编译 SDK：

pnpm setup:native
pnpm build
pnpm test:native

构建工具会保存在特定于平台的用户缓存中，位于检出目录和已发布软件包之外。 桥接程序是一个单一的 Rust I/O 循环；MCP 协议处理、授权和取消操作仍由共享的 Node 后端处理。

故障排除

使用含特殊字符的密码回退方案

如果你的 Huly 密码包含 *、%、! 或 # 等字符，通过 -e 或 --env 等 CLI 环境标志传入密码可能会失败，因为 shell 会在这些字符传递到进程之前对其进行解释。

解决方案：直接编辑 MCP 配置文件，而不是通过 shell 传递密码：

• Codex：~/.codex/config.toml
• Claude Code：~/.claude.json（用户范围）或 .mcp.json（项目范围）
• Claude Desktop：安装部分所列位置中的 claude_desktop_config.json
• VS Code 和 Cursor：使用安装部分所列的客户端配置位置；避免提交包含真实凭据的工作区文件
• Windsurf：直接编辑 Windsurf MCP 配置文件
• OpenCode：~/.config/opencode/opencode.json

对于 Claude JSON 配置，上述对 shell 敏感的字符可以直接写入。JSON 保留字符（如 " 和 \）仍需按常规进行 JSON 转义：

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

如果部署支持托管 API 令牌，请优先使用 HULY_TOKEN，而不是此密码回退方案（参见 环境变量）。

MCP 客户端显示“Failed to reconnect”

更改 MCP 配置后，某些客户端（包括 Claude Code）需要完全重启，而不只是重新连接。请完全退出应用程序，然后重新打开。

你可以使用以下命令独立验证连接是否正常：

claude mcp list  # Should show "Connected"

自托管 Huly：登录失败次数过多导致账户锁定

Huly 在 5 次 API 身份验证失败后会锁定密码登录。这通常发生在初始设置期间，原因是密码配置错误。即使服务重启，锁定状态仍会保留在数据库中。

症状：MCP 服务返回 PasswordLoginLocked 错误，Huly 网页界面显示“由于登录失败次数过多，密码登录已锁定。请使用 OTP 登录方式解锁账户。”（未配置 SMTP 时，OTP 无法使用。）

修复方法——重置 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>';"

CockroachDB 凭据可以在 Huly 的 compose.yml 中找到，也可以通过 docker exec <cockroach_container> env | grep COCKROACH 查询。

Windows 特定说明

• Bash 包装脚本（加载 .env 文件）由 Windows 上的 MCP 客户端启动时可能无法稳定运行。建议直接在 MCP 配置 JSON 中设置环境变量。
• 通过 SSH 拉取 Docker 镜像在 Windows 上可能会因凭据管理器问题而失败。如有需要，请从服务器桌面拉取镜像。