huly-mcp

Name: huly-mcp
Author: varaprasadreddy9676

本地服务

github.com/varaprasadreddy9676生产力532 周前更新

代码仓库

关于 huly-mcp

huly-mcp 是面向 Huly 项目管理平台的 MCP 服务，供团队通过兼容客户端管理项目、问题和文档。它提供涵盖评论、里程碑、组件、标签及工时记录的工具，也支持 Markdown 文档编辑。

主要功能

01管理项目与问题
02评论、标签和关联操作
03里程碑与组件管理
04创建及编辑 Markdown 文档
05问题全文搜索与工时记录

适用场景

01通过 AI 客户端更新问题状态
02批量创建和整理项目问题
03在 Huly 中编写含 Mermaid 图表的文档
04搜索问题并记录处理工时

MCP 相关

通过标准 stdio 传输向 MCP 客户端提供 36 个 Huly 工作区管理工具，兼容 Claude Desktop 等客户端。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "varaprasadreddy9676-huly": {
      "command": "npx",
      "args": [
        "-y",
        "huly-mcp-sdk"
      ],
      "env": {
        "HULY_TOKEN": "<HULY_TOKEN>",
        "HULY_WORKSPACE": "<HULY_WORKSPACE>",
        "HULY_FRONT_URL": "<HULY_FRONT_URL>"
      }
    }
  }
}

启动命令npx -y huly-mcp-sdk

需要配置的环境变量

HULY_TOKEN密钥Huly workspace token — get from huly.app DevTools → Application → Local Storage → token

HULY_WORKSPACEYour Huly workspace slug (the part after huly.app/ in your URL, e.g. 'myteam')

HULY_FRONT_URLOptional — set to https://front.huly.app to enable reading document content

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmhuly-mcp-sdk0.5.4stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

huly-mcp-sdk

最完整的 Huly MCP 服务，适用于 Huly——这款开源项目管理平台。

可将 Claude Desktop（以及任何兼容 MCP 的客户端）直接连接到你的 Huly 工作区。通过自然语言管理项目、问题、里程碑、组件、文档、标签等内容。

工具（共 36 个）

类别	工具	描述
项目	`list_projects`	列出工作区中的所有项目
	`get_project`	获取项目详情和可用状态
	`create_project`	创建具有唯一标识符的新跟踪器项目
问题	`list_issues`	列出问题，可选按状态／优先级筛选
	`get_issue`	获取问题的完整详情（例如 `PROJ-42`）
	`create_issue`	创建新问题
	`update_issue`	更新标题、状态、优先级、指派对象、截止日期、组件、里程碑
	`delete_issue`	根据标识符永久删除问题
评论	`add_comment`	为问题添加评论
	`list_comments`	列出问题的所有评论（包含 `delete_comment` 所需的 ID）
	`delete_comment`	根据 ID 删除指定评论
时间跟踪	`log_time`	记录问题所花费的小时数
标签	`list_labels`	列出所有标签及其颜色和使用次数
	`create_label`	创建带可选十六进制颜色的新标签
	`add_label`	为问题添加标签（如果标签不存在则自动创建）
	`remove_label`	从问题中移除标签
关联关系	`add_relation`	将两个问题标记为相关（双向）
	`add_blocked_by`	将问题标记为被另一个问题阻塞
	`set_parent`	设置或清除问题的父级史诗
成员	`list_members`	列出工作区成员
里程碑	`list_milestones`	列出项目的里程碑
	`create_milestone`	创建带目标日期和状态的里程碑
组件	`list_components`	列出项目中的组件（子区域）
	`create_component`	创建带可选负责人信息的新组件
文档	`list_teamspaces`	列出文档团队空间
	`create_teamspace`	创建新的团队空间（顶层文档文件夹）
	`list_documents`	列出团队空间中的文档
	`delete_document`	根据 ID 永久删除文档
	`get_document`	获取文档元数据和内容
	`create_document`	在团队空间中创建新文档
	`update_document`	将 Markdown 内容写入文档——Mermaid 图表可原生渲染
	`link_document`	将文档关联到问题——文档会显示在“关联关系”面板中
搜索	`search_issues`	对所有问题进行全文搜索

要求

Node.js >= 20
Huly 账号——huly.app（云端）或可自托管版本

快速开始

npx huly-mcp-sdk setup

这会运行交互式设置向导——向你的邮箱发送一次性验证码（Google／GitHub SSO 账号也适用），并自动写入 .env 文件。

你的工作区 slug 是 Huly URL 中域名后面的部分：huly.app/myteam → slug 为 myteam。

兼容的客户端

同一个 MCP 服务适用于所有主流 AI 编码工具。选择你的客户端。

