@firfi/huly-mcp 0.12.0 → 0.14.0

package/README.md

@@ -30,6 +30,36 @@ The standard configuration works with most MCP clients:
 }
 ```
 
+<details>
+<summary>Codex</summary>
+
+Use Codex's MCP manager:
+
+```bash
+codex mcp add huly \
+  --env HULY_URL=https://huly.app \
+  --env HULY_EMAIL=your@email.com \
+  --env HULY_PASSWORD=yourpassword \
+  --env HULY_WORKSPACE=yourworkspace \
+  -- npx -y @firfi/huly-mcp@latest
+```
+
+Or add it directly to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.huly]
+command = "npx"
+args = ["-y", "@firfi/huly-mcp@latest"]
+
+[mcp_servers.huly.env]
+HULY_URL = "https://huly.app"
+HULY_EMAIL = "your@email.com"
+HULY_PASSWORD = "yourpassword"
+HULY_WORKSPACE = "yourworkspace"
+```
+
+</details>
+
 <details>
 <summary>Claude Code</summary>
 
@@ -59,7 +89,7 @@ Add the standard config to your `claude_desktop_config.json`:
 <details>
 <summary>VS Code</summary>
 
-Add to your user settings (`.vscode/mcp.json`) or use Command Palette → "MCP: Add Server":
+Add with Command Palette → "MCP: Add Server", or put this in a VS Code MCP config such as `.vscode/mcp.json`. Do not commit workspace config files that contain real credentials.
 
 ```json
 {
@@ -94,16 +124,42 @@ Add the standard config to your Windsurf MCP configuration file.
 
 </details>
 
+<details>
+<summary>OpenCode</summary>
+
+Open the global configuration file (`~/.config/opencode/opencode.json`) and merge this entry into your config:
+
+```json
+{
+  "mcp": {
+    "huly": {
+      "type": "local",
+      "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
+      "environment": {
+        "HULY_URL": "https://huly.app",
+        "HULY_EMAIL": "your@email.com",
+        "HULY_PASSWORD": "yourpassword",
+        "HULY_WORKSPACE": "yourworkspace"
+      }
+    }
+  }
+}
+```
+
+</details>
+
 ## Updating
 
-The `@latest` tag in the install command always fetches the newest version. Most MCP clients cache the installed package, so you need to force a re-fetch:
+The `@latest` tag asks the package runner for the newest version. Some MCP clients keep server processes or resolved installs alive, so restart or re-add the server when updating:
 
 | Client | How to update |
 |--------|--------------|
+| **Codex** | `codex mcp remove huly` then re-add with the install command above. If your password has shell-sensitive characters, edit `~/.codex/config.toml` directly instead |
 | **Claude Code** | `claude mcp remove huly` then re-add with the install command above |
 | **Claude Desktop** | Restart the app (it runs `npx` on startup) |
-| **VS Code / Cursor** | Restart the MCP server from the command palette or reload the window |
-| **npx (manual)** | `npx -y @firfi/huly-mcp@latest` — the `-y` flag skips the cache when `@latest` resolves to a new version |
+| **VS Code / Cursor** | Restart the MCP server from the command palette/configured client or reload the window |
+| **OpenCode** | Restart OpenCode or start a new session after config changes |
+| **npx (manual)** | `npx -y @firfi/huly-mcp@latest` — the `-y` flag auto-confirms install prompts |
 
 ## HTTP Transport
 
@@ -147,7 +203,7 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 <!-- 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`, `custom-fields`, `labels`, `leads`, `tag-categories`, `task-management`, `test-management`
+**`TOOLSETS` categories:** `projects`, `issues`, `comments`, `milestones`, `documents`, `storage`, `attachments`, `contacts`, `channels`, `calendar`, `time tracking`, `search`, `activity`, `notifications`, `workspace`, `cards`, `custom-fields`, `labels`, `leads`, `processes`, `tag-categories`, `task-management`, `test-management`
 
 ### Projects
 
