huly-mcp-selfhost 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to [huly-mcp-selfhost](https://www.npmjs.com/package/huly-mcp-selfhost). Versions follow [semver](https://semver.org).
 
+### 3.6.0 — 2026-11-12
+
+- **New: Claude Desktop extension** — `huly-mcp-selfhost.mcpb` on every GitHub release: double-click, enter your Huly login in Claude Desktop's form (password and token go to the system keychain), done — no Node.js, no JSON. Built from the same bundled server; the release smoke-tests it before attaching it.
+- **Clearer tool descriptions** for the tools rated weakest by Glama's Tool Definition Quality Score (`list_todos`, `search`, `create_document`, `delete_comment`, …): verb first, the key default or side effect, the tool to use instead. +732 characters in the default tool list (+1.9 %). `create_document` now points to `update_document` for the body.
+- **`changes_since` is shorter** — fields set when an issue was created count as "new", and when one person made every change the name appears once in the heading (−14 % measured on 14 days of changes).
+- **`triage_inbox`**: a comment that appears on several items (bots commenting on every PR) is shown once in full; GitHub-synced accounts are named by their login (`dependabot[bot] (GitHub)`) instead of "Unknown".
+- **Aliases per tool**: `update_milestone`/`get_milestone` accept `milestoneLabel` for `label`, `update_component` accepts `componentLabel` — the names other tools use.
+- **Release workflow** waits up to 15 minutes for npm before the MCP registry publish and retries it (3.5.1 needed a manual re-run).
+- Website and README: navigation with jump links, back-to-top links, plugin icon for the Claude directory.
+- Issue forms (bug report asks for `check_setup` output), questions in GitHub Discussions, private security reports.
+
+### 3.5.1 — 2026-11-11
+
+- **Fixed: `resources/list` failed without a usable login** — it tried to list your open issues and errored when the login was missing or wrong (e.g. in an inspector or a client not set up yet). Now the guides are listed and issues are simply left out. Found through Glama's inspection.
+- **Release workflow** waits until npm shows the new version before registering it with the MCP registry (3.5.0 was refused once because npm was a few seconds behind).
+- npm and registry descriptions: 227 tools.
+
 ### 3.5.0 — 2026-11-11
 
 - **Fixed: MCP registry name** — the registry namespace is case-sensitive and must match the GitHub owner: `io.github.JoKeks2023/huly-mcp-selfhost` (was lowercase, refused with 403). A test checks it.

package/README.md

@@ -8,7 +8,22 @@
 
 **Huly for AI agents.** An MCP server for [Huly](https://huly.io) — self-hosted or Huly Cloud — that lets Claude and other agents work in your workspaces: issues, epics, milestones, documents, chat, inbox, planner, test management and more. 227 tools, built for agent workflows and to spend as few tokens as possible.
 
-[Website](https://jokeks2023.github.io/huly-mcp/) · [Quick start](#quick-start) · [Tools](#tools-227-total-grouped-in-toolsets) · [Claude Code plugin](#claude-code-plugin) · [Changelog](https://github.com/JoKeks2023/huly-mcp/blob/main/CHANGELOG.md)
+<p align="center">
+  <b><a href="#quick-start">Quick start</a></b> ·
+  <a href="#compatible-clients">Clients</a> ·
+  <a href="#claude-code-plugin">Claude Code plugin</a> ·
+  <a href="#command-line">Command line</a> ·
+  <a href="#team-server-over-http">Team server</a> ·
+  <a href="#tools-227-total-grouped-in-toolsets">Tools</a> ·
+  <a href="#configuration">Configuration</a> ·
+  <a href="#authentication">Authentication</a>
+  <br>
+  <a href="https://jokeks2023.github.io/huly-mcp/">Website</a> ·
+  <a href="https://github.com/JoKeks2023/huly-mcp/wiki/">Docs</a> ·
+  <a href="https://github.com/JoKeks2023/huly-mcp/blob/main/CHANGELOG.md">Changelog</a> ·
+  <a href="https://www.npmjs.com/package/huly-mcp-selfhost">npm</a> ·
+  <a href="https://hub.docker.com/r/jokeks2023/huly-mcp">Docker Hub</a>
+</p>
 
 ## Highlights
 
@@ -21,14 +36,16 @@
 - **Claude Code plugin:** `/huly:setup` asks once per repo how Huly is used there and writes the rules; skill, hooks and `/huly:*` commands. Guides and a `setup` prompt for every other MCP client too.
 - **Self-hosted first:** document and description content, file uploads and internal URLs work on `huly-selfhost`; one account, all its workspaces.
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Tokens, measured
 
 What the model reads — measured on a real self-hosted project (≈60 issues):
 
 | | Characters | ≈ Tokens |
 |---|--:|--:|
-| Tool list, default toolsets (99 tools, each callable directly) | 38,259 | 10.9k |
-| Tool list, pinned workspace | 34,567 | 9.9k |
+| Tool list, default toolsets (99 tools, each callable directly) | 38,991 | 11.1k |
+| Tool list, pinned workspace | 35,299 | 10.1k |
 | Open issues of a project (one call, ≈30 issues) | 2,768 | 0.8k |
 | One issue with description | 318 | 0.1k |
 | Project report (done, in progress, blocked, milestones, PRs, time) | ~2,700 | 0.8k |
@@ -40,7 +57,7 @@ Lists default to open items, empty fields are left out, and one call answers wha
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JoKeks2023/huly-mcp/main/docs/assets/benchmark-dark.svg">
-  <img alt="Characters per answer: huly-mcp-selfhost needs 2.9× less text per answer (median), 14× smaller tool definitions, one call instead of up to four" src="https://raw.githubusercontent.com/JoKeks2023/huly-mcp/main/docs/assets/benchmark-light.svg" width="900">
+  <img alt="Characters per answer: huly-mcp-selfhost needs 2.9× less text per answer (median), 13× smaller tool definitions, one call instead of up to four" src="https://raw.githubusercontent.com/JoKeks2023/huly-mcp/main/docs/assets/benchmark-light.svg" width="900">
 </picture>
 
 Same self-hosted Huly, same questions, the best parameters on both sides, measured 2026-11-11. For the other server only the text content is counted, not the duplicate JSON copy it also returns. Where we return more (components), it is because we include each component's description and code paths.
@@ -59,13 +76,15 @@ Same self-hosted Huly, same questions, the best parameters on both sides, measur
 | Milestones | 208 (1 call) | 503 (1 call) | 2.4× less |
 | Components | 1,302 (1 call) | 692 (1 call) | 2.0× more |
 | Documents of a teamspace | 106 (1 call) | 305 (1 call) | 2.9× less |
-| Tool definitions (49 tools with the same name) | 15,728 | 216,890 | 13.8× less |
+| Tool definitions (49 tools with the same name) | 16,579 | 216,890 | 13.1× less |
 
 </details>
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Quick start
 
-You need Node.js 20+ and a Huly account — [Huly Cloud](https://huly.app) or self-hosted.
+You need a Huly account — [Huly Cloud](https://huly.app) or self-hosted — and, except for the Claude Desktop extension, Node.js 20+.
 
 **Claude Code** — install the plugin, then fill in its settings when asked:
 
@@ -76,7 +95,9 @@ You need Node.js 20+ and a Huly account — [Huly Cloud](https://huly.app) or se
 
 Then run `/huly:setup` in a repository. Details: [Claude Code plugin](#claude-code-plugin).
 
-**Claude Desktop, Cursor, VS Code, Windsurf, Zed, …** — add the server to your client's MCP config:
+**Claude Desktop** — download [`huly-mcp-selfhost.mcpb`](https://github.com/JoKeks2023/huly-mcp/releases/latest/download/huly-mcp-selfhost.mcpb), double-click it and enter your Huly login. Nothing else to install.
+
+**Cursor, VS Code, Windsurf, Zed, …** (or Claude Desktop by hand) — add the server to your client's MCP config:
 
 ```json
 {
@@ -105,6 +126,8 @@ Then ask: *"What's on my plate today?"*, *"Plan the login redesign as an epic in
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Claude Code plugin
 
 The repo is also a Claude Code plugin marketplace. The plugin bundles the MCP server with a workflow skill, hooks and commands:
@@ -114,7 +137,7 @@ The repo is also a Claude Code plugin marketplace. The plugin bundles the MCP se
 /plugin install huly@huly-mcp
 ```
 
-> **Note:** the plugin starts the npm package at exactly its own version (e.g. `huly-mcp-selfhost@3.5.0`; the plugin directory does not accept version ranges), so a plugin update brings the matching server. To try a local checkout instead: `npm run build`, then point `plugin/.mcp.json` at `dist/index.js` and start `claude --plugin-dir ./plugin`.
+> **Note:** the plugin starts the npm package at exactly its own version (e.g. `huly-mcp-selfhost@3.6.0`; the plugin directory does not accept version ranges), so a plugin update brings the matching server. To try a local checkout instead: `npm run build`, then point `plugin/.mcp.json` at `dist/index.js` and start `claude --plugin-dir ./plugin`.
 
 Claude Code then asks for your Huly settings (e-mail + password or token, and for self-hosted Huly the accounts and front URL; passwords and tokens go to the OS keychain).
 
@@ -135,6 +158,8 @@ Without the plugin, the same server works in Claude Code as a plain MCP server (
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Command line
 
 Every tool also works from the terminal — for scripts, CI and quick looks without a chat. Same login (`HULY_*` environment or `--env-file`), same safety rules (write scope, audit log, confirmation for hard-to-undo changes).
@@ -159,6 +184,8 @@ huly-mcp my_day --format json | jq -r .text
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Tools (227 total, grouped in toolsets)
 
 All tools except `list_workspaces` take a `workspace` argument — required for every change, optional for reads when only one workspace is available.
@@ -210,8 +237,8 @@ Context cost of `tools/list` (≈3.5 chars/token):
 
 | | default (99 tools) | `all` (227 tools) |
 |---|--:|--:|
-| several workspaces | ~38.3k chars ≈ **10.9k tokens** | ~83.5k chars ≈ **23.9k tokens** |
-| pinned with `HULY_WORKSPACE` | ~34.6k chars ≈ **9.9k tokens** | ~75.0k chars ≈ **21.4k tokens** |
+| several workspaces | ~39.0k chars ≈ **11.1k tokens** | ~84.2k chars ≈ **24.1k tokens** |
+| pinned with `HULY_WORKSPACE` | ~35.3k chars ≈ **10.1k tokens** | ~75.8k chars ≈ **21.7k tokens** |
 
 For comparison, 2.2.0 needed ≈12.8k tokens for 64 tools. **Using one workspace? Set `HULY_WORKSPACE`** — the `workspace` argument then disappears from every tool (−10%). **Claude Code** loads MCP tools on demand, so there even `HULY_TOOLSETS=all` costs little up front.
 
@@ -434,6 +461,8 @@ Options: `--run <name>`, `--parent-suite <suite>`, `--no-create` (only existing
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Workspaces (one account, several workspaces)
 
 A single Huly account can belong to several workspaces — e.g. a personal one and a team one. This server logs in **once** with your account credentials and discovers every workspace that account can access via the account service (`getUserWorkspaces()`). You **don't configure a workspace** in the environment.
@@ -452,6 +481,8 @@ A single Huly account can belong to several workspaces — e.g. a personal one a
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Configuration
 
 | Variable | Required | Purpose |
@@ -479,6 +510,8 @@ A single Huly account can belong to several workspaces — e.g. a personal one a
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Authentication
 
 Create a `.env` file in the project root (or pass via `env` in your client config). No workspace is needed in either option.
@@ -522,6 +555,8 @@ HULY_FRONT_URL=https://your-huly-instance.com                # document content
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Compatible clients
 
 The same MCP server works across all major AI coding tools. All examples use **email + password** and the npm package via `npx`; for SSO accounts replace the two credentials with `"HULY_TOKEN": "your-token"` (see [Authentication](#authentication)). To run a local build instead, replace `npx` + args with `node` + `["/absolute/path/to/huly-mcp/dist/index.js"]`.
@@ -532,6 +567,10 @@ The same MCP server works across all major AI coding tools. All examples use **e
 
 ### Claude Desktop
 
+**One click:** download [`huly-mcp-selfhost.mcpb`](https://github.com/JoKeks2023/huly-mcp/releases/latest/download/huly-mcp-selfhost.mcpb) and double-click it (or *Settings → Extensions → Advanced settings → Install Extension…*). Claude Desktop shows a form for your Huly login; password and token go to the system keychain. No Node.js or JSON needed — Claude Desktop brings its own Node.js.
+
+**Or by hand** in the config file:
+
 - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
@@ -703,11 +742,13 @@ For network access (HTTP/SSE) use the [Docker image](#docker).
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Running the server
 
 ### npx (recommended)
 
-Every client example uses `"command": "npx", "args": ["-y", "huly-mcp-selfhost"]`. Pin a version (`huly-mcp-selfhost@3.5.0`) if you want updates only when you choose.
+Every client example uses `"command": "npx", "args": ["-y", "huly-mcp-selfhost"]`. Pin a version (`huly-mcp-selfhost@3.6.0`) if you want updates only when you choose.
 
 ### From source
 
@@ -766,6 +807,8 @@ Set `MCP_ALLOWED_HOSTS` to the host names clients use (DNS-rebinding protection)
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Example prompts
 
 **Workspaces:**
@@ -824,6 +867,8 @@ Set `MCP_ALLOWED_HOSTS` to the host names clients use (DNS-rebinding protection)
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Document content
 
 ### Reading: `get_document`
@@ -890,6 +935,8 @@ The Mermaid block renders as a live interactive diagram in Huly's document edito
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Bulk CSV Import
 
 Import many issues at once from a CSV file — useful for migrating from other tools:
@@ -914,6 +961,8 @@ Required column: `title`. Optional: `priority` (Urgent/High/Medium/Low), `status
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Architecture
 
 ```text
@@ -940,6 +989,8 @@ See [`src/connection.ts`](https://github.com/JoKeks2023/huly-mcp/blob/main/src/c
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Development and CI
 
 ```bash
@@ -979,16 +1030,22 @@ Secrets:
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/JoKeks2023/huly-mcp/blob/main/CHANGELOG.md).
 
 ---
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Credits
 
 Started as a fork of [varaprasadreddy9676/huly-mcp](https://github.com/varaprasadreddy9676/huly-mcp) (npm `huly-mcp-sdk`) by SaiVaraprasad Medapati and grown from its 33 tools to 227, with self-hosted support, toolsets, agent workflow and the Claude Code plugin. Published separately as `huly-mcp-selfhost`. Not affiliated with Huly Labs.
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## Links
 
 - Website: https://jokeks2023.github.io/huly-mcp/
@@ -996,6 +1053,10 @@ Started as a fork of [varaprasadreddy9676/huly-mcp](https://github.com/varaprasa
 - npm: https://www.npmjs.com/package/huly-mcp-selfhost · Docker: https://hub.docker.com/r/jokeks2023/huly-mcp · MCP Registry: `io.github.JoKeks2023/huly-mcp-selfhost`
 - Security: [SECURITY.md](https://github.com/JoKeks2023/huly-mcp/blob/main/SECURITY.md)
 
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>
+
 ## License
 
 [Eclipse Public License 2.0](https://github.com/JoKeks2023/huly-mcp/blob/main/LICENSE)
+
+<div align="right"><a href="#huly-mcp-selfhost">↑ Back to top</a></div>

package/dist/index.js

@@ -90627,7 +90627,7 @@ async function socialIdNames(client, ids) {
   if (ids.length === 0) return /* @__PURE__ */ new Map();
   const identities = await client.findAll(import_contact.default.class.SocialIdentity, { _id: { $in: ids } });
   const names2 = await peopleNames(client);
-  return new Map(identities.map((i) => [i._id, names2.get(i.attachedTo) ?? "Unknown"]));
+  return new Map(identities.map((i) => [i._id, names2.get(i.attachedTo) ?? (i.type === "github" && typeof i.value === "string" ? `${i.value} (GitHub)` : "Unknown")]));
 }
 async function currentAccountUuid(client) {
   const me = await currentPerson(client);
@@ -92316,7 +92316,7 @@ var createDocument = wrapToolHandler(async (args) => {
     docId
   );
   return `\u2705 Document **"${args.title}"** created (id: \`${docId}\`) in teamspace "${teamspace.name}".
-Open it in Huly to add content via the editor.`;
+Write its content with update_document.`;
 });
 var deleteDocument = wrapToolHandler(async (args) => {
   const client = await getConnection(args.workspace);
@@ -94223,20 +94223,26 @@ var changesSince = wrapToolHandler(async (args) => {
   ]);
   const authors = await socialIdNames(client, [...new Set([...updates, ...comments].map((m) => m.createdBy).filter((x) => x != null))]);
   const statusName2 = new Map(statuses.map((s) => [s._id, s.name]));
-  const lines = issues.map((issue2) => {
+  const rows = issues.map((issue2) => {
     const ups = updates.filter((u) => u.attachedTo === issue2._id);
-    const fields = [...new Set(ups.map((u) => u.attributeUpdates?.attrKey).filter((k) => k != null && k !== "rank").map((k) => k === "attachedTo" ? "parent" : k))];
     const cs = comments.filter((c) => c.attachedTo === issue2._id);
+    const isNew = issue2.createdOn >= since;
+    const fields = isNew ? [] : [...new Set(ups.map((u) => u.attributeUpdates?.attrKey).filter((k) => k != null && k !== "rank").map((k) => k === "attachedTo" ? "parent" : k))];
     const who = [...new Set([...ups, ...cs].map((m) => authors.get(m.createdBy)).filter((n) => n != null))];
     const parts = [
-      issue2.createdOn >= since ? "new" : void 0,
+      isNew ? "new" : void 0,
       fields.length > 0 ? `changed ${fields.join(", ")}` : void 0,
       cs.length > 0 ? `+${cs.length} comment(s)` : void 0
     ].filter((p) => p != null);
+    return { issue: issue2, who, what: parts.length > 0 ? parts.join(" \xB7 ") : "updated" };
+  });
+  const everyone = [...new Set(rows.flatMap((r) => r.who))];
+  const single = everyone.length === 1 && rows.every((r) => r.who.length === 1);
+  const lines = rows.map(({ issue: issue2, who, what }) => {
     const kind = issue2._class === C.PullRequest ? "PR " : "";
-    return `- ${kind}**${issue2.identifier}** [${statusName2.get(issue2.status) ?? "?"}] ${issue2.title} \u2014 ${parts.length > 0 ? parts.join(" \xB7 ") : "updated"}${who.length > 0 ? ` (by ${who.join(", ")})` : ""} \xB7 ${formatDate(issue2.modifiedOn)}`;
+    return `- ${kind}**${issue2.identifier}** [${statusName2.get(issue2.status) ?? "?"}] ${issue2.title} \u2014 ${what}${!single && who.length > 0 ? ` (by ${who.join(", ")})` : ""} \xB7 ${formatDate(issue2.modifiedOn)}`;
   });
-  return `## Changes since ${new Date(since).toISOString()} (${issues.length}${issues.length === args.limit ? "+" : ""})
+  return `## Changes since ${new Date(since).toISOString()} (${issues.length}${issues.length === args.limit ? "+" : ""})${single ? `, all by ${everyone[0]}` : ""}
 
 ${lines.join("\n")}`;
 });
@@ -97322,6 +97328,7 @@ var triageInbox = wrapToolHandler(async (args) => {
   const ctxs = await client.findAll(C.DocNotifyContext, { _id: { $in: ctxIds } });
   const statuses = new Map((await client.findAll("core:class:Status", {})).map((s) => [s._id, s.name]));
   const names2 = await peopleNames(client);
+  const seen = /* @__PURE__ */ new Map();
   const out = [`# Inbox triage \u2014 ${unread.length}${unread.length === 500 ? "+" : ""} unread on ${groups.size} item(s)${groups.size > limit ? `, newest ${limit} shown` : ""}`];
   for (const ctxId of ctxIds) {
     const notes = groups.get(ctxId);
@@ -97342,10 +97349,23 @@ var triageInbox = wrapToolHandler(async (args) => {
     const comments = msgs.filter((m) => typeof m.message === "string" && (m._class === "chunter:class:ChatMessage" || h.isDerived(m._class, "chunter:class:ChatMessage")));
     const fields = [...new Set(msgs.filter((m) => m._class === C.DocUpdateMessage).map((m) => m.action === "create" ? "created" : m.attributeUpdates?.attrKey === "attachedTo" ? "parent" : m.attributeUpdates?.attrKey).filter((k) => k != null && !["rank", "subIssues", "comments", "modifiedOn"].includes(k)))];
     if (fields.length > 0) out.push(`- changed: ${fields.join(", ")}`);
-    for (const m of comments.slice(0, 3).reverse()) out.push(`- \u{1F4AC} **${who.get(m.createdBy) ?? "?"}**: ${clip(plain(m.message), 200, "list_comments")}`);
+    for (const m of comments.slice(0, 3).reverse()) {
+      const text3 = plain(m.message);
+      const author = who.get(m.createdBy) ?? "?";
+      const key = `${author}\0${text3.slice(0, 160)}`;
+      const first = seen.get(key);
+      if (first != null) {
+        first.count++;
+        out.push(`- \u{1F4AC} **${author}**: _same comment as on ${first.where}_`);
+        continue;
+      }
+      seen.set(key, { line: out.length, where: label2.split(/[:\s]/)[0], count: 1 });
+      out.push(`- \u{1F4AC} **${author}**: ${clip(text3, 200, "list_comments")}`);
+    }
     if (comments.length > 3) out.push(`- _${comments.length - 3} older new comment(s)_`);
     if (fields.length === 0 && comments.length === 0) out.push("- (no details recorded)");
   }
+  for (const f of seen.values()) if (f.count > 1) out[f.line] += ` _(same on ${f.count} items)_`;
   out.push("", "_Done with an item? mark_notifications_read with its id (e.g. PROJ-12)._");
   return out.join("\n");
 });
@@ -97541,7 +97561,7 @@ var ListComponentsSchema = external_exports.object({
 var CreateComponentSchema = external_exports.object({
   workspace: WorkspaceArg,
   projectIdentifier: external_exports.string().describe("Project key"),
-  label: external_exports.string().min(1),
+  label: external_exports.string().min(1).describe("Component name"),
   description: external_exports.string().optional(),
   lead: external_exports.string().optional().describe("Person name")
 });
@@ -97586,7 +97606,7 @@ var GetDocumentSchema = external_exports.object({
 var CreateDocumentSchema = external_exports.object({
   workspace: WorkspaceArg,
   teamspaceId: external_exports.string().describe("Teamspace id"),
-  title: external_exports.string().min(1),
+  title: external_exports.string().min(1).describe("Document title"),
   parentId: external_exports.string().optional().describe("Parent document id; omit for top-level")
 });
 var SearchIssuesSchema = external_exports.object({
@@ -97606,7 +97626,7 @@ var ListLabelsSchema = external_exports.object({
 });
 var CreateLabelSchema = external_exports.object({
   workspace: WorkspaceArg,
-  title: external_exports.string().min(1),
+  title: external_exports.string().min(1).describe("Label name"),
   color: external_exports.string().optional().describe("Hex color, e.g. #FF6B6B")
 });
 var AddLabelSchema = external_exports.object({
@@ -98500,7 +98520,7 @@ var TOOLS = [
   { name: "undo_changes", toolset: "core", description: "Undo your last changes made through this server: created \u2192 removed, changed \u2192 old values, deleted \u2192 restored. Dry run first", schema: UndoChangesSchema, handler: undoChanges },
   { name: "check_setup", toolset: "core", description: "Diagnose the setup: version and updates, login, workspaces, front URL, settings (no secrets)", schema: CheckSetupSchema, handler: checkSetup },
   { name: "list_projects", toolset: "tracker", description: "List all projects in a Huly workspace", schema: ListProjectsSchema, handler: listProjects },
-  { name: "get_project", toolset: "tracker", description: 'Get a project by its identifier (e.g. "PROJ")', schema: GetProjectSchema, handler: getProject },
+  { name: "get_project", toolset: "tracker", description: 'Project by key (e.g. "PROJ"): name, description, issue count, statuses', schema: GetProjectSchema, handler: getProject },
   { name: "create_project", toolset: "tracker-admin", description: "Create a tracker project", schema: CreateProjectSchema, handler: createProject },
   { name: "update_project", toolset: "tracker-admin", description: "Update project name, description, default assignee/status", schema: UpdateProjectSchema, handler: updateProject },
   { name: "list_issues", toolset: "tracker", description: "List issues of a project; filters: status, priority, milestone, component, label, assignee, parent", schema: ListIssuesSchema, handler: listIssues },
@@ -98513,12 +98533,12 @@ var TOOLS = [
   { name: "list_sub_issues", toolset: "tracker", description: "Sub-issue tree of an issue with progress", schema: ListSubIssuesSchema, handler: listSubIssues },
   { name: "add_comment", toolset: "tracker", description: "Add a comment to an issue", schema: AddCommentSchema, handler: addComment },
   { name: "list_comments", toolset: "tracker", description: "List comments of an issue (with ids)", schema: ListCommentsSchema, handler: listComments },
-  { name: "delete_comment", toolset: "tracker", description: "Delete a comment by id", schema: DeleteCommentSchema, handler: deleteComment },
+  { name: "delete_comment", toolset: "tracker", description: "Permanently delete a comment on an issue (commentId from list_comments); to edit: update_comment", schema: DeleteCommentSchema, handler: deleteComment },
   { name: "update_comment", toolset: "tracker", description: "Edit a comment by id", schema: UpdateCommentSchema, handler: updateComment },
   { name: "log_time", toolset: "tracker", description: "Log hours spent on an issue", schema: LogTimeSchema, handler: logTime },
   { name: "list_time_reports", toolset: "tracker", description: "Logged time for an issue or project, totals per person; person/date filters", schema: ListTimeReportsSchema, handler: listTimeReports },
   { name: "list_labels", toolset: "tracker", description: "List all labels in the workspace", schema: ListLabelsSchema, handler: listLabels },
-  { name: "create_label", toolset: "tracker", description: "Create a new label with an optional hex color", schema: CreateLabelSchema, handler: createLabel },
+  { name: "create_label", toolset: "tracker", description: "Create a workspace-wide label (optional hex color); an existing title is reused. Tag an issue: add_label", schema: CreateLabelSchema, handler: createLabel },
   { name: "add_label", toolset: "tracker", description: "Add label to issue (auto-creates label)", schema: AddLabelSchema, handler: addLabel },
   { name: "remove_label", toolset: "tracker", description: "Remove a label from an issue", schema: RemoveLabelSchema, handler: removeLabel },
   { name: "update_label", toolset: "tracker-admin", description: "Rename/recolor a label (on every issue)", schema: UpdateLabelSchema, handler: updateLabel },
@@ -98536,14 +98556,14 @@ var TOOLS = [
   { name: "update_milestone", toolset: "tracker", description: "Update a milestone (name, target date, status, description)", schema: UpdateMilestoneSchema, handler: updateMilestone },
   { name: "delete_milestone", toolset: "tracker-admin", description: "Delete milestone; its issues are unassigned or moved (moveIssuesTo)", schema: DeleteMilestoneSchema, handler: deleteMilestone },
   { name: "list_components", toolset: "tracker", description: "List components (sub-areas) in a project", schema: ListComponentsSchema, handler: listComponents },
-  { name: "create_component", toolset: "tracker", description: "Create a new component in a project", schema: CreateComponentSchema, handler: createComponent },
+  { name: "create_component", toolset: "tracker", description: "Create a component (sub-area) in a project; issues get it via componentLabel. Change it: update_component", schema: CreateComponentSchema, handler: createComponent },
   { name: "update_component", toolset: "tracker", description: "Update a component (name, description, lead)", schema: UpdateComponentSchema, handler: updateComponent },
   { name: "delete_component", toolset: "tracker-admin", description: "Delete component; its issues are unassigned or moved (moveIssuesTo)", schema: DeleteComponentSchema, handler: deleteComponent },
-  { name: "list_teamspaces", toolset: "documents", description: "List all document teamspaces in the workspace", schema: ListTeamspacesSchema, handler: listTeamspaces },
+  { name: "list_teamspaces", toolset: "documents", description: "List document teamspaces with their ids (teamspaceId for list_documents, create_document)", schema: ListTeamspacesSchema, handler: listTeamspaces },
   { name: "create_teamspace", toolset: "documents", description: "Create a document teamspace", schema: CreateTeamspaceSchema, handler: createTeamspace },
   { name: "list_documents", toolset: "documents", description: "List documents in a teamspace", schema: ListDocumentsSchema, handler: listDocuments },
   { name: "get_document", toolset: "documents", description: "Document metadata and content", schema: GetDocumentSchema, handler: getDocument },
-  { name: "create_document", toolset: "documents", description: "Create a new document in a teamspace", schema: CreateDocumentSchema, handler: createDocument },
+  { name: "create_document", toolset: "documents", description: "Create an empty document in a teamspace, optionally under a parent; returns its id. Write the body with update_document", schema: CreateDocumentSchema, handler: createDocument },
   { name: "delete_document", toolset: "documents", description: "Permanently delete a document by its ID", schema: DeleteDocumentSchema, handler: deleteDocument },
   { name: "update_document", toolset: "documents", description: "Replace content (Markdown), rename or move a document", schema: UpdateDocumentSchema, handler: updateDocument },
   { name: "list_document_comments", toolset: "collaboration", description: "Comments on a document", schema: ListDocumentCommentsSchema, handler: listDocumentComments },
@@ -98557,11 +98577,11 @@ var TOOLS = [
   { name: "list_messages", toolset: "chat", description: "List messages in a channel or direct message", schema: ListMessagesSchema, handler: listMessages },
   { name: "attach_file", toolset: "tracker", description: "Attach a file to an issue (base64-encoded content)", schema: AttachFileSchema, handler: attachFile },
   { name: "list_attachments", toolset: "tracker", description: "List files attached to an issue", schema: ListAttachmentsSchema, handler: listAttachments },
-  { name: "delete_attachment", toolset: "tracker", description: "Delete a file attachment from an issue", schema: DeleteAttachmentSchema, handler: deleteAttachment },
+  { name: "delete_attachment", toolset: "tracker", description: "Permanently delete a file attached to an issue (attachmentId from list_attachments)", schema: DeleteAttachmentSchema, handler: deleteAttachment },
   { name: "list_issue_statuses", toolset: "tracker", description: "List all issue statuses (workflow states), grouped by phase", schema: ListIssueStatusesSchema, handler: listIssueStatuses },
   { name: "create_issue_status", toolset: "tracker-admin", description: "Create a workspace-wide issue status", schema: CreateIssueStatusSchema, handler: createIssueStatus },
   { name: "list_organizations", toolset: "contacts", description: "List all organizations (companies) in the workspace", schema: ListOrganizationsSchema, handler: listOrganizations },
-  { name: "get_organization", toolset: "contacts", description: "Get details of an organization, including description", schema: GetOrganizationSchema, handler: getOrganization },
+  { name: "get_organization", toolset: "contacts", description: "Organization (company) by id from list_organizations: city, linked members, description", schema: GetOrganizationSchema, handler: getOrganization },
   { name: "create_organization", toolset: "contacts", description: "Create a new organization (company contact)", schema: CreateOrganizationSchema, handler: createOrganization },
   { name: "update_organization", toolset: "contacts", description: "Set the description of an organization from Markdown", schema: UpdateOrganizationSchema, handler: updateOrganization },
   // Chat: threads, editing, reactions, pins (channel messages and issue comments)
@@ -98569,9 +98589,9 @@ var TOOLS = [
   { name: "reply_to_message", toolset: "chat", description: "Reply in the thread of a message or comment", schema: ReplyToMessageSchema, handler: replyToMessage },
   { name: "update_message", toolset: "chat", description: "Edit a message or thread reply", schema: UpdateMessageSchema, handler: updateMessage },
   { name: "delete_message", toolset: "chat", description: "Delete a message or thread reply", schema: DeleteMessageSchema, handler: deleteMessage },
-  { name: "add_reaction", toolset: "chat", description: "React to a message/comment with an emoji", schema: ReactionSchema, handler: addReaction },
+  { name: "add_reaction", toolset: "chat", description: "Add your emoji reaction to a message or comment (no-op if already there); undo: remove_reaction", schema: ReactionSchema, handler: addReaction },
   { name: "remove_reaction", toolset: "chat", description: "Remove your emoji reaction", schema: ReactionSchema, handler: removeReaction },
-  { name: "pin_message", toolset: "chat", description: "Pin or unpin a message", schema: PinMessageSchema, handler: pinMessage },
+  { name: "pin_message", toolset: "chat", description: "Pin a message or comment in its channel; pinned=false unpins", schema: PinMessageSchema, handler: pinMessage },
   // Inbox
   { name: "list_notifications", toolset: "inbox", description: "Your inbox notifications, grouped by issue/PR/document", schema: ListNotificationsSchema, handler: listNotifications },
   { name: "triage_inbox", toolset: "inbox", description: "Unread items with what changed since last read: new comments, fields, status", schema: TriageInboxSchema, handler: triageInbox },
@@ -98580,7 +98600,7 @@ var TOOLS = [
   // Activity
   { name: "get_activity", toolset: "activity", description: "Change history and comments of an issue or object", schema: GetActivitySchema, handler: getActivity },
   // Planner
-  { name: "list_todos", toolset: "planner", description: "Your planner to-dos", schema: ListTodosSchema, handler: listTodos },
+  { name: "list_todos", toolset: "planner", description: "List your own planner to-dos: open by default, in planner order; filter by status or due date", schema: ListTodosSchema, handler: listTodos },
   { name: "create_todo", toolset: "planner", description: "Create a to-do, optionally on an issue", schema: CreateTodoSchema, handler: createTodo },
   { name: "update_todo", toolset: "planner", description: "Update a to-do or mark it done", schema: UpdateTodoSchema, handler: updateTodo },
   { name: "delete_todo", toolset: "planner", description: "Delete a to-do", schema: DeleteTodoSchema, handler: deleteTodo },
@@ -98616,7 +98636,7 @@ var TOOLS = [
   { name: "find_project_for_repo", toolset: "agent", description: "Huly workspace + project linked to a GitHub repo", schema: FindProjectForRepoSchema, handler: findProjectForRepo },
   { name: "release_issue", toolset: "agent", description: "Release an agent claim", schema: ReleaseIssueSchema, handler: releaseIssue },
   // Generic access to any class
-  { name: "search", toolset: "generic", description: "Fulltext search across everything (issues, docs, messages, cards, files \u2026)", schema: SearchAllSchema, handler: searchAll },
+  { name: "search", toolset: "generic", description: "Fulltext search across all content (issues, docs, messages, cards, files \u2026); issues only, with status: search_issues", schema: SearchAllSchema, handler: searchAll },
   { name: "list_classes", toolset: "generic", description: "Huly data classes (for modules without dedicated tools)", schema: ListClassesSchema, handler: listClasses },
   { name: "describe_class", toolset: "generic", description: "Attributes and types of a class", schema: DescribeClassSchema, handler: describeClass },
   { name: "query_documents", toolset: "generic", description: "Read documents of any class (secrets redacted)", schema: QueryDocumentsSchema, handler: queryDocuments },
@@ -98888,7 +98908,13 @@ var import_core49 = __toESM(require_lib4());
 var DONE = /* @__PURE__ */ new Set([import_task7.default.statusCategory.Won, import_task7.default.statusCategory.Lost]);
 async function myOpenIssues(limit = 30) {
   const out = [];
-  for (const ws2 of await listWorkspaces()) {
+  let workspaces;
+  try {
+    workspaces = await listWorkspaces();
+  } catch {
+    return [];
+  }
+  for (const ws2 of workspaces) {
     try {
       const client = await getConnection(ws2.url);
       const me = await currentPerson(client);
@@ -99144,7 +99170,7 @@ function createServer(options = {}) {
   if (enabled.has("agent")) instructions += `
 - Guides: resources huly://guide/workflow, huly://guide/costs, huly://guide/onboarding, huly://guide/features; prompt "setup" writes a project's Huly rules.`;
   if (dynamic) instructions = instructions.replace("- Missing tools may be in a disabled toolset (HULY_TOOLSETS).", "- More tools (calendar, cards, drive, testing, recruiting, \u2026) load on demand: enable_toolsets.");
-  const server = new McpServer({ name: "huly-mcp-selfhost", version: "3.5.0" }, { instructions });
+  const server = new McpServer({ name: "huly-mcp-selfhost", version: "3.6.0" }, { instructions });
   const asker = elicitationAsker(server);
   const registered = /* @__PURE__ */ new Map();
   for (const tool of TOOLS) {
@@ -99217,6 +99243,15 @@ var ARG_ALIASES = {
   component: "componentLabel",
   milestone: "milestoneLabel"
 };
+var TOOL_ARG_ALIASES = {
+  get_milestone: { milestoneLabel: "label", milestone: "label" },
+  update_milestone: { milestoneLabel: "label", milestone: "label" },
+  update_component: { componentLabel: "label", component: "label" }
+};
+function aliasTarget(tool, name2, known) {
+  const target = TOOL_ARG_ALIASES[tool]?.[name2] ?? ARG_ALIASES[name2];
+  return target != null && known.has(target) ? target : void 0;
+}
 function normalizeArguments(tool, args, known) {
   const out = {};
   const unknown2 = [];
@@ -99225,8 +99260,8 @@ function normalizeArguments(tool, args, known) {
       out[k] = v;
       continue;
     }
-    const target = ARG_ALIASES[k];
-    if (target != null && known.has(target) && !(target in args)) {
+    const target = aliasTarget(tool, k, known);
+    if (target != null && !(target in args)) {
       out[target] = v;
       continue;
     }
@@ -104381,7 +104416,7 @@ function buildArgs(tool, parsed, io) {
       continue;
     }
     const name2 = camel(rawName);
-    const target = byName.has(name2) ? name2 : ARG_ALIASES[name2] != null && byName.has(ARG_ALIASES[name2]) ? ARG_ALIASES[name2] : void 0;
+    const target = byName.has(name2) ? name2 : aliasTarget(tool.name, name2, new Set(byName.keys()));
     if (target == null) {
       const flags = params.filter((p) => p.name !== "workspace").map((p) => `--${kebab(p.name)}`);
       const hint = closest(`--${rawName}`, flags);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huly-mcp-selfhost",
-  "version": "3.5.0",
-  "description": "MCP server for Huly (self-hosted and Huly Cloud): 224 tools for Claude and other AI agents — issues, epics, documents, chat, planner, test management — with toolsets for low token use, an agent workflow and a Claude Code plugin.",
+  "version": "3.6.0",
+  "description": "MCP server for Huly (self-hosted and Huly Cloud): 227 tools for Claude and other AI agents — issues, epics, documents, chat, planner, test management — with toolsets for low token use, an agent workflow and a Claude Code plugin.",
   "keywords": [
     "huly",
     "huly-selfhost",
@@ -47,7 +47,8 @@
     "start": "node dist/index.js",
     "setup": "node scripts/setup.js",
     "prepublishOnly": "npm run build",
-    "test": "node --import tsx --test test/*.test.ts"
+    "test": "node --import tsx --test test/*.test.ts",
+    "mcpb": "node scripts/mcpb.js"
   },
   "dependencies": {},
   "devDependencies": {