@firfi/huly-mcp 0.1.61 → 0.3.0

package/README.md

@@ -144,6 +144,7 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 *Auth: Provide either `HULY_EMAIL` + `HULY_PASSWORD` or `HULY_TOKEN`.
 
 <!-- tools:start -->
+<!-- AUTO-GENERATED from src/mcp/tools/ descriptions. Do not edit manually. Run `pnpm update-readme` to regenerate. -->
 ## Available Tools
 
 **`TOOLSETS` categories:** `projects`, `issues`, `comments`, `milestones`, `documents`, `storage`, `attachments`, `contacts`, `channels`, `calendar`, `time tracking`, `search`, `activity`, `notifications`, `workspace`, `cards`, `labels`, `tag-categories`, `test-management`
@@ -154,6 +155,7 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 |------|-------------|
 | `list_projects` | List all Huly projects. Returns projects sorted by name. Supports filtering by archived status. |
 | `get_project` | Get full details of a Huly project including its statuses. Returns project name, description, archived flag, default status, and all available statuses. |
+| `list_statuses` | List all issue statuses for a Huly project with category info. Returns status name, isDone, isCanceled, and isDefault flags. Use this to discover valid statuses before creating or updating issues. |
 | `create_project` | Create a new Huly tracker project. Idempotent: returns existing project if one with the same identifier already exists (created=false). Identifier must be 1-5 uppercase alphanumeric chars starting with a letter. |
 | `update_project` | Update a Huly project. Only provided fields are modified. Set description to null to clear it. |
 | `delete_project` | Permanently delete a Huly project. All issues, milestones, and components in this project will be orphaned. This action cannot be undone. |
@@ -187,7 +189,9 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 | `remove_template_child` | Remove a child (sub-task) template from an issue template by its child ID. Get child IDs from get_issue_template response. |
 | `add_issue_relation` | Add a relation between two issues. Relation types: 'blocks' (source blocks target — pushes into target's blockedBy), 'is-blocked-by' (source is blocked by target — pushes into source's blockedBy), 'relates-to' (bidirectional link — updates both sides). targetIssue accepts cross-project identifiers like 'OTHER-42'. No-op if the relation already exists. |
 | `remove_issue_relation` | Remove a relation between two issues. Mirrors add_issue_relation: 'blocks' pulls from target's blockedBy, 'is-blocked-by' pulls from source's blockedBy, 'relates-to' pulls from both sides. No-op if the relation doesn't exist. |
-| `list_issue_relations` | List all relations of an issue. Returns blockedBy (issues blocking this one) and relations (bidirectional links) with resolved identifiers. Does NOT return issues that this issue blocks — use list_issue_relations on the target issue to see that. |
+| `list_issue_relations` | List all relations of an issue. Returns blockedBy (issues blocking this one), relations (bidirectional issue links), and documents (linked documents with title/teamspace). Does NOT return issues that this issue blocks — use list_issue_relations on the target issue to see that. |
+| `link_document_to_issue` | Link a Huly document to an issue. The link appears in the issue's Relations panel in the UI. Idempotent: no-op if the document is already linked. Use list_issue_relations to see linked documents. |
+| `unlink_document_from_issue` | Remove a document link from an issue. Idempotent: no-op if the document is not linked. |
 
 ### Comments
 
@@ -220,8 +224,9 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 | `delete_teamspace` | Permanently delete a Huly document teamspace. This action cannot be undone. |
 | `list_documents` | List documents in a Huly teamspace. Returns documents sorted by modification date (newest first). Supports searching by title substring (titleSearch) and content (contentSearch). |
 | `get_document` | Retrieve full details for a Huly document including markdown content. Use this to view document content and metadata. |
-| `create_document` | Create a new document in a Huly teamspace. Content supports markdown formatting. Returns the created document id. |
-| `edit_document` | Edit an existing Huly document. Two content modes (mutually exclusive): (1) 'content' for full replace, (2) 'old_text' + 'new_text' for targeted search-and-replace. Multiple matches error unless replace_all is true. Empty new_text deletes matched text. Also supports renaming via 'title'. |
+| `create_document` | Create a new document in a Huly teamspace. Content supports full markdown including native Mermaid diagrams (```mermaid blocks render interactively in Huly UI). Returns the created document id. Use link_document_to_issue to associate the document with a tracker issue. |
+| `edit_document` | Edit an existing Huly document. Two content modes (mutually exclusive): (1) 'content' for full replace, (2) 'old_text' + 'new_text' for targeted search-and-replace. Multiple matches error unless replace_all is true. Empty new_text deletes matched text. Also supports renaming via 'title'. Content supports full markdown including native Mermaid diagrams. |
+| `list_inline_comments` | List inline comment threads from a Huly document. Extracts comments embedded in document content as ProseMirror marks. Each comment includes the highlighted text and thread ID. Set includeReplies=true to also fetch thread reply messages with sender names. |
 | `delete_document` | Permanently delete a Huly document. This action cannot be undone. |
 
 ### Storage
@@ -418,3 +423,67 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 
 <!-- tools:end -->
 
+## Troubleshooting
+
+### Passwords with special characters
+
+If your Huly password contains characters like `*`, `%`, `!`, or `#`, passing it via the CLI `-e` flag may fail because the shell interprets these characters before they reach the process.
+
+**Solution**: Edit your MCP config file directly instead of using `claude mcp add -e`. In `~/.claude.json` (user scope) or `.mcp.json` (project scope), JSON handles all special characters natively:
+
+```json
+{
+  "mcpServers": {
+    "huly": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["path/to/dist/index.cjs"],
+      "env": {
+        "HULY_URL": "https://your-huly-instance.com",
+        "HULY_EMAIL": "you@example.com",
+        "HULY_PASSWORD": "p@ss*w0rd!#%",
+        "HULY_WORKSPACE": "your-workspace"
+      }
+    }
+  }
+}
+```
+
+Alternatively, use `HULY_TOKEN` instead of email/password to bypass password auth entirely (see [Environment Variables](#environment-variables)).
+
+### MCP client shows "Failed to reconnect"
+
+After changing MCP configuration, some clients (including Claude Code) require a full restart — not just a reconnect. Exit the application completely and reopen it.
+
+You can verify the connection works independently with:
+```bash
+claude mcp list  # Should show "Connected"
+```
+
+### Self-hosted Huly: account locked after failed login attempts
+
+Huly locks password login after 5 failed API authentication attempts. This commonly happens during initial setup when the password is misconfigured. The lock persists in the database across service restarts.
+
+**Symptoms**: `PasswordLoginLocked` error from the MCP server, and the Huly web UI shows "Password login is locked due to too many failed attempts. Please use an OTP login method to unlock your account." (OTP won't work without SMTP configured.)
+
+**Fix** — reset the lock counter in CockroachDB:
+
+```bash
+# Find your account UUID and check lock status
+docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
+  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
+  -e "SELECT uuid, failed_login_attempts FROM global_account.account;"
+
+# Reset the counter
+docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
+  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
+  -e "UPDATE global_account.account SET failed_login_attempts = 0 WHERE uuid = '<your_account_uuid>';"
+```
+
+The CockroachDB credentials can be found in your Huly `compose.yml` or via `docker exec <cockroach_container> env | grep COCKROACH`.
+
+### Windows-specific notes
+
+- **Bash wrapper scripts** (sourcing `.env` files) may not work reliably when launched by MCP clients on Windows. Prefer setting env vars directly in the MCP config JSON.
+- **Docker pulls over SSH** may fail on Windows due to credential manager issues. Pull images from the server desktop if needed.
+