@firfi/huly-mcp 0.11.0 → 0.13.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
 
@@ -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. |
 
@@ -285,6 +341,7 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-m
 | `update_channel_message` | Update a channel message. Only the body can be modified. |
 | `delete_channel_message` | Permanently delete a channel message. This action cannot be undone. |
 | `list_direct_messages` | List direct message conversations in Huly. Returns conversations sorted by date (newest first). |
+| `create_direct_message` | Open a one-to-one direct-message conversation with a workspace member. The `person` argument accepts an email or exact display name (e.g. `Smith,Bill`). Idempotent: if a DM with that participant already exists, returns it (`created: false`); otherwise creates a new DM (`created: true`). The returned `id` can be passed as `dm` to send_dm_message, list_dm_messages, etc. |
 | `list_dm_messages` | List messages in a direct-message conversation, newest first. The `dm` argument accepts either the DM `_id` or a participant display name (e.g. `Kerr,Shannon`); a name resolves only to a one-to-one DM with the authenticated account. |
 | `send_dm_message` | Send a message to a direct-message conversation. The `dm` argument accepts either the DM `_id` or a participant display name; a name resolves only to a one-to-one DM with the authenticated account. Message body supports markdown formatting. |
 | `update_dm_message` | Update a direct-message message. The `dm` argument accepts either the DM `_id` or a participant display name; a name resolves only to a one-to-one DM with the authenticated account. Only the body can be modified. |
@@ -331,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. |
@@ -470,17 +527,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",