huly-mcp-selfhost 3.3.0 → 3.5.0

package/.env.example

@@ -27,6 +27,14 @@ HULY_PASSWORD=your-password
 # Host names clients use to reach the container (reverse proxy / public name),
 # comma-separated. Without it only localhost is accepted (421 "Invalid Host header").
 # MCP_ALLOWED_HOSTS=huly-mcp.example.com,huly-mcp.example.com:443
+# Docker: the server's own HTTP endpoint (/mcp) instead of mcp-proxy — persistent sessions,
+# one Huly login per person via X-Huly-Token or X-Huly-Email/X-Huly-Password headers.
+# MCP_TRANSPORT=http
+# Bearer token clients must send; required to use the HULY_* login above over HTTP.
+# MCP_AUTH_TOKEN=
+# "Log in with Huly" (OAuth): people add <MCP_PUBLIC_URL>/mcp in their AI app and log in in the browser.
+# MCP_OAUTH_SECRET=   # openssl rand -hex 32
+# MCP_PUBLIC_URL=https://huly-mcp.example.com
 
 # ─── Single workspace (optional) ─────────────────────────────────────────────
 # Pin this server to one workspace (slug, name or id). Tools then take no
@@ -46,6 +54,9 @@ HULY_PASSWORD=your-password
 # Tool annotations (title, read-only / destructive) for clients that use them; ~16% larger tool list.
 # HULY_ANNOTATIONS=1
 
