Huly MCP 是面向 Huly 平台的功能完整 MCP 服务器，同时在同一仓库中维护对应的 Huly CLI。两者共享同一操作注册表，因此操作的输入、输出、警告和类型化失败保持一致。Huly MCP 以 npm 包 @firfi/huly-mcp 发布，Huly CLI 以 @firfi/huly-cli 发布。
用途 Huly MCP 用于将 Huly 平台接入支持 MCP 的客户端，使客户端能够查询问题、创建和更新任务、管理标签与优先级，并执行 Huly 平台上的其他操作。它连接 Huly Platform 部署，官方称也应适用于 Platform Collective 和 TraceX 分支；Intabia 0.8.33 / model 0.8.4 已做兼容性测试，已知差距记录在 issue #279 中，分支支持仍为非官方。
主要能力 Huly MCP 提供功能完整的 Huly 操作集，覆盖项目、问题、评论、里程碑、文档、存储、附件、联系人、频道、日历、时间跟踪、搜索、关联、活动、通知、工作区、审批、看板、卡片、协作者、自定义字段、Drive、HR、库存、标签、线索、邮件、模板、模型管理、规划器、偏好设置、流程、招聘、SDK 发现、安全管理、序列管理、空间、支持、标签类别、标签、任务管理、测试管理、用户状态、视图、虚拟办公室、工作台、工作流状态等类别。
工具暴露模式 默认 HULY_TOOL_MODE=auto 时，为避免一次性列出约 470 个工具，Huly MCP 针对当前 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 固定常用原生工具，同时保留代理发现能力。
使用方式 Huly MCP 要求 Node.js 22.19.0 或更高版本。MCP 客户端不提供 Node.js 运行时，node、npx 以及包可执行文件会从 MCP 客户端运行的环境中解析 Node.js，安装前需检查该环境。若 MCP 客户端以较旧运行时启动 Huly MCP，服务器会初始化仅用于诊断的 MCP 界面，而不是加载不兼容的应用；其服务器指令和 get_huly_startup_diagnostic 工具会报告检测到的可执行文件和所需版本，同样的不支持运行时诊断也会写入 stderr。需升级 Node.js 或将 MCP 服务器命令配置为使用兼容 Node.js 可执行文件的绝对路径，然后重启 MCP 服务器；在运行时升级前，Huly 操作不可用。
标准配置使用 Huly API 令牌，适用于大多数 MCP 客户端。当目标部署支持时，优先使用在 Huly 账户设置中创建的托管 API 令牌。托管令牌绑定到一个工作区，分配有到期时间，可在不更改账户密码的情况下撤销。它们仍继承账户在该工作区中的全部权限，因此应使用专用集成账户，仅授予自动化所需的工作区角色、空间成员资格和数据访问权限。较旧的 Huly 部署可能不提供托管令牌设置；电子邮件/密码认证仍可作为兼容性回退。
安装与配置 可通过 Codex 的 MCP 管理器添加，或直接写入 ~/.codex/config.toml；也可按标准配置添加到 ~/.claude.json。Claude Desktop 可添加到 claude_desktop_config.json，macOS 路径为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 路径为 %APPDATA%\Claude\claude_desktop_config.json。VS Code 可通过命令面板的 "MCP: Add Server" 添加，或写入 .vscode/mcp.json 等 VS Code MCP 配置；不要提交包含真实凭据的工作区配置文件。Cursor 可添加到 ~/.cursor/mcp.json，或通过 Settings → Tools & Integrations → New MCP Server 添加。Windsurf 添加到其 MCP 配置文件。OpenCode 打开全局配置文件 ~/.config/opencode/opencode.json 并合并条目。Pi 需要 MCP 适配器，安装后以 auto 模式使用 Huly MCP，并将四个代理工具提升到 Pi 的原生工具列表。
@latest 标签会向包运行器请求最新版本。某些 MCP 客户端会保持服务器进程或已解析安装处于活动状态，因此更新时需重启或重新添加服务器。
传输方式 默认服务器使用 stdio 传输。HTTP 传输时，服务器默认监听 http://127.0.0.1:3000/mcp，可通过 MCP_HTTP_PORT 和 MCP_HTTP_HOST 配置。两种传输均使用 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-* 头单独配置。
对于托管或隧道 HTTP 部署，可要求 MCP 端点 bearer 令牌。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 服务器环境中设置 HULY_PROFILE=work。两个进程必须在同一操作系统用户和配置目录下运行。stdio 不会隐式跟随活动 CLI 配置。保存的令牌绑定到其实例 URL 和工作区；更改需要重新登录或完整注入环境凭据。
托管 HTTP 头配置 对于托管 URL 部署，保持服务器进程配置为 MCP_TRANSPORT=http。托管层可将每会话 Huly 凭据作为请求头转发，使一个托管服务器无需进程级 HULY_* 环境变量即可服务不同 Huly 工作区。支持的 v1 头中，若存在任何受支持的 x-huly-* 头，则所有必需头都必须存在，且不支持的 x-huly-* 头会被拒绝。仅含不支持 x-huly-* 头（例如代理跟踪 ID）的请求使用进程环境配置。缺失值不会从环境变量填充。托管头配置 v1 不支持电子邮件/密码认证。
环境变量 认证优先使用 HULY_TOKEN。仅当 Huly 部署不支持托管 API 令牌或其他兼容性约束要求密码认证时，才使用 HULY_EMAIL + HULY_PASSWORD。
内置诊断工具 get_version 返回当前服务器版本和最新 npm 版本。get_huly_context 返回当前 MCP 会话的已清理运行时/配置上下文，不连接 Huly。它报告包版本、传输、认证模式、已清理的 Huly URL 来源/主机/协议、工作区、超时、配置来源、原生工具范围过滤以及解析后的原生/代理工具暴露情况。令牌、密码、电子邮件值、凭据头、URL 路径、URL 查询字符串和 URL 凭据永不返回。
服务器为支持 resources/read 的客户端暴露只读 MCP Resources 作为 JSON 上下文。resources/list 返回具体的活动项目资源。问题资源基于模板：使用 resources/templates/list 发现支持的问题 URI 模板，然后读取已知问题 URI。
适用场景 适用于需要将 Huly 平台接入 MCP 客户端进行项目管理和任务自动化的场景，也适用于需要终端原生 Huly 集成、脚本和自动化替代方案的场景。Huly CLI 提供与 Huly MCP 完全相同的 Huly 操作，以原生、模式感知命令形式暴露，支持人类可读或 JSON 输出、文件输入、上传和下载。
限制 Huly MCP 要求 Node.js 22.19.0 或更高版本，运行时版本不满足时 Huly 操作不可用。分支支持为非官方。托管头配置 v1 不支持电子邮件/密码认证。若 Huly 密码包含 *、%、! 或 # 等字符，通过 CLI 环境标志传递可能失败，因为 shell 会在字符到达进程前解释它们，解决方案是直接编辑 MCP 配置文件。更改 MCP 配置后，某些客户端（包括 Claude Code）需要完全重启而非仅重新连接。自托管 Huly 在 5 次 API 认证失败后会锁定密码登录，该锁定在数据库跨服务重启后仍存在，需在 CockroachDB 中重置锁定计数器。Windows 上由 MCP 客户端启动的 Bash 包装脚本（source .env 文件）可能无法可靠工作，建议直接在 MCP 配置 JSON 中设置环境变量；Windows 上通过 SSH 拉取 Docker 镜像可能因凭据管理器问题失败。