@firfi/huly-mcp 0.52.5 → 0.53.0

package/README.md

@@ -36,7 +36,7 @@ detected executable and required version, and the same `unsupported Node.js runt
 stderr. Upgrade Node.js or configure the MCP server command to use the absolute path of a compatible Node.js
 executable, then restart the MCP server. Huly operations remain unavailable until the runtime is upgraded.
 
-The standard configuration works with most MCP clients:
+The standard configuration uses a Huly API token and works with most MCP clients:
 
 ```json
 {
@@ -46,8 +46,7 @@ The standard configuration works with most MCP clients:
       "args": ["-y", "@firfi/huly-mcp@latest"],
       "env": {
         "HULY_URL": "https://your-huly-instance.example.com",
-        "HULY_EMAIL": "your@email.com",
-        "HULY_PASSWORD": "yourpassword",
+        "HULY_TOKEN": "your-huly-api-token",
         "HULY_WORKSPACE": "yourworkspace"
       }
     }
@@ -55,6 +54,12 @@ The standard configuration works with most MCP clients:
 }
 ```
 
+Prefer a managed API token created in Huly account settings when the target deployment supports it. Managed tokens
+are bound to one workspace, assigned an expiry, and can be revoked without changing the account password. They still
+inherit the account's full rights in that workspace, so use a dedicated integration account with only the workspace
+role, space memberships, and data access the automation needs. Older Huly deployments may not expose managed token
+settings; email/password authentication remains available as a compatibility fallback.
+
 ## Tool Exposure Defaults
 
 By default (`HULY_TOOL_MODE=auto`), Huly MCP optimizes for current MCP clients by avoiding a 470-tool eager list. Exact `claude-code` sessions receive native Huly tools. Codex, Cursor, Windsurf, Copilot, OpenCode, Claude AI/Desktop-style clients, and unknown clients receive a small proxy surface: `list_tool_categories`, `search_tools`, `get_tool_schema`, and `invoke_tool`.
@@ -69,8 +74,7 @@ Use Codex's MCP manager:
 ```bash
 codex mcp add huly \
   --env HULY_URL=https://your-huly-instance.example.com \
-  --env HULY_EMAIL=your@email.com \
-  --env HULY_PASSWORD=yourpassword \
+  --env HULY_TOKEN=your-huly-api-token \
   --env HULY_WORKSPACE=yourworkspace \
   -- npx -y @firfi/huly-mcp@latest
 ```
@@ -84,8 +88,7 @@ args = ["-y", "@firfi/huly-mcp@latest"]
 
 [mcp_servers.huly.env]
 HULY_URL = "https://your-huly-instance.example.com"
-HULY_EMAIL = "your@email.com"
-HULY_PASSWORD = "yourpassword"
+HULY_TOKEN = "your-huly-api-token"
 HULY_WORKSPACE = "yourworkspace"
 ```
 
@@ -97,8 +100,7 @@ HULY_WORKSPACE = "yourworkspace"
 ```bash
 claude mcp add huly \
   -e HULY_URL=https://your-huly-instance.example.com \
-  -e HULY_EMAIL=your@email.com \
-  -e HULY_PASSWORD=yourpassword \
+  -e HULY_TOKEN=your-huly-api-token \
   -e HULY_WORKSPACE=yourworkspace \
   -- npx -y @firfi/huly-mcp@latest
 ```
@@ -130,8 +132,7 @@ Add with Command Palette → "MCP: Add Server", or put this in a VS Code MCP con
       "args": ["-y", "@firfi/huly-mcp@latest"],
       "env": {
         "HULY_URL": "https://your-huly-instance.example.com",
-        "HULY_EMAIL": "your@email.com",
-        "HULY_PASSWORD": "yourpassword",
+        "HULY_TOKEN": "your-huly-api-token",
         "HULY_WORKSPACE": "yourworkspace"
       }
     }
@@ -168,8 +169,7 @@ Open the global configuration file (`~/.config/opencode/opencode.json`) and merg
       "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
       "environment": {
         "HULY_URL": "https://your-huly-instance.example.com",
-        "HULY_EMAIL": "your@email.com",
-        "HULY_PASSWORD": "yourpassword",
+        "HULY_TOKEN": "your-huly-api-token",
         "HULY_WORKSPACE": "yourworkspace"
       }
     }
