@firfi/huly-mcp 0.52.4 → 0.52.6

package/README.md

@@ -10,10 +10,7 @@
 
 **Huly MCP** is a feature-complete MCP server for [Huly](https://huly.io/) integration. Published on npm as [`@firfi/huly-mcp`](https://www.npmjs.com/package/@firfi/huly-mcp).
 
-It connects to any Huly Platform deployment, so it should also work with the [Platform Collective](https://github.com/Platform-Collective/platform) fork and [TraceX](https://tracex.co) — unofficial for now.
-
-> [!IMPORTANT]
-> **Hosted Huly is shutting down.** Huly's upstream README says shutdown is expected July 20. If you use `https://huly.app`, [export and migrate your data](https://github.com/hcengineering/platform/blob/develop/README.md) as soon as possible. See the [backup and restore guide](https://github.com/hcengineering/platform/blob/develop/docs/guides/backup-restore.en.md) and [self-hosting repository](https://github.com/hcengineering/huly-selfhost). Self-hosted deployments are not affected.
+It connects to Huly Platform deployments and should also work with the [Platform Collective](https://github.com/Platform-Collective/platform) and [TraceX](https://tracex.co) forks. [Intabia](https://platform.intabia.ru/) `0.8.33` / model `0.8.4` has been compatibility-tested; [known gaps are tracked in issue #279](https://github.com/dearlordylord/huly-mcp/issues/279). Fork support remains unofficial.
 
 ## Huly CLI Alternative
 
@@ -39,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
 {
@@ -49,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"
       }
     }
@@ -58,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`.
@@ -72,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
 ```
@@ -87,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"
 ```
 
@@ -100,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
 ```
@@ -133,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"
       }
     }
@@ -171,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"
       }
     }
@@ -229,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
@@ -246,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:
 
@@ -286,9 +284,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` |
@@ -300,7 +298,8 @@ For a Smithery publish schema example, see [docs/SMITHERY_URL_PUBLISH.md](docs/S
 | `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` |
 
-*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
 
@@ -362,6 +361,9 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 | Tool | Description |
 |------|-------------|
 | `preview_deletion` | Preview the impact of deleting a Huly entity before actually deleting it. Shows affected sub-entities, relations, and warnings. Supports issues, projects, components, and milestones. Use this to understand cascade effects before calling a delete operation. |
+| `list_external_tracker_targets` | List external issue-tracker targets mapped to a Huly project. Omit provider to list every provider supported by this server, or pass provider:'github' to list mapped GitHub repositories. Returns each target's provider, kind, stable Huly ID, exact name, enabled state, and an actionable unavailable reason when known. This discovers Huly configuration only; it does not call the external provider or prove that the synchronization worker is running. |
+| `publish_issue_to_external_tracker` | Request publication of an existing Huly issue as a new issue in Huly's configured external tracker. Identify the issue with project and its human identifier (for example, HULY-123); provider currently accepts only 'github'. Select target by stable Huly target ID or exact name, or omit target only when exactly one enabled target is mapped to the project. Publication is asynchronous: pending means Huly accepted the request, not that an external issue exists. Repeating the same target is safe while pending or published; a failed same-target request retries, while a different target is rejected. Use get_issue_publication_status to observe completion. |
+| `get_issue_publication_status` | Read the Huly-persisted external publication state for an issue identified by project and human issue identifier. Returns not_requested, pending, published, or failed; pending includes the ISO state-change timestamp and elapsed time, while published includes an external URL and positive issue number. A timeout is projected as failed only after the bounded wait, and later persisted publication takes precedence. This reads Huly state and never calls the external provider directly. |
 | `list_components` | List components in a Huly project. Components organize issues by area/feature. Returns components sorted by modification date (newest first). |
 | `get_component` | Retrieve full details for a Huly component. Use this to view component content and metadata. |
 | `create_component` | Create a new component in a Huly project. Components help organize issues by area/feature. Description supports 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. Returns the created component ID and label. |
@@ -1184,7 +1186,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 +1219,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"