**身份验证说明：**以下所有配置示例均使用 HULY_TOKEN。如果遇到令牌过期问题，请改用邮箱和密码——只需将 env 代码块替换为：
"HULY_EMAIL": "[email protected]",
"HULY_PASSWORD": "yourpassword",
"HULY_WORKSPACE": "your-workspace-slug"
关于这两种选项的详情，请参阅手动身份验证。

Claude Desktop

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

保存后重启 Claude Desktop。

Claude Code（CLI）

claude mcp add huly -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk

也可以将其限定为仅适用于单个项目：

claude mcp add huly --scope project -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk

验证是否已连接：claude mcp list

Cursor

创建或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

重启 Cursor。工具会显示在 Agent 面板的 MCP 下。

Windsurf（Codeium）

创建或编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

重启 Windsurf。Cascade AI 面板即可使用 MCP 工具。

VS Code — Cline 扩展

安装 Cline 扩展
打开 Cline 设置 → MCP Servers → Edit MCP Settings
添加：

{
  "huly": {
    "command": "npx",
    "args": ["huly-mcp-sdk"],
    "env": {
      "HULY_TOKEN": "your-token",
      "HULY_WORKSPACE": "your-workspace-slug"
    }
  }
}

VS Code — Continue 扩展

安装 Continue 扩展
编辑 ~/.continue/config.json，并将以下内容添加到 mcpServers 数组中：