@@ -226,8 +226,7 @@ By default, the server uses stdio transport. For HTTP transport:
 
 ```bash
 HULY_URL=https://your-huly-instance.example.com \
-HULY_EMAIL=your@email.com \
-HULY_PASSWORD=yourpassword \
+HULY_TOKEN=your-huly-api-token \
 HULY_WORKSPACE=yourworkspace \
 MCP_TRANSPORT=http \
 npx -y @firfi/huly-mcp@latest
@@ -243,7 +242,9 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 
 ### HTTP MCP Protocol Support
 
-Both stdio and HTTP implement the released MCP `2026-07-28` interface and retain SDK-owned compatibility for MCP `2025-06-18` clients. Stdio pins each connection to the protocol era selected by its opening exchange; HTTP serves legacy requests statelessly. Modern HTTP requires one JSON-RPC message per POST, `Accept: application/json, text/event-stream`, `MCP-Protocol-Version: 2026-07-28`, `Mcp-Method`, method-specific `Mcp-Name`, and per-request `_meta.io.modelcontextprotocol/*` client metadata. Huly credentials are configured separately through env vars or supported `x-huly-*` headers.
+Both transports are implemented with Effect AI's MCP server and protocol adapters. The server configures the released MCP `2026-07-28` stateless protocol and the MCP `2025-06-18` compatibility protocol. Modern HTTP requires one JSON-RPC message per POST, `Accept: application/json, text/event-stream`, `MCP-Protocol-Version: 2026-07-28`, `Mcp-Method`, method-specific `Mcp-Name`, and per-request `_meta.io.modelcontextprotocol/*` client metadata. Legacy HTTP supports initialized sessions using the returned `Mcp-Session-Id` and bare stateless calls with request-local bindings. Huly credentials are configured separately through env vars or supported `x-huly-*` headers.
+
+See [MCP transport architecture and certification](docs/MCP_TRANSPORT_CERTIFICATION.md) for the implementation boundary and the current verification record.
 
 For hosted or tunneled HTTP deployments, you can require an MCP endpoint bearer token:
 
@@ -261,6 +262,10 @@ Authorization: Bearer <MCP_AUTH_TOKEN>
 
 `MCP_AUTH_TOKEN` protects only the MCP HTTP `/mcp` endpoint. It is unrelated to `HULY_TOKEN`, does not authenticate to Huly, and does not replace `HULY_EMAIL` / `HULY_PASSWORD` / `HULY_TOKEN`. Huly credentials are still required through process env vars or, for hosted URL deployments, the supported `x-huly-*` headers. Stdio deployments do not use `MCP_AUTH_TOKEN`.
 
+### Shared CLI and stdio profiles
+
+Save a profile with `huly auth login --profile work`, then set `HULY_PROFILE=work` in the stdio MCP server's environment. Both processes must run under the same OS user and configuration directory. Stdio never follows the active CLI profile implicitly. Saved tokens are bound to their instance URL and workspace; changes require login again or complete environment credential injection. See the [CLI profile instructions](packages/huly-cli/README.md#authentication-and-profiles). HTTP configuration remains unchanged.
+
 ### Hosted HTTP Header Configuration
 
 For hosted URL deployments, keep the server process configured with `MCP_TRANSPORT=http`. A hosting layer can forward per-session Huly credentials as request headers, so one hosted server can serve different Huly workspaces without process-wide `HULY_*` env vars.
@@ -283,9 +288,9 @@ For a Smithery publish schema example, see [docs/SMITHERY_URL_PUBLISH.md](docs/S
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `HULY_URL` | Yes | Reachable self-hosted or replacement hosted Huly instance URL |
-| `HULY_EMAIL` | Auth* | Account email |
-| `HULY_PASSWORD` | Auth* | Account password |
-| `HULY_TOKEN` | Auth* | API token (alternative to email/password) |
+| `HULY_TOKEN` | Auth* | Preferred: managed Huly API token where supported |
+| `HULY_EMAIL` | Auth* | Compatibility fallback: account email |
+| `HULY_PASSWORD` | Auth* | Compatibility fallback: account password |
 | `HULY_WORKSPACE` | Yes | Workspace identifier |
 | `HULY_CONNECTION_TIMEOUT` | No | Connection timeout in ms. Omit to use the package default. |
 | `MCP_TRANSPORT` | No | Transport type: `stdio` (default) or `http` |
@@ -296,8 +301,10 @@ For a Smithery publish schema example, see [docs/SMITHERY_URL_PUBLISH.md](docs/S
 | `PROXY_OUTPUT_STRICT` | No | Proxy candidate strictness: `false` (default) keeps proxy discovery broad; `true` makes active `TOOLSETS` / `TOOLS` a hard allow-list for proxy search, schema lookup, and invocation. |
 | `TOOLSETS` | No | Comma-separated tool categories to expose. If neither `TOOLSETS` nor `TOOLS` is set, all native Huly tools are exposed. Example: `issues,projects,search` |
 | `TOOLS` | No | Comma-separated exact tool names to expose in addition to selected toolsets. Example: `list_documents,create_issue` |
+| `HULY_MCP_TELEMETRY` | No | Aggregate usage analytics (PostHog), on by default. Set `0` to disable. `DO_NOT_TRACK=1` also disables it. |
 
-*Auth: Provide either `HULY_EMAIL` + `HULY_PASSWORD` or `HULY_TOKEN`.
+*Auth: Prefer `HULY_TOKEN`. Use `HULY_EMAIL` + `HULY_PASSWORD` only when the Huly deployment does not support a
+managed API token or another compatibility constraint requires password authentication.
 
 ## Built-in Diagnostic Tools
 
@@ -369,13 +376,13 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 | `set_issue_component` | Set or clear the component on a Huly issue. Pass null for component to clear it. |
 | `delete_component` | Permanently delete a Huly component. This action cannot be undone. |
 | `list_issues` | Query Huly issues with optional filters. Returns issues sorted by modification date (newest first). Supports filtering by project, exact workflow status name (status), Huly SDK task.statusCategory key (statusCategory: UnStarted, ToDo, Active, Won, Lost), assignee (email, Person display name, or exact agent UserProfile title), creator (raw Person ID, exact email, or exact display name), component, a human-readable attached label title (label, exact and case-insensitive), milestone (project-scoped ID or exact case-insensitive label), milestone presence (hasMilestone), parentIssue (to list children of a specific issue), and isTopLevel (to return only native top-level issues). Creator, label, and milestone filters are applied before the result limit; ambiguous creator display names fail actionably and unknown creators return an empty list. Each result includes creator as a stable Person reference { id, name?, email? } when resolvable and the assigned milestone as { id, label } when resolvable. Supports searching by title substring (titleSearch) and description content (descriptionSearch). Each result includes deterministic label summaries with title and available color; missing labels are an empty array, duplicate titles collapse case-insensitively while preferring a valid color, and unusable partial attachments are omitted with a tool warning. |
-| `get_issue` | Retrieve full details for a Huly issue including markdown description, its creator as a stable Person reference { id, name?, email? } when resolvable, its assigned milestone as { id, label } when resolvable, and deterministic attached-label summaries with title and available color. Missing labels are an empty array, duplicate titles collapse case-insensitively while preferring a valid color, and unusable partial creator or label metadata is omitted with one bounded tool warning. Use this to view issue content, comments, classification, or full metadata. |
+| `get_issue` | Retrieve full details for a Huly issue including markdown description, its creator as a stable Person reference { id, name?, email? } when resolvable, its assigned milestone as { id, label } when resolvable, and deterministic attached-label summaries with title and available color. Missing labels are an empty array, duplicate titles collapse case-insensitively while preferring a valid color, and unusable partial creator or label metadata is omitted with one bounded tool warning. Use this to view issue content, comments, classification, or full metadata. identifier accepts a project-local identifier/number or stable issue ID; stable IDs resolve across the workspace after movement and return the actual project. The supplied project must exist. |
 | `create_issue` | Create a new issue in a Huly project. Assignee accepts an email, Person display name, or exact agent UserProfile title and always stores the linked Person. Omit parentIssue for a native top-level issue, or specify parentIssue to create a sub-issue. Optionally set taskType by ID or display name; it is resolved within the target project's project type, and status is validated against that task type's workflow. Use list_task_types or get_project_type to discover valid task types and statuses. Description supports markdown formatting; markdown links to current-workspace Huly browse URLs with _class, _id, and label become native references, while external URLs stay normal links. Returns the created issue identifier. |
 | `update_issue` | Update fields on an existing Huly issue. Assignee accepts an email, Person display name, or exact agent UserProfile title and always stores the linked Person; use null to unassign. Optionally set taskType by ID or display name; it is resolved within the target project's project type, and the status is preserved only when valid for the new task type. Use list_task_types or get_project_type to discover valid task types and statuses. Only provided fields are modified. Description updates support markdown; markdown links to current-workspace Huly browse URLs with _class, _id, and label become native references, while external URLs stay normal links. |
 | `add_issue_label` | Add a tag/label to a Huly issue. Creates the tag if it doesn't exist in the project. |
 | `remove_issue_label` | Remove a tag/label from a Huly issue. Detaches the label reference; does not delete the label definition. |
 | `delete_issue` | Permanently delete a Huly issue. This action cannot be undone. |
-| `move_issue` | Move an issue to a new parent (making it a sub-issue), or pass null to restore its native top-level shape. Updates parent/child relationships and sub-issue counts. |
+| `move_issue` | Move an issue tree within its project, preserving IDs, identifiers and attributes. issue/parent accept full identifiers or stable IDs; project accepts identifier or stable ID. destination forms: {project: 'HULY'} for project top level, {parent: 'HULY-42'} to infer the parent project, {project: 'HULY', parent: 'HULY-42'} requiring agreement, or {parent: null} for current project top level. Cross-project movement supports complete compatible trees with equal project types and actual supported kind/status, component/milestone references preserved when valid or matched by literal unique name; otherwise blocked with candidates for exact per-task resolutions {issueId,field,from,to}, where to is a valid destination ID or null to clear. All discoverable conflicts are returned before writes. Comments (including threads/nested attachments), issue attachments, labels, time reports and audited activity/replies/reactions follow the move; historical payloads and independent links stay intact. Unknown record classes/collection edges or discovery limits cause a pre-write refusal. Restricted projects are refused; private destinations require membership. Tree discovery follows attachments, and all task conflicts and resolutions are checked before number allocation. Consent never extends to siblings or newly discovered children. Safety limits refuse a complete move before writes; successful mappings include every task. Cross-project identifiers change; stable IDs and independent references remain. Omit resolutions for same-project calls, including no-ops. Inspects hierarchy before writes and verifies after execution; inconsistent or uncertain outcomes include inspection guidance. Never automatically retry an uncertain move. |
 | `list_issue_templates` | List issue templates in a Huly project. Templates define reusable issue configurations. Returns templates sorted by modification date (newest first). |
 | `get_issue_template` | Retrieve full details for a Huly issue template including children (sub-task templates). Use this to view template content, default values, and child template IDs. |
 | `create_issue_template` | Create a new issue template in a Huly project. Templates define default values for new issues. Template and child descriptions support markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Optionally include children (sub-task templates) that will become sub-issues when creating issues from this template. Returns the created template ID and title. |
@@ -1184,7 +1191,7 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 
 ## Troubleshooting
 
-### Passwords with special characters
+### Password fallback with special characters
 
 If your Huly password contains characters like `*`, `%`, `!`, or `#`, passing it via CLI environment flags such as `-e` or `--env` may fail because the shell interprets these characters before they reach the process.
 
@@ -1217,7 +1224,8 @@ For Claude JSON config, the shell-sensitive characters above can be written dire
 }
 ```
 
-Alternatively, use `HULY_TOKEN` instead of email/password to bypass password auth entirely (see [Environment Variables](#environment-variables)).
+Prefer `HULY_TOKEN` instead of this password fallback when the deployment supports managed API tokens (see
+[Environment Variables](#environment-variables)).
 
 ### MCP client shows "Failed to reconnect"