@@ -167,8 +223,8 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 | `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_issues` | Query Huly issues with optional filters. Returns issues sorted by modification date (newest first). Supports filtering by project, status, assignee, component, and parentIssue (to list children of a specific issue). Supports searching by title substring (titleSearch) and description content (descriptionSearch). |
 | `get_issue` | Retrieve full details for a Huly issue including markdown description. Use this to view issue content, comments, or full metadata. |
-| `create_issue` | Create a new issue in a Huly project. Optionally create as a sub-issue by specifying parentIssue. Description supports markdown formatting. Returns the created issue identifier. |
-| `update_issue` | Update fields on an existing Huly issue. Only provided fields are modified. Description updates support markdown. |
+| `create_issue` | Create a new issue in a Huly project. 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. Optionally create as a sub-issue by specifying parentIssue. Description supports markdown formatting. Returns the created issue identifier. |
+| `update_issue` | Update fields on an existing Huly issue. 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. |
 | `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. |
@@ -189,7 +245,7 @@ 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), 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. |
+| `list_issue_relations` | List all relations of an issue. Returns blockedBy (issues blocking this one), blocks (issues this one blocks), relations (bidirectional issue links), and documents (linked documents with title/teamspace). |
 | `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. |
 
@@ -332,7 +388,7 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 
 | Tool | Description |
 |------|-------------|
-| `list_activity` | List activity messages for a Huly object. Returns activity sorted by date (newest first). |
+| `list_activity` | List activity messages for a Huly issue, document, channel, or raw Huly object. Prefer friendly targets: project+issueIdentifier for issues, teamspace+document for documents, or channel for channels. Advanced callers may pass objectId+objectClass directly. Returns activity sorted by date (newest first). |
 | `add_reaction` | Add an emoji reaction to an activity message. |
 | `remove_reaction` | Remove an emoji reaction from an activity message. |
 | `list_reactions` | List reactions on an activity message. |
@@ -412,6 +468,14 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 | `list_leads` | Query Huly leads in a funnel with optional filters. Pass the funnel ID returned by list_funnels, or a funnel name for convenience lookup. Returns leads sorted by modification date (newest first). Supports filtering by status, assignee, and title search. |
 | `get_lead` | Retrieve full details for a Huly lead including markdown description, customer name, funnel ID and funnel name, and status. Lead identifiers follow the upstream Huly format like 'LEAD-1'. |
 
+### Processes
+
+| Tool | Description |
+|------|-------------|
+| `list_processes` | List read-only Huly Process workflow definitions. Optionally filter by the master tag/card type that workflows attach to. Returns process IDs, names, attached card type, automation flags, and state/transition counts. |
+| `get_process` | Get one Huly Process workflow definition by process ID or exact display name. If a name is ambiguous, the tool returns a typed error with candidate IDs instead of guessing. |
+| `list_process_executions` | List read-only Huly Process workflow executions. Supports filters by process ID/name, card/document ID/title, and status. Rows are enriched with process name, card title, and current state title when available. |
+
 ### Tag-Categories
 
 | Tool | Description |
@@ -471,17 +535,26 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 
 ### 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.
+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.
 
-**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:
+**Solution**: Edit your MCP config file directly instead of passing the password through the shell:
+
+- Codex: `~/.codex/config.toml`
+- Claude Code: `~/.claude.json` (user scope) or `.mcp.json` (project scope)
+- Claude Desktop: `claude_desktop_config.json` in the location listed in the installation section
+- VS Code and Cursor: use the client config location from the installation section; avoid committing workspace files that contain real credentials
+- Windsurf: edit your Windsurf MCP configuration file directly
+- OpenCode: `~/.config/opencode/opencode.json`
+
+For Claude JSON config, the shell-sensitive characters above can be written directly. JSON-reserved characters such as `"` and `\` still need normal JSON escaping:
 
 ```json
 {
   "mcpServers": {
     "huly": {
       "type": "stdio",
-      "command": "node",
-      "args": ["path/to/dist/index.cjs"],
+      "command": "npx",
+      "args": ["-y", "@firfi/huly-mcp@latest"],
       "env": {
         "HULY_URL": "https://your-huly-instance.com",
         "HULY_EMAIL": "you@example.com",