{
  "mcpServers": [
    {
      "name": "huly",
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  ]
}

Zed

编辑 ~/.config/zed/settings.json，并添加一个 context_servers 条目：

{
  "context_servers": {
    "huly": {
      "command": {
        "path": "npx",
        "args": ["huly-mcp-sdk"],
        "env": {
          "HULY_TOKEN": "your-token",
          "HULY_WORKSPACE": "your-workspace-slug"
        }
      }
    }
  }
}

OpenAI Codex CLI

编辑 ~/.codex/config.json，并将以下内容添加到 mcpServers 中：

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

其他任何兼容 MCP 的客户端

该服务使用标准的 stdio 传输。如果你的工具支持 MCP，配置模式始终相同：

command： npx
args： ["huly-mcp-sdk"]
env： HULY_TOKEN + HULY_WORKSPACE

请查阅你的工具的 MCP 文档，了解确切的配置文件位置。

替代方案（避免 npx 冷启动）： 克隆并构建一次，然后直接指向编译后的二进制文件：
git clone https://github.com/varaprasadreddy9676/huly-mcp.git
cd huly-mcp && npm install && npm run build
在上述任意配置中，将 "command": "npx", "args": ["huly-mcp-sdk"] 替换为 "command": "node", "args": ["/absolute/path/to/huly-mcp/dist/index.js"]。

提示词示例

项目与问题：

“创建一个名为 'Mobile App'、标识符为 MOBILE 的新项目”
“列出 PROJ 项目中所有进行中的问题”
“在 PROJ 中创建一个高优先级问题，标题为 'Fix login timeout'”
“将 PROJ-42 的状态更新为 Done，指派给 Sarah，并将其移至 Auth 组件”
“搜索与身份验证相关的问题”
“在 PROJ-15 中添加一条评论，说明修复已部署”
“列出 PROJ-42 的所有评论，查看讨论内容”

里程碑与组件：

“在 PROJ 中创建一个名为 'v2.0 Launch'、目标日期为 2026-06-01 的里程碑”
“列出 PROJ 项目的里程碑”
“在 PROJ 中创建一个名为 'Auth' 的组件”
“列出 PROJ 中的所有组件”

标签与关联：

“为 PROJ-42 添加 'bug' 标签”
“创建一个名为 'backend'、颜色为 #3b82f6 的标签”
“将 PROJ-55 标记为被 PROJ-12 阻塞”
“将 PROJ-42 设为 PROJ-5 的子任务”

时间跟踪：

“为数据库重构在 PROJ-42 上记录 2.5 小时”

文档：

“列出 Engineering teamspace 中的所有文档”
“在 Engineering teamspace 中创建一个名为 'API Design' 的文档”
“使用以下 Markdown 更新 API Design 文档：...”
“在 EP1 文档中添加 Mermaid 架构图”
“将文档 abc123 链接到问题 PROJ-42”
“删除 PROJ-15 的第二条评论”

文档内容

阅读：`get_document`

get_document 始终返回完整元数据（标题、teamspace、评论、快照）。如需同时获取并显示文本内容，请设置可选的 HULY_FRONT_URL 环境变量：

"env": {
  "HULY_TOKEN": "...",
  "HULY_WORKSPACE": "myteam",
  "HULY_FRONT_URL": "https://front.huly.app"
}

对于可自托管的 Huly，请将 HULY_FRONT_URL 设置为你自己的前端服务 URL（例如 http://localhost:8083）。

编写：`update_document`

update_document 接受一个 documentId 和一个 markdown 字符串，并直接将丰富的结构化内容写入文档，无需手动编辑。

支持的 Markdown：

元素	语法
标题	`#`、`##`、`###`
粗体 / 行内代码	`bold`、`code`
段落	纯文本
项目符号列表	`- item`
管道符表格	`\| col \| col \|`
代码块	```lang
Mermaid 图表	```mermaid — 以 Huly 原生的 `mermaid` 节点类型存储，因此图表会在编辑器中渲染为可交互的可视内容

示例：

update_document({
  documentId: "abc123",
  markdown: `# Service Flow\n\n` +
    `## Architecture\n\n` +
    "```mermaid\n" +
    "flowchart TD\n" +
    "  A([User]) --> B[Browse Catalogue]\n" +
    "  B --> C[Pay via Razorpay]\n" +
    "  C --> D[Order Confirmed]\n" +
    "```\n\n" +
    "## Business Rules\n\n" +
    "- Payment required before confirmation\n" +
    "- All orders synced to HIS\n"
})

Mermaid 代码块会在 Huly 文档编辑器中渲染为实时交互式图表，而不是代码块。

批量 CSV 导入

一次从 CSV 文件导入多个问题，适用于从其他工具迁移：

node scripts/import-csv.js tasks.csv PROJ

CSV 格式：

title,priority,status,dueDate
Fix login bug,High,In Progress,2025-04-01
Add dark mode,Medium,,
Improve performance,Urgent,,2025-05-01

必需列：title。可选列：priority（Urgent/High/Medium/Low）、status（必须与项目中的某个状态名称一致）、dueDate（YYYY-MM-DD）。

手动身份验证

在项目根目录中创建 .env 文件（或在客户端配置中的 env 传入）：

选项 A — 电子邮件 + 密码（推荐）：

如果你的 Huly 账户已设置密码，则可使用此方式（Profile → Security → Change password）。

[email protected]
HULY_PASSWORD=yourpassword
HULY_WORKSPACE=your-workspace-slug

选项 B — 令牌：

HULY_WORKSPACE=your-workspace-slug
HULY_TOKEN=your-token-here

获取令牌：前往 huly.app → 打开浏览器开发者工具 → Application → Local Storage → https://huly.app → 复制 token 值。

令牌会在一段时间后过期。如果遇到身份验证错误，请改用电子邮件 + 密码身份验证，或从开发者工具中刷新令牌。

自托管 Huly：

HULY_ACCOUNTS_URL=https://your-huly-instance.com/account
HULY_FRONT_URL=https://your-huly-instance.com

架构

单个长期运行的 WebSocket 连接 — 每个进程通过 @hcengineering/server-client 连接一次，而非每次调用工具时都重新连接（模型加载需要 1–3 s，因此这能让工具保持快速）
延迟初始化 — 在首次调用工具时建立连接，以便在 Claude 中清晰显示身份验证错误
双重身份验证 — OTP 令牌（适用于 Google/GitHub SSO）或电子邮件 + 密码
Stdio 传输 — 标准 MCP 传输，与 Claude Desktop 及任何 MCP 客户端兼容

更新日志

v0.5.6 — delete_document

新增：delete_document — 根据 ID 永久删除文档

v0.5.5 — create_teamspace

新增：create_teamspace — 创建新的文档团队空间（用于按项目或团队整理文档的顶层文件夹）

v0.5.2 — delete_comment + link_document

新增：delete_comment — 根据 ID 删除问题中的指定评论；list_comments 现在会在输出中包含评论 ID
新增：link_document — 将 Huly 文档关联到问题；该文档会显示在问题的 Relations 面板中

v0.5.0 — 文档编写 + 错误修复

新增：update_document — 以编程方式向任意 Huly 文档写入 Markdown；\``mermaid` 代码块使用 Huly 原生节点类型，并渲染为交互式图表
修复：IssueStatus 查询 — 在 Huly 中，状态是全局存储的（core:space:Model），而非按项目存储；移除了错误的空间筛选条件，该条件会导致 create_issue、update_issue 和 list_issues 出现 “no statuses found” 错误
修复：create_project — 设置 members: [currentUser]，使新创建的项目能立即在 Huly 界面中显示

v0.4.0

log_time、list_comments、在 update_issue 中分配组件 / 里程碑

v0.3.1

get_document、create_document

v0.3.0

create_project、create_milestone、为问题添加负责人支持

链接

npm：https://www.npmjs.com/package/huly-mcp-sdk
GitHub：https://github.com/varaprasadreddy9676/huly-mcp
MCP Registry：https://registry.modelcontextprotocol.io（搜索 "huly-mcp"）

许可证

Eclipse Public License 2.0

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。