@firfi/huly-mcp 0.55.0 → 0.55.2

package/README.md

@@ -45,6 +45,7 @@ The standard configuration uses a Huly API token and works with most MCP clients
       "command": "npx",
       "args": ["-y", "@firfi/huly-mcp@latest"],
       "env": {
+        "MCP_TRANSPORT": "stdio-resident",
         "HULY_URL": "https://your-huly-instance.example.com",
         "HULY_TOKEN": "your-huly-api-token",
         "HULY_WORKSPACE": "yourworkspace"
@@ -73,6 +74,7 @@ Use Codex's MCP manager:
 
 ```bash
 codex mcp add huly \
+  --env MCP_TRANSPORT=stdio-resident \
   --env HULY_URL=https://your-huly-instance.example.com \
   --env HULY_TOKEN=your-huly-api-token \
   --env HULY_WORKSPACE=yourworkspace \
@@ -85,8 +87,10 @@ Or add it directly to `~/.codex/config.toml`:
 [mcp_servers.huly]
 command = "npx"
 args = ["-y", "@firfi/huly-mcp@latest"]
+startup_timeout_sec = 60
 
 [mcp_servers.huly.env]
+MCP_TRANSPORT = "stdio-resident"
 HULY_URL = "https://your-huly-instance.example.com"
 HULY_TOKEN = "your-huly-api-token"
 HULY_WORKSPACE = "yourworkspace"
@@ -99,6 +103,7 @@ HULY_WORKSPACE = "yourworkspace"
 
 ```bash
 claude mcp add huly \
+  -e MCP_TRANSPORT=stdio-resident \
   -e HULY_URL=https://your-huly-instance.example.com \
   -e HULY_TOKEN=your-huly-api-token \
   -e HULY_WORKSPACE=yourworkspace \
@@ -131,6 +136,7 @@ Add with Command Palette → "MCP: Add Server", or put this in a VS Code MCP con
       "command": "npx",
       "args": ["-y", "@firfi/huly-mcp@latest"],
       "env": {
+        "MCP_TRANSPORT": "stdio-resident",
         "HULY_URL": "https://your-huly-instance.example.com",
         "HULY_TOKEN": "your-huly-api-token",
         "HULY_WORKSPACE": "yourworkspace"
@@ -168,6 +174,7 @@ Open the global configuration file (`~/.config/opencode/opencode.json`) and merg
       "type": "local",
       "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
       "environment": {
+        "MCP_TRANSPORT": "stdio-resident",
         "HULY_URL": "https://your-huly-instance.example.com",
         "HULY_TOKEN": "your-huly-api-token",
         "HULY_WORKSPACE": "yourworkspace"
@@ -206,7 +213,7 @@ The `@latest` tag asks the package runner for the newest version. Some MCP clien
 | **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 |
 | **Pi** | Run `/mcp reconnect huly`, then `/reload` if the registered direct-tool surface changed |
-| **npx (manual)** | `npx -y @firfi/huly-mcp@latest` — the `-y` flag auto-confirms install prompts |
+| **npx (manual)** | `MCP_TRANSPORT=stdio-resident npx -y @firfi/huly-mcp@latest` — the `-y` flag auto-confirms install prompts |
 
 ## Maintainer Production Release
 
@@ -220,6 +227,15 @@ Use this exact command even when a newer Node.js version is active on the host.
 exact Node.js versions certified by CI; this is intentionally narrower than the package's runtime requirement. See
 the [production release guide](docs/NPM_PRODUCTION_RELEASE.md) for preflight checks, rerun behavior, and verification.
 
+## Shared resident stdio
+
+The setup examples explicitly select `MCP_TRANSPORT=stdio-resident`. MCP clients still use stdio, while compatible clients under the same OS user share a Node backend through small native bridges. Linux and macOS arm64/x64 binaries are included; no Rust installation is needed. Resident startup has a 30-second budget. If the native bridge cannot run or resident startup fails, the connection automatically falls back to ordinary stdio with its buffered MCP input preserved. This transition happens before any MCP request is sent to the resident. A failed active resident never reconnects or replays requests.
+
+Allow at least 60 seconds for MCP startup in the client so it can wait for the resident attempt, cleanup, and ordinary stdio startup. For Codex, set `startup_timeout_sec = 60` in its Huly server configuration, including when adding the server through `codex mcp add`.
+For Claude Code, set `MCP_TIMEOUT=60000` in the environment that launches `claude`, or add `"MCP_TIMEOUT": "60000"` under `env` in `~/.claude/settings.json` ([Claude Code environment variables](https://code.claude.com/docs/en/env-vars)). Setting it only in the Huly server's `env` does not increase the parent client's startup timeout.
+
+Omitting `MCP_TRANSPORT` still selects ordinary `stdio`, preserving existing installations. Set `MCP_TRANSPORT=stdio` explicitly to keep a separate backend per client. Restart the MCP client after changing the setting.
+
 ## Manual resident backend
 
 The experimental [manual resident backend path](docs/resident-manual.md) lets
@@ -270,7 +286,7 @@ Authorization: Bearer <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.
+Save a profile with `huly auth login --profile work`, then set `MCP_TRANSPORT=stdio-resident` and `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
 
@@ -299,7 +315,7 @@ For a Smithery publish schema example, see [docs/SMITHERY_URL_PUBLISH.md](docs/S
 | `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` |
+| `MCP_TRANSPORT` | No | Transport type: `stdio` (package default), `stdio-resident` (recommended in setup examples), or `http` |
 | `MCP_PRELOAD_TOOLS` | No | Load every tool handler before serving requests. Defaults to `false`; use `true` for smoke tests that check all handler imports. |
 | `MCP_HTTP_PORT` | No | HTTP server port (falls back to `PORT`, then 3000) |
 | `MCP_HTTP_HOST` | No | HTTP server host. Omit to bind to the package default loopback host. |
@@ -1204,6 +1220,22 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 
 <!-- tools:end -->
 
+## Building from source
+
+Published packages include the native resident bridge; Rust is a build dependency.
+Source builds require Node.js, pnpm, Rustup, Python 3, and Bash. Prepare the pinned
+Rust toolchain, Zig linker, and cross-compilation SDK once:
+
+```bash
+pnpm setup:native
+pnpm build
+pnpm test:native
+```
+
+Build tools are kept in a platform-specific user cache, outside the checkout and
+published package. The bridge is a single Rust I/O loop; MCP protocol processing,
+authorization, and cancellation remain in the shared Node backend.
+
 ## Troubleshooting
 
 ### Password fallback with special characters
@@ -1229,6 +1261,7 @@ For Claude JSON config, the shell-sensitive characters above can be written dire
       "command": "npx",
       "args": ["-y", "@firfi/huly-mcp@latest"],
       "env": {
+        "MCP_TRANSPORT": "stdio-resident",
         "HULY_URL": "https://your-huly-instance.com",
         "HULY_EMAIL": "you@example.com",
         "HULY_PASSWORD": "p@ss*w0rd!#%",