+# Connect at start-up so the first call is fast (default on); 0 = connect on the first call.
+# HULY_PREWARM=0
+
 # ─── Guard rails for agents (optional) ───────────────────────────────────────
 # Only allow changes in these projects (reads are never blocked):
 # HULY_WRITE_PROJECTS=TSK,WEB

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to [huly-mcp-selfhost](https://www.npmjs.com/package/huly-mcp-selfhost). Versions follow [semver](https://semver.org).
 
+### 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.
+- **Fixed: `check_setup` in HTTP/OAuth sessions** reported "No credentials" — it read the server's environment instead of the session's own login. Found while testing OAuth from Claude Code.
+- **Install size: 126 MB → 4.3 MB.** The package is now one bundled, readable file (`dist/index.js`, esbuild, not minified) with no runtime dependencies — the first `npx huly-mcp-selfhost` downloads 900 kB instead of ~180 packages. Verified from a clean install of the packed tarball: MCP over stdio, CLI, reads (issues, documents via the front service, reports, search, inbox, drive), writes with undo, HTTP with header login and OAuth. `huly-mcp-setup` still works (now a small wrapper for `huly-mcp setup`).
+- **Fixed: `create_issue_tree` dropped the epic's component, milestone and status** — the epic only took title, description, priority and labels; anything else was silently ignored (and the dry run did not show it). The epic now takes `componentLabel`, `milestoneLabel`, `assignee` and `statusName` (children get `statusName` too), the top-level `componentLabel`/`milestoneLabel` defaults apply to the epic as well, and the dry run lists them.
+- **Fixed: unknown fields in nested objects are rejected instead of dropped** — in `create_issue_tree`, issue templates, test cases, persons, inventory variants and generic writes. A test keeps every tool that way.
+- **New: log in with Huly (OAuth)** — with `MCP_OAUTH_SECRET` and `MCP_PUBLIC_URL`, the HTTP server is an OAuth 2.1 server: people add `…/mcp` in Claude Code, Claude's custom connectors or another OAuth-capable client and log in in the browser with their own Huly account (password, or a one-time e-mail code for Google/GitHub accounts). Stateless (AES-256-GCM sealed registrations, codes and tokens — no database, survives restarts); the password is never stored; 1-hour access tokens, rotating 30-day refresh tokens, login throttling, PKCE and client registration from the MCP SDK. Verified live against a self-hosted Huly, including Claude Code's own OAuth flow (client registration, browser login, tools as that person).
+- **New: `undo_changes`** — undo your last changes made through this server, newest first: created objects are removed, changed fields get their old values, deleted objects come back with the same id and data (verified live: an issue deleted and restored with its description). Dry run by default; an object someone else changed since is skipped and named (`force` overrides). Works for every write tool without per-tool code — writes are recorded as their reverse while a tool runs; issue counters are never wound back. History per process (stdio) or per session (HTTP), last 50 changes.
+- **New: command line for every tool** — `huly-mcp <tool> --param value` (or `npx huly-mcp-selfhost …`): `tools` to search, `help <tool>` with types, allowed values and defaults generated from the same schemas the MCP server uses; values read by type, lists by repeating a flag, JSON for nested values, `--input`/`--json`, `--<param>-file`; a positional value for tools with one required parameter; the same write scope, audit log and confirmation (hard-to-undo tools ask in a terminal, scripts need `--yes`); `--format json`; exit codes 0/1/2 with "did you mean" hints; bash/zsh completion for tools, options and values. Verified live (read, JSON output, create with a description from a file, guarded delete).
+
+### 3.4.0 — 2026-11-11
+
+- **New: team server over HTTP** — `huly-mcp-selfhost http` (Docker: `MCP_TRANSPORT=http`) serves MCP at `/mcp` with persistent sessions instead of a proxy. Every client can bring its own Huly login (`X-Huly-Token` or `X-Huly-Email`/`X-Huly-Password`, optional `X-Huly-Workspace`), so one server works for a whole team and each person acts as themselves. The server's own login is only used behind `MCP_AUTH_TOKEN`. Measured: first call of a session ~0.2 s.
+- **New: `check_setup`** — one call that diagnoses the setup: version and newer releases, login (incl. API-token expiry), workspaces, front URL, active settings; never prints secrets.
+- **New: `manage_notifications`** — for one object: pin/unpin, hide/unhide, mark unread, unarchive, follow/unfollow. Verified live.
+- **Huly API tokens** (Settings → API tokens) work as `HULY_TOKEN`: the server stays in the token's workspace, checks the expiry before connecting and explains expired or revoked tokens. Built from Huly's source; not yet tested against a live server that issues such tokens.
+- **`list_issues`: two new filters** — `title` (title contains text, case-insensitive) and `due` (`overdue`, `set`, `none`). Both run as one query on the server and combine with all other filters. Verified live on a self-hosted instance.
+- **Faster first call:** the server logs in and opens the workspace (when there is only one, e.g. pinned with `HULY_WORKSPACE`) in the background right after start-up. Measured on a self-hosted instance: first `list_issues` 4.4 s → 0.17 s; start-up itself unchanged. `HULY_PREWARM=0` turns it off; a failed login is reported by the first real call as before.
+- **Fixed: MCP registry entry.** The `server.json` description was longer than the registry's 100 characters, so 3.3.0 was refused there; a test now checks the length and the release workflow warns when the registry refuses an entry.
+- **Docs:** clearer positioning ("Huly for AI agents"), a table of measured token costs and a measured comparison with another popular Huly MCP server (2.9× less text per answer, 14× smaller tool definitions) in the README.
+
 ### 3.3.0 — 2026-11-11
 
 - **Claude Code plugin: `/huly:setup`** — the agent asks once per repo how Huly is used there (role, where new issues go, initiative, how token-saving) and writes the answers as a `## Huly` section; every later session follows it. You choose where: `CLAUDE.md` (shared), `CLAUDE.local.md` (only you; added to `.gitignore` if needed) or split — shared rules in `CLAUDE.md`, initiative and efficiency in `CLAUDE.local.md`. The project and its GitHub sync are detected first, so only the questions that matter are asked; "Not now" writes nothing. Optional import: status set, components, milestones, TODO/FIXME proposals, architecture document. The session-start hook reads the rules from all three files and offers `/huly:setup` while a repo has none.

package/README.md

@@ -3,22 +3,66 @@
 [![npm](https://img.shields.io/npm/v/huly-mcp-selfhost?label=npm)](https://www.npmjs.com/package/huly-mcp-selfhost)
 [![CI](https://github.com/JoKeks2023/huly-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/JoKeks2023/huly-mcp/actions/workflows/ci.yml)
 [![Docker Pulls](https://img.shields.io/docker/pulls/jokeks2023/huly-mcp)](https://hub.docker.com/r/jokeks2023/huly-mcp)
-[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.jokeks2023%2Fhuly--mcp--selfhost-blue)](https://registry.modelcontextprotocol.io)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.JoKeks2023%2Fhuly--mcp--selfhost-blue)](https://registry.modelcontextprotocol.io)
 [![License: EPL-2.0](https://img.shields.io/badge/license-EPL--2.0-blue)](https://github.com/JoKeks2023/huly-mcp/blob/main/LICENSE)
 
-**The MCP server for [Huly](https://huly.io) — self-hosted or Huly Cloud.** Let Claude and other AI agents work in your Huly workspaces: issues, epics, milestones, documents, chat, inbox, planner, test management and more — 224 tools, built to spend as few tokens as possible.
+**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-224-total-grouped-in-toolsets) · [Claude Code plugin](#claude-code-plugin) · [Changelog](https://github.com/JoKeks2023/huly-mcp/blob/main/CHANGELOG.md)
+[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)
 
 ## Highlights
 
 - **Everything in Huly:** tracker, documents, chat, inbox, activity, planner, calendar, GitHub PRs, contacts, drive, cards, templates, test management, recruiting, CRM, HR and more — plus read access to *any* Huly class.
 - **Made for agents:** one-call overviews (`my_day`, `standup`, `project_report`, `get_issue_context`), `start_work` → `finish_work`, plans → epics with sub-issues, specs and meeting notes → issues, claims for parallel agents, and `huly-mcp watch` to hand issues to Claude from Huly.
-- **Few tokens:** tools come in toolsets (default ≈10k tokens, everything ≈23k), optionally loaded on demand; pin a workspace for −10 %; compact outputs; wrong parameters are rejected with the valid list instead of silently ignored.
-- **Safe by default:** every change names its workspace, risky tools ask first, writes can be limited to projects, optional audit log.
+- **Few tokens:** tools come in toolsets (default ≈11k tokens, everything ≈24k), optionally loaded on demand; pin a workspace for −10 %; compact outputs; wrong parameters are rejected with the valid list instead of silently ignored.
+- **Safe by default:** every change names its workspace, risky tools ask first, writes can be limited to projects, optional audit log — and `undo_changes` reverses your last changes.
+- **Small and quick to install:** one self-contained package of ~4 MB (900 kB download) — no 180 dependencies to fetch on the first `npx`.
+- **No telemetry.** The server talks to your Huly server and nothing else: no analytics, no usage tracking, nothing to opt out of. (The only other request, the npm version check, runs when you call `check_setup`.)
 - **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.
 
+## 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 |
+| 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 |
+| My day (calendar, to-dos, my issues, PRs, inbox) | ~1,200 | 0.3k |
+
+Lists default to open items, empty fields are left out, and one call answers what would otherwise take four or five. Per call and question: [`costs.md`](https://github.com/JoKeks2023/huly-mcp/blob/main/plugin/skills/huly/costs.md).
+
+### Compared with another popular Huly MCP server
+
+<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">
+</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.
+
+<details>
+<summary>All numbers (characters)</summary>
+
+| Question | huly-mcp-selfhost | Other server | Ratio |
+|---|--:|--:|--:|
+| Open issues of a project | 2,768 (1 call) | 11,601 (3 calls) | 4.2× less |
+| Issues in progress | 211 (1 call) | 790 (1 call) | 3.7× less |
+| One issue | 318 (1 call) | 585 (1 call) | 1.8× less |
+| Everything about an issue (fields, sub-issues, comments, relations) | 1,246 (1 call) | 3,585 (4 calls) | 2.9× less |
+| Search | 406 (1 call) | 1,405 (1 call) | 3.5× less |
+| Projects | 550 (1 call) | 1,041 (1 call) | 1.9× less |
+| 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 |
+
+</details>
+
 ## Quick start
 
 You need Node.js 20+ and a Huly account — [Huly Cloud](https://huly.app) or self-hosted.
@@ -55,7 +99,7 @@ Then run `/huly:setup` in a repository. Details: [Claude Code plugin](#claude-co
 
 Config file locations and examples for each client: [Compatible clients](#compatible-clients).
 
-**Server for a team or remote clients** — run the Docker image (HTTP/SSE on port 8000): see [Docker](#docker).
+**Server for a team or remote clients** — `huly-mcp-selfhost http` or the Docker image; everyone logs in with their own Huly account in the browser (OAuth): see [Team server over HTTP](#team-server-over-http).
 
 Then ask: *"What's on my plate today?"*, *"Plan the login redesign as an epic in WEB"*, *"Write release notes for v1.2"*. More in [Example prompts](#example-prompts).
 
@@ -70,7 +114,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.3.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.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`.
 
 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).
 
@@ -91,7 +135,31 @@ Without the plugin, the same server works in Claude Code as a plain MCP server (
 
 ---
 
-## Tools (224 total, grouped in toolsets)
+## 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).
+
+```bash
+npm install -g huly-mcp-selfhost          # or: npx huly-mcp-selfhost <command>
+
+huly-mcp tools issue                      # find tools
+huly-mcp help list_issues                 # parameters, types, allowed values, defaults
+huly-mcp get_issue PROJ-12                # one required parameter can be given directly
+huly-mcp list_issues --project PROJ --due overdue --assignee null
+huly-mcp create_issue -w acme --project PROJ --title "Fix login" --description-file notes.md
+huly-mcp bulk_update_issues --identifiers PROJ-1 --identifiers PROJ-2 --status-name Done --yes
+huly-mcp my_day --format json | jq -r .text
+```
+
+- **Parameters** come from the same schemas the MCP server sends to Claude, so `help` is always current. Names work as `--project-identifier` or `--projectIdentifier`; common short forms (`--project`, `--status`, `--milestone`, …) too. Values are read by type: numbers, `true`/`false`, `null` to clear, repeat a flag for lists, JSON for nested values. `--json '{…}'` or `--input file.json` (`-` = stdin) pass everything at once; `--<text-param>-file` reads a text value from a file.
+- **Hard-to-undo tools** (deletes, bulk changes, moves) ask in a terminal; in scripts they run only with `--yes`.
+- **Exit codes:** 0 ok · 1 the tool failed or was cancelled · 2 wrong usage (unknown tool or option — with a "did you mean …").
+- **Output:** the tool's Markdown; `--format json` gives `{"ok", "tool", "text"}` (errors too). The Huly SDK's own logging is silenced; `HULY_DEBUG=1` shows it on stderr.
+- **Shell completion** for tools, options and allowed values: `eval "$(huly-mcp completion zsh)"` (or `bash`) in your shell profile.
+
+---
+
+## 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.
 
@@ -101,7 +169,7 @@ Every tool schema is sent to the model in each session (Claude Desktop loads all
 
 ```bash
 HULY_TOOLSETS=all                       # everything
-HULY_TOOLSETS=tracker,documents,planner # just these ('core' = list_workspaces is always on)
+HULY_TOOLSETS=tracker,documents,planner # just these ('core' = list_workspaces, check_setup and undo_changes, always on)
 ```
 
 **Load on demand** (`HULY_DYNAMIC_TOOLSETS=1`): `HULY_TOOLSETS` becomes the starting set, and Claude loads more toolsets itself via `enable_toolsets`. Called without arguments, it lists every toolset with its tools; called with names, it loads them and tells the client that the tool list changed. With `HULY_TOOLSETS=agent,inbox` a session starts at ≈1.8k tokens instead of ≈9–11k. This needs a client that reloads the tool list on `notifications/tools/list_changed`: it is tested with the MCP SDK client, but **not yet verified in Claude Desktop**. Without the variable, nothing changes.
@@ -113,7 +181,7 @@ HULY_TOOLSETS=tracker,documents,planner # just these ('core' = list_workspaces i
 | `documents` | ✓ | 8 | teamspaces and documents (tree, move, rename) |
 | `chat` | ✓ | 12 | channels, DMs, threads, edit/delete, reactions, pins |
 | `contacts` | ✓ | 11 | members, organizations, persons, contact channels |
-| `inbox` | ✓ | 3 | notifications, triage (what changed since last read), mark read/archive |
+| `inbox` | ✓ | 4 | notifications, triage (what changed since last read), mark read/archive; pin, hide, mark unread, follow/unfollow per object |
 | `activity` | ✓ | 1 | change history of an issue/object |
 | `planner` | ✓ | 5 | to-dos, time blocking |
 | `generic` | ✓ | 4 | fulltext search across everything, read any Huly class |
@@ -140,10 +208,10 @@ HULY_TOOLSETS=tracker,documents,planner # just these ('core' = list_workspaces i
 
 Context cost of `tools/list` (≈3.5 chars/token):
 
-| | default (96 tools) | `all` (224 tools) |
+| | default (99 tools) | `all` (227 tools) |
 |---|--:|--:|
-| several workspaces | ~36.5k chars ≈ **10.4k tokens** | ~81.6k chars ≈ **23.3k tokens** |
-| pinned with `HULY_WORKSPACE` | ~33k chars ≈ **9.4k tokens** | ~73.3k chars ≈ **20.9k tokens** |
+| 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** |
 
 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.
 
@@ -223,11 +291,13 @@ Options: `--run <name>`, `--parent-suite <suite>`, `--no-create` (only existing
 | Category | Tool | Description |
 |----------|------|-------------|
 | **Workspaces** | `list_workspaces` | List the workspaces this account can access (name, slug, id) |
+| | `undo_changes` | Undo your last changes made through this server, newest first: what was created is removed, changed fields get their old values, deleted objects come back with the same id and data. Dry run by default; skips (and says so) when someone changed the object since — `force` overrides. Covers every write tool; history per process (stdio) or per session (HTTP), last 50 changes |
+| | `check_setup` | Diagnose the setup in one call: version and whether a newer one exists, login (incl. API-token expiry), workspaces, front URL reachable, active settings — never prints secrets |
 | **Projects** | `list_projects` | List all projects in a workspace |
 | | `get_project` | Get project details + available statuses |
 | | `create_project` | Create a new tracker project with a unique identifier *(tracker-admin)* |
 | | `update_project` | Change name, description, default assignee or default status *(tracker-admin)* |
-| **Issues** | `list_issues` | List issues — open ones by default (`status: "all"` or a status name for others), filterable by priority, milestone, component, label, assignee, parent; `offset` pages through long lists ("51–100 of 118") |
+| **Issues** | `list_issues` | List issues — open ones by default (`status: "all"` or a status name for others), filterable by priority, milestone, component, label, assignee, parent (`null` = none for each), text in the title and due date (`overdue`, `set`, `none`); `offset` pages through long lists ("51–100 of 118") |
 | | `get_issue` | Full details of an issue (e.g. `PROJ-42`): assignee, milestone, component, labels, parent, links |
 | | `create_issue` | Create a new issue (with optional Markdown description) |
 | | `update_issue` | Update title, description, status, priority, assignee, due date, component, milestone |
@@ -303,6 +373,7 @@ Options: `--run <name>`, `--parent-suite <suite>`, `--no-create` (only existing
 | **Inbox** (`inbox`) | `list_notifications` | Your notifications, grouped by issue/PR/document |
 | | `triage_inbox` | Work through the inbox in one call: per unread item its status and assignee, which fields changed and the new comments (plain text, shortened) since you last read it |
 | | `mark_notifications_read` | Mark read by object, ids or all; optionally archive |
+| | `manage_notifications` | For one object: `pin`/`unpin`, `hide`/`unhide`, `unread`, `unarchive`, `follow`/`unfollow` (follow = its changes reach your inbox) |
 | **Activity** (`activity`) | `get_activity` | Who changed what, plus comments, for an issue or object |
 | **Planner** (`planner`) | `list_todos` | Your to-dos (open/done, due date filter) |
 | | `create_todo` | Create a to-do, optionally attached to an issue |
@@ -399,6 +470,11 @@ A single Huly account can belong to several workspaces — e.g. a personal one a
 | `HULY_AGENT_NAME` | no | Default agent name for `claim_issue` (default `claude`) |
 | `HULY_CONFIRM` | no | `auto` (default), `strict` or `off` — ask before deletes and other risky tools (see [Agent workflow](#agent-workflow)) |
 | `HULY_FILE_ROOT` | no | Directory for local files: `upload_file` (`localPath`) and `download_file` (`savePath`) only work inside it. Off when unset — the server may run remotely |
+| `MCP_TRANSPORT` | no | Docker only: `http` = the server's own HTTP endpoint (`/mcp`, per-user logins) instead of mcp-proxy (see [Team server over HTTP](#team-server-over-http)) |
+| `MCP_OAUTH_SECRET` | no | HTTP mode: turns on "log in with Huly" (OAuth); at least 32 characters, e.g. `openssl rand -hex 32` (see [Team server over HTTP](#team-server-over-http)) |
+| `MCP_PUBLIC_URL` | with OAuth | The HTTPS address clients reach the server at (issuer and login page), e.g. `https://huly-mcp.example.com` |
+| `MCP_AUTH_TOKEN` | no | HTTP mode: bearer token every client must send; required before the server's own `HULY_*` login is used over HTTP |
+| `HULY_PREWARM` | no | `0` turns off connecting at start-up. By default the server logs in (and opens the workspace when there is only one) right after it starts, so the first tool call answers in well under a second instead of 4–12 s |
 | `HULY_SUBSCRIBE_POLL_MS` | no | How often subscribed `huly://` resources are checked for changes (default 30000, minimum 5000) |
 
 ---
@@ -433,6 +509,10 @@ A token copied from the browser (DevTools → Application → Local Storage →
 
 > Tokens expire after some time. If you get an auth error, run `npx huly-mcp-selfhost setup` again or switch to email + password.
 
+**Option C — API token (Huly → Settings → API tokens; in Huly's development branch since 2026-08, not yet in every release or self-hosted install):** bound to one workspace, with an expiry date, revocable without changing your password — the best choice for agents and CI. Use it as `HULY_TOKEN`. The server keeps it to its own workspace (even where Huly itself would allow switching), checks the expiry up front, and `check_setup` warns two weeks before it runs out. Tested against Huly's token format, not yet against a live server that issues such tokens.
+
+**Something not working?** Ask Claude to run `check_setup`: version (and whether a newer one exists), login, workspaces, whether the front URL is reachable and which settings are active — without printing secrets.
+
 **Self-hosted Huly:**
 
 ```bash
@@ -627,7 +707,7 @@ For network access (HTTP/SSE) use the [Docker image](#docker).
 
 ### npx (recommended)
 
-Every client example uses `"command": "npx", "args": ["-y", "huly-mcp-selfhost"]`. Pin a version (`huly-mcp-selfhost@3.3.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.5.0`) if you want updates only when you choose.
 
 ### From source
 
@@ -657,6 +737,33 @@ docker compose up -d
 
 The container wraps the server with [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy) to expose it over HTTP/SSE at `:8000/sse`, since standard MCP stdio transport can't be reached over a network directly. **Behind a reverse proxy or on a public hostname, set `MCP_ALLOWED_HOSTS`** to the host name(s) clients use, e.g. `MCP_ALLOWED_HOSTS=huly-mcp.example.com`. Otherwise mcp-proxy only accepts `localhost` and answers `421 Invalid Host header`. See [`Dockerfile`](https://github.com/JoKeks2023/huly-mcp/blob/main/Dockerfile) / [`docker-compose.yml`](https://github.com/JoKeks2023/huly-mcp/blob/main/docker-compose.yml).
 
+### Team server over HTTP
+
+`huly-mcp-selfhost http` serves MCP over Streamable HTTP at `/mcp` (health check `/healthz`) — no proxy, one long-lived session per client, so logins and connections are reused (the first call of a session takes ~0.2 s). In Docker: `MCP_TRANSPORT=http`.
+
+```bash
+npx huly-mcp-selfhost http --host 0.0.0.0 --port 8000
+```
+
+**Everyone with their own Huly account.** A client sends its own login as headers; the session then acts as that person:
+
+```bash
+claude mcp add --transport http huly https://huly-mcp.example.com/mcp \
+  --header "X-Huly-Token: <your token>"            # or X-Huly-Email + X-Huly-Password
+  # optional: --header "X-Huly-Workspace: acme"    # pin one workspace (fewer tokens)
+```
+
+**Log in with Huly (OAuth).** Set `MCP_OAUTH_SECRET` (`openssl rand -hex 32`) and `MCP_PUBLIC_URL` (the HTTPS address clients reach, e.g. `https://huly-mcp.example.com`). Then people simply add `https://huly-mcp.example.com/mcp` in their AI app — Claude Code (`claude mcp add --transport http huly …`), Claude's custom connectors and other OAuth-capable MCP clients — and log in in the browser with their own Huly account: e-mail + password, or a one-time code by e-mail for Google/GitHub accounts. One server, as many people as you like, nobody handles tokens.
+
+- Stateless: registrations, codes and tokens are sealed with AES-256-GCM under `MCP_OAUTH_SECRET` — no database, logins survive restarts. Changing the secret logs everyone out.
+- The Huly password goes only to your Huly server; the server keeps just the resulting Huly token, inside the sealed tokens. Access tokens last 1 hour, refresh tokens 30 days and work once (rotation). Login attempts are throttled per address.
+- The protocol parts (client registration, PKCE, token endpoint, metadata) are the MCP SDK's own; this server adds the login page and the tokens.
+- `X-Huly-Workspace` still pins a workspace. In OAuth mode `/mcp` needs the OAuth token; `MCP_AUTH_TOKEN` and the `X-Huly-*` login headers are for the other mode.
+
+**One shared account.** The server's own `HULY_*` login is only used behind a bearer token — set `MCP_AUTH_TOKEN` and give clients `Authorization: Bearer <token>`. Without it an open port would act as that account, so the server refuses and asks for per-user headers instead. With `MCP_AUTH_TOKEN` set, every request needs the bearer token, also when it brings its own login.
+
+Set `MCP_ALLOWED_HOSTS` to the host names clients use (DNS-rebinding protection). Use HTTPS (reverse proxy) as soon as logins travel over a network. Idle sessions close after 30 minutes.
+
 ---
 
 ## Example prompts
@@ -839,6 +946,8 @@ See [`src/connection.ts`](https://github.com/JoKeks2023/huly-mcp/blob/main/src/c
 npm ci && npm run build && npm test
 ```
 
+`npm run build` type-checks (`tsc --noEmit`) and bundles `src/` with all dependencies into one readable file, `dist/index.js` (esbuild, not minified), plus `dist/guides/`. The published package therefore has no runtime dependencies; everything in `package.json` is a dev dependency. Tests run on the TypeScript sources (`tsx`).
+
 GitHub Actions check every pull request:
 
 | Workflow | What it checks |
@@ -878,13 +987,13 @@ See [CHANGELOG.md](https://github.com/JoKeks2023/huly-mcp/blob/main/CHANGELOG.md
 
 ## 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 224, with self-hosted support, toolsets, agent workflow and the Claude Code plugin. Published separately as `huly-mcp-selfhost`. Not affiliated with Huly Labs.
+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.
 
 ## Links
 
 - Website: https://jokeks2023.github.io/huly-mcp/
 - Source and issues: https://github.com/JoKeks2023/huly-mcp
-- 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`
+- 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)
 
 ## License

package/dist/guides/costs.md

@@ -12,12 +12,13 @@ Every Huly call costs a round trip and its output stays in context. Aim for **on
 | Everything about PROJ-12 before working on it | `get_issue_context` | ~1.3k | `get_issue` + `list_sub_issues` + `list_comments` + relations (4+ calls) |
 | Status/assignee of PROJ-12 | `get_issue` | ~0.4k | `get_issue_context` |
 | What changed? | `changes_since` with `projectIdentifiers` and a short `since` | — | whole workspace for 7d: ~8k |
+| Inbox housekeeping for one object (pin, hide, unread, follow) | `manage_notifications` | small | several updates |
 | What needs my attention? | `triage_inbox` with a small `limit` | ~4k at 10 | `list_notifications` + `get_issue` per item |
 | What's in release v1.2? | `release_notes` | ~2k | `list_issues milestoneLabel=…` + reading every issue |
 | Find issues about X | `search_issues` | ~2k | `list_issues status=all` and scanning |
 | Find anything (docs, chat, issues) | `search` | ~2.5k | several list calls |
 
-**Narrow lists with filters, not by reading them:** `list_issues` takes `status` (`open` default, `all`, or a name), `assignee` (`null` = unassigned), `milestoneLabel`, `componentLabel`, `labelName`, `parentIdentifier` (`null` = top level) and `limit`.
+**Narrow lists with filters, not by reading them:** `list_issues` takes `status` (`open` default, `all`, or a name), `assignee` (`null` = unassigned), `milestoneLabel`, `componentLabel`, `labelName`, `parentIdentifier` (`null` = top level), `title` (contains text), `due` (`overdue`, `set`, `none`) and `limit`.
 
 **Avoid** `query_documents` / generic tools when a specific tool exists: one issue there is ~1.8k raw fields vs ~0.4k from `get_issue`. Use them only for classes without a tool.
 

package/dist/guides/workflow.md

@@ -19,7 +19,7 @@ Keep Huly current as you work, in the same turn as the action. Every call costs
 | Everything about PROJ-12 | `get_issue_context` (just status/assignee: `get_issue`) |
 | Find something | `search_issues`, `search` — not `list_issues status=all` |
 
-Narrow lists with filters (`status`, `assignee`, `milestoneLabel`, `componentLabel`, `parentIdentifier`, `limit`). More questions with measured sizes: [costs.md](costs.md).
+Narrow lists with filters (`status`, `assignee`, `milestoneLabel`, `componentLabel`, `parentIdentifier`, `title`, `due: overdue`, `limit`). More questions with measured sizes: [costs.md](costs.md).
 
 ## 2. Pick up and hand back
 
@@ -52,6 +52,8 @@ Narrow lists with filters (`status`, `assignee`, `milestoneLabel`, `componentLab
 ## 5. Be careful with
 
 - Bulk changes, `move_issue`, deletes: show what will change first.
+- A change went wrong: `undo_changes` (dry run first) reverses your last changes through this server — don't repair by hand.
 - GitHub-synced projects: every change appears on GitHub too; don't cross-post.
 - `HULY_WRITE_PROJECTS` refusals: tell the user, don't work around them.
+- Huly calls fail with login/connection errors: run `check_setup` and show the user what it says.
 - A tool you need is missing: it is in a disabled toolset — `enable_toolsets` if available, otherwise tell the user which toolset to enable ([features.md](features.md)).