huly-mcp-selfhost 1.0.0

package/.env.example

@@ -0,0 +1,16 @@
+# ─── Required ────────────────────────────────────────────────────────────────
+HULY_WORKSPACE=your-workspace-slug   # e.g. "myteam" from huly.app/myteam
+
+# ─── Authentication (choose ONE option) ──────────────────────────────────────
+
+# Option A — Token auth (recommended for SSO / Google / GitHub accounts)
+# Run the interactive setup wizard to get a token via email OTP:
+#   npm run setup
+# HULY_TOKEN=your-token-here
+
+# Option B — Email + password auth (only works if you set a password on huly.app)
+# HULY_EMAIL=your-email@example.com
+# HULY_PASSWORD=your-password
+
+# ─── Optional ────────────────────────────────────────────────────────────────
+# HULY_ACCOUNTS_URL=https://account.huly.app   # default shown; change for self-hosted

package/README.md

@@ -0,0 +1,522 @@
+# huly-mcp-sdk (self-hosted fork)
+
+> The most complete MCP server for [Huly](https://huly.app) — the open-source project management platform.
+
+Connects **Claude Desktop** (and any [MCP](https://modelcontextprotocol.io)-compatible client) directly to your Huly workspace. Manage projects, issues, milestones, components, documents, labels, chat, attachments, organizations, and more — all via natural language.
+
+## About this fork
+
+This is a fork of [varaprasadreddy9676/huly-mcp](https://github.com/varaprasadreddy9676/huly-mcp), built out for a **self-hosted** (`huly-selfhost`) deployment and extended well past the upstream tool set. **Not published to npm** — see [Installing this fork](#installing-this-fork) below.
+
+**Fixed vs. upstream:**
+- **Self-hosted document/description writes.** Upstream's `update_document` (and, by extension, any issue description) is hardcoded against Huly Cloud's "datalake" microservice at `dl-eu.huly.app`, which `huly-selfhost` doesn't run. This fork auto-detects self-hosted deployments via `HULY_FRONT_URL` and uploads through `front`'s own `/files` contract instead — falls back to the original Cloud behavior when `HULY_FRONT_URL` is unset. See [`src/utils/storage.ts`](src/utils/storage.ts).
+- **`description` on `create_issue`/`update_issue`.** Missing entirely upstream — issue descriptions are `MarkupBlobRef`s, same storage mechanism as document content, so this needed the same fix.
+
+**New tool categories** (upstream had 36 tools across Projects/Issues/Comments/Time/Labels/Relations/Members/Milestones/Components/Documents/Search; this fork adds 14 more):
+- **Chat** — `list_channels`, `create_channel`, `start_direct_message`, `send_message`, `list_messages`
+- **Attachments** — `attach_file`, `list_attachments`, `delete_attachment` (generic files on issues, any content type)
+- **Issue Statuses** — `list_issue_statuses`, `create_issue_status` (custom workflow states)
+- **Organizations** — `list_organizations`, `get_organization`, `create_organization`, `update_organization`
+
+**Investigated and deliberately not built:** Calendar (not a native event system in Huly — it's a Google Calendar sync bridge requiring infra this fork doesn't assume you're running) and Drive/HR/Recruiting/CRM-Leads/Board (blocked by an [upstream npm packaging bug](https://github.com/hcengineering/platform/issues/10881) — `@hcengineering/*` packages published `0.7.411`+ ship without their `types/` directory, and these modules have no earlier version to pin around it).
+
+---
+
+## Tools (50 total)
+
+| Category | Tool | Description |
+|----------|------|-------------|
+| **Projects** | `list_projects` | List all projects in the workspace |
+| | `get_project` | Get project details + available statuses |
+| | `create_project` | Create a new tracker project with a unique identifier |
+| **Issues** | `list_issues` | List issues with optional status / priority filters |
+| | `get_issue` | Get full details of an issue (e.g. `PROJ-42`) |
+| | `create_issue` | Create a new issue (with optional Markdown description) |
+| | `update_issue` | Update title, description, status, priority, assignee, due date, component, milestone |
+| | `delete_issue` | Permanently delete an issue by identifier |
+| **Comments** | `add_comment` | Add a comment to an issue |
+| | `list_comments` | List all comments on an issue (includes IDs for `delete_comment`) |
+| | `delete_comment` | Delete a specific comment by ID |
+| **Time Tracking** | `log_time` | Log hours spent on an issue |
+| **Labels** | `list_labels` | List all labels with color + usage count |
+| | `create_label` | Create a new label with an optional hex color |
+| | `add_label` | Add a label to an issue (auto-creates if it doesn't exist) |
+| | `remove_label` | Remove a label from an issue |
+| **Relations** | `add_relation` | Mark two issues as related (bidirectional) |
+| | `add_blocked_by` | Mark an issue as blocked by another issue |
+| | `set_parent` | Set or clear the parent epic of an issue |
+| **Members** | `list_members` | List workspace members |
+| **Milestones** | `list_milestones` | List milestones for a project |
+| | `create_milestone` | Create a milestone with a target date and status |
+| **Components** | `list_components` | List components (sub-areas) in a project |
+| | `create_component` | Create a new component with optional lead |
+| **Documents** | `list_teamspaces` | List document teamspaces |
+| | `create_teamspace` | Create a new teamspace (top-level document folder) |
+| | `list_documents` | List documents in a teamspace |
+| | `delete_document` | Permanently delete a document by ID |
+| | `get_document` | Get document metadata + content |
+| | `create_document` | Create a new document in a teamspace |
+| | `update_document` | Write Markdown content to a document — Mermaid diagrams render natively |
+| | `link_document` | Link a document to an issue — appears in the Relations panel |
+| **Search** | `search_issues` | Full-text search across all issues |
+| **Chat** | `list_channels` | List all channels in the workspace |
+| | `create_channel` | Create a new channel |
+| | `start_direct_message` | Start (or find) a 1:1 direct message with a workspace member |
+| | `send_message` | Send a message to a channel or direct message |
+| | `list_messages` | List messages in a channel or direct message |
+| **Attachments** | `attach_file` | Attach a file to an issue (base64-encoded content) |
+| | `list_attachments` | List files attached to an issue |
+| | `delete_attachment` | Delete a file attachment from an issue |
+| **Issue Statuses** | `list_issue_statuses` | List all issue statuses (workflow states), grouped by phase |
+| | `create_issue_status` | Create a new issue status — available in every project immediately |
+| **Organizations** | `list_organizations` | List all organizations (companies) in the workspace |
+| | `get_organization` | Get details of an organization, including description |
+| | `create_organization` | Create a new organization (company contact) |
+| | `update_organization` | Set the description of an organization from Markdown |
+
+---
+
+## Requirements
+
+- Node.js >= 20
+- A Huly account — [huly.app](https://huly.app) (cloud) or self-hosted
+
+---
+
+## Installing this fork
+
+This fork isn't published to npm — `npx huly-mcp-sdk` (the upstream package) will **not** include anything in this README past "About this fork". Clone and build instead:
+
+```bash
+git clone https://github.com/JoKeks2023/huly-mcp.git
+cd huly-mcp
+npm install
+npm run build
+```
+
+Then in any client config below, replace `"command": "npx", "args": ["huly-mcp-sdk"]` with:
+
+```json
+"command": "node",
+"args": ["/absolute/path/to/huly-mcp/dist/index.js"]
+```
+
+**Your workspace slug** is the part of your Huly URL after the domain: `huly.app/`**`myteam`** → slug is `myteam` (self-hosted: the `url` field of your workspace, e.g. `https://your-instance.com/workbench/`**`myteam`**).
+
+---
+
+## Compatible Clients
+
+The same MCP server works across all major AI coding tools. Pick your client, then swap the `npx`/`args` for the local build per [Installing this fork](#installing-this-fork) above.
+
+> **Auth note:** All config examples below use `HULY_TOKEN`. If you have issues with token expiry, use email + password instead — just replace the `env` block with:
+> ```json
+> "HULY_EMAIL": "your@email.com",
+> "HULY_PASSWORD": "yourpassword",
+> "HULY_WORKSPACE": "your-workspace-slug"
+> ```
+> See [Manual Auth](#manual-auth) for details on both options.
+
+---
+
+### Claude Desktop
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "huly": {
+      "command": "npx",
+      "args": ["huly-mcp-sdk"],
+      "env": {
+        "HULY_TOKEN": "your-token",
+        "HULY_WORKSPACE": "your-workspace-slug"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+---
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add huly -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk
+```
+
+Or scope it to a single project only:
+
+```bash
+claude mcp add huly --scope project -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk
+```
+
+Verify it's connected: `claude mcp list`
+
+---
+
+### Cursor
+
+Create or edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "huly": {
+      "command": "npx",
+      "args": ["huly-mcp-sdk"],
+      "env": {
+        "HULY_TOKEN": "your-token",
+        "HULY_WORKSPACE": "your-workspace-slug"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor. The tools appear in the Agent panel under MCP.
+
+---
+
+### Windsurf (Codeium)
+
+Create or edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "huly": {
+      "command": "npx",
+      "args": ["huly-mcp-sdk"],
+      "env": {
+        "HULY_TOKEN": "your-token",
+        "HULY_WORKSPACE": "your-workspace-slug"
+      }
+    }
+  }
+}
+```
+
+Restart Windsurf. MCP tools are available to the Cascade AI panel.
+
+---
+
+### VS Code — Cline extension
+
+1. Install the [Cline extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)
+2. Open Cline settings → **MCP Servers** → **Edit MCP Settings**
+3. Add:
+
+```json
+{
+  "huly": {
+    "command": "npx",
+    "args": ["huly-mcp-sdk"],
+    "env": {
+      "HULY_TOKEN": "your-token",
+      "HULY_WORKSPACE": "your-workspace-slug"
+    }
+  }
+}
+```
+
+---
+
+### VS Code — Continue extension
+
+1. Install the [Continue extension](https://marketplace.visualstudio.com/items?itemName=Continue.continue)
+2. Edit `~/.continue/config.json` and add to the `mcpServers` array:
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "huly",
+      "command": "npx",
+      "args": ["huly-mcp-sdk"],
+      "env": {
+        "HULY_TOKEN": "your-token",
+        "HULY_WORKSPACE": "your-workspace-slug"
+      }
+    }
+  ]
+}
+```
+
+---
+
+### Zed
+
+Edit `~/.config/zed/settings.json` and add a `context_servers` entry:
+
+```json
+{
+  "context_servers": {
+    "huly": {
+      "command": {
+        "path": "npx",
+        "args": ["huly-mcp-sdk"],
+        "env": {
+          "HULY_TOKEN": "your-token",
+          "HULY_WORKSPACE": "your-workspace-slug"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+### OpenAI Codex CLI
+
+Edit `~/.codex/config.json` and add to `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "huly": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["huly-mcp-sdk"],
+      "env": {
+        "HULY_TOKEN": "your-token",
+        "HULY_WORKSPACE": "your-workspace-slug"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Any other MCP-compatible client
+
+The server uses standard **stdio transport**. If your tool supports MCP, the config pattern is always the same:
+
+- **command:** `node`
+- **args:** `["/absolute/path/to/huly-mcp/dist/index.js"]` (see [Installing this fork](#installing-this-fork))
+- **env:** `HULY_TOKEN` + `HULY_WORKSPACE` (or `HULY_EMAIL`/`HULY_PASSWORD`; self-hosted also needs `HULY_ACCOUNTS_URL` + `HULY_FRONT_URL`, see [Manual Auth](#manual-auth))
+
+Consult your tool's MCP documentation for the exact config file location.
+
+---
+
+<img width="932" height="401" alt="image" src="https://github.com/user-attachments/assets/0f9d9a74-ca1e-4884-bd6a-918c0fb8ddbd" />
+
+## Example Prompts
+
+**Projects & issues:**
+- *"Create a new project called 'Mobile App' with identifier MOBILE"*
+- *"List all in-progress issues in the PROJ project"*
+- *"Create a high-priority issue in PROJ titled 'Fix login timeout'"*
+- *"Update PROJ-42 status to Done, assign it to Sarah, and move it to the Auth component"*
+- *"Search for issues related to authentication"*
+- *"Add a comment to PROJ-15 saying the fix is deployed"*
+- *"List all comments on PROJ-42 to see the discussion"*
+
+**Milestones & components:**
+- *"Create a milestone 'v2.0 Launch' in PROJ with target date 2026-06-01"*
+- *"List milestones for the PROJ project"*
+- *"Create a component called 'Auth' in PROJ"*
+- *"List all components in PROJ"*
+
+**Labels & relations:**
+- *"Add the label 'bug' to PROJ-42"*
+- *"Create a label called 'backend' with color #3b82f6"*
+- *"Mark PROJ-55 as blocked by PROJ-12"*
+- *"Set PROJ-42 as a subtask of PROJ-5"*
+
+**Time tracking:**
+- *"Log 2.5 hours on PROJ-42 for the database refactor"*
+
+**Documents:**
+- *"List all documents in the Engineering teamspace"*
+- *"Create a document called 'API Design' in the Engineering teamspace"*
+- *"Update the API Design document with this Markdown: ..."*
+- *"Add a Mermaid architecture diagram to the EP1 document"*
+- *"Link document abc123 to issue PROJ-42"*
+- *"Delete the second comment on PROJ-15"*
+
+---
+
+## Document Content
+
+### Reading: `get_document`
+
+`get_document` always returns full metadata (title, teamspace, comments, snapshots). To also fetch and display the **text content**, set the optional `HULY_FRONT_URL` env var:
+
+```json
+"env": {
+  "HULY_TOKEN": "...",
+  "HULY_WORKSPACE": "myteam",
+  "HULY_FRONT_URL": "https://front.huly.app"
+}
+```
+
+For **self-hosted** Huly, set `HULY_FRONT_URL` to your own front service URL (e.g. `http://localhost:8083`).
+
+### Writing: `update_document`
+
+`update_document` accepts a `documentId` and a `markdown` string and writes rich structured content directly to the document — no manual editing required.
+
+> **Self-hosted note:** Document content (and, as of this fork, issue descriptions —
+> see below) is stored as a `MarkupBlobRef` blob. Huly Cloud uploads these through a
+> dedicated "datalake" microservice at a fixed URL; `huly-selfhost` (v0.7.x) does not
+> run that service — blob storage goes through `front`'s own, older `/files` endpoint
+> instead. **If `HULY_FRONT_URL` is set, this fork uploads through that self-hosted
+> contract automatically; if it's unset, it falls back to Huly Cloud's datalake** (the
+> original, upstream behavior). No separate flag needed — `HULY_FRONT_URL` doubles as
+> the self-host/cloud switch for both reading and writing.
+
+**Supported Markdown:**
+
+| Element | Syntax |
+|---------|--------|
+| Headings | `#`, `##`, `###` |
+| Bold / inline code | `**bold**`, `` `code` `` |
+| Paragraphs | plain text |
+| Bullet lists | `- item` |
+| Pipe tables | `\| col \| col \|` |
+| Code blocks | ` ```lang ` |
+| **Mermaid diagrams** | ` ```mermaid ` — stored as Huly's native `mermaid` node type so diagrams render as interactive visuals in the editor |
+
+**Example:**
+
+```
+update_document({
+  documentId: "abc123",
+  markdown: `# Service Flow\n\n` +
+    `## Architecture\n\n` +
+    "```mermaid\n" +
+    "flowchart TD\n" +
+    "  A([User]) --> B[Browse Catalogue]\n" +
+    "  B --> C[Pay via Razorpay]\n" +
+    "  C --> D[Order Confirmed]\n" +
+    "```\n\n" +
+    "## Business Rules\n\n" +
+    "- Payment required before confirmation\n" +
+    "- All orders synced to HIS\n"
+})
+```
+
+The Mermaid block renders as a live interactive diagram in Huly's document editor — not as a code block.
+
+---
+
+## Bulk CSV Import
+
+Import many issues at once from a CSV file — useful for migrating from other tools:
+
+```bash
+node scripts/import-csv.js tasks.csv PROJ
+```
+
+**CSV format:**
+
+```csv
+title,priority,status,dueDate
+Fix login bug,High,In Progress,2025-04-01
+Add dark mode,Medium,,
+Improve performance,Urgent,,2025-05-01
+```
+
+Required column: `title`. Optional: `priority` (Urgent/High/Medium/Low), `status` (must match a status name in the project), `dueDate` (YYYY-MM-DD).
+
+---
+
+## Manual Auth
+
+Create a `.env` file in the project root (or pass via `env` in your client config):
+
+**Option A — Email + password (recommended):**
+
+Works if you have a password set on your Huly account (Profile → Security → Change password).
+
+```bash
+HULY_EMAIL=your@email.com
+HULY_PASSWORD=yourpassword
+HULY_WORKSPACE=your-workspace-slug
+```
+
+**Option B — Token:**
+
+```bash
+HULY_WORKSPACE=your-workspace-slug
+HULY_TOKEN=your-token-here
+```
+
+To get a token: go to [huly.app](https://huly.app) → open browser DevTools → Application → Local Storage → `https://huly.app` → copy the `token` value.
+
+> Tokens expire after some time. If you get an auth error, switch to email + password auth or refresh the token from DevTools.
+
+**Self-hosted Huly:**
+
+```bash
+HULY_ACCOUNTS_URL=https://your-huly-instance.com/account
+HULY_FRONT_URL=https://your-huly-instance.com
+```
+
+---
+
+## Architecture
+
+- **Single long-lived WebSocket connection** — connects once per process via `@hcengineering/server-client`, not per tool call (model load takes 1–3 s, so this keeps tools fast)
+- **Lazy init** — connects on the first tool call so auth errors surface clearly in Claude
+- **Dual auth** — OTP token (works for Google/GitHub SSO) or email + password
+- **Stdio transport** — standard MCP transport compatible with Claude Desktop and any MCP client
+
+---
+
+## Changelog
+
+### Fork — self-hosted support, chat, attachments, statuses, organizations
+- **Fix: self-hosted document/description writes** — auto-detects `huly-selfhost` via `HULY_FRONT_URL` and uploads through `front`'s `/files` contract instead of Huly Cloud's datalake, which self-hosted doesn't run
+- **New: `description` on `create_issue`/`update_issue`** — was missing entirely upstream
+- **New: Chat** — `list_channels`, `create_channel`, `start_direct_message`, `send_message`, `list_messages`
+- **New: Attachments** — `attach_file`, `list_attachments`, `delete_attachment`
+- **New: Issue Statuses** — `list_issue_statuses`, `create_issue_status`
+- **New: Organizations** — `list_organizations`, `get_organization`, `create_organization`, `update_organization`
+- See [About this fork](#about-this-fork) for details and what was investigated but not built
+
+### v0.5.6 — delete_document
+- **New: `delete_document`** — permanently delete a document by ID
+
+### v0.5.5 — create_teamspace
+- **New: `create_teamspace`** — create a new document teamspace (top-level folder for organising documents by project or team)
+
+### v0.5.2 — delete_comment + link_document
+- **New: `delete_comment`** — delete a specific comment from an issue by ID; `list_comments` now includes comment IDs in its output
+- **New: `link_document`** — link a Huly document to an issue; the document appears in the Relations panel on the issue
+
+### v0.5.0 — Document Writing + Bug Fixes
+- **New: `update_document`** — write Markdown to any Huly document programmatically; `\`\`\`mermaid` blocks use Huly's native node type and render as interactive diagrams
+- **Fix: `IssueStatus` queries** — statuses are stored globally in Huly (`core:space:Model`), not per-project; removed incorrect space filter that caused *"no statuses found"* errors on `create_issue`, `update_issue`, and `list_issues`
+- **Fix: `create_project`** — sets `members: [currentUser]` so newly created projects are immediately visible in the Huly UI
+
+### v0.4.0
+- `log_time`, `list_comments`, component/milestone assignment on `update_issue`
+
+### v0.3.1
+- `get_document`, `create_document`
+
+### v0.3.0
+- `create_project`, `create_milestone`, assignee support on issues
+
+---
+
+## Links
+
+- This fork: https://github.com/JoKeks2023/huly-mcp
+- Upstream: https://github.com/varaprasadreddy9676/huly-mcp ([npm](https://www.npmjs.com/package/huly-mcp-sdk), [MCP Registry](https://registry.modelcontextprotocol.io) — neither reflects this fork's changes)
+- Missing `.d.ts` in `@hcengineering/*` 0.7.411+: https://github.com/hcengineering/platform/issues/10881
+
+---
+
+## License
+
+[Eclipse Public License 2.0](https://www.eclipse.org/legal/epl-2.0/)

package/dist/connection.d.ts

@@ -0,0 +1,9 @@
+import { type AccountClient } from '@hcengineering/account-client';
+import { TxOperations } from '@hcengineering/core';
+export declare function getConnection(): Promise<TxOperations>;
+export declare function getAccountClient(): Promise<AccountClient>;
+export declare function getWorkspaceInfo(): Promise<{
+    wsToken: string;
+    workspaceUuid: string;
+}>;
+export declare function closeConnection(): Promise<void>;

package/dist/connection.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConnection = getConnection;
+exports.getAccountClient = getAccountClient;
+exports.getWorkspaceInfo = getWorkspaceInfo;
+exports.closeConnection = closeConnection;
+const account_client_1 = require("@hcengineering/account-client");
+const core_1 = require("@hcengineering/core");
+const server_client_1 = require("@hcengineering/server-client");
+let state = null;
+let connectPromise = null;
+async function getConnection() {
+    if (state !== null)
+        return state.txClient;
+    if (connectPromise !== null)
+        return (await connectPromise).txClient;
+    connectPromise = connect();
+    state = await connectPromise;
+    connectPromise = null;
+    return state.txClient;
+}
+async function getAccountClient() {
+    if (state !== null)
+        return state.accountClient;
+    await getConnection();
+    return state.accountClient;
+}
+async function getWorkspaceInfo() {
+    if (state !== null)
+        return { wsToken: state.wsToken, workspaceUuid: state.workspaceUuid };
+    await getConnection();
+    return { wsToken: state.wsToken, workspaceUuid: state.workspaceUuid };
+}
+async function connect() {
+    const email = process.env.HULY_EMAIL;
+    const password = process.env.HULY_PASSWORD;
+    const workspaceUrl = process.env.HULY_WORKSPACE;
+    const hulyToken = process.env.HULY_TOKEN;
+    const accountsUrl = process.env.HULY_ACCOUNTS_URL ?? 'https://account.huly.app';
+    if (workspaceUrl == null) {
+        throw new Error('Missing required env var: HULY_WORKSPACE');
+    }
+    let socialId;
+    let endpoint;
+    let wsToken;
+    let workspaceUuid = '';
+    if (hulyToken != null) {
+        // Token-based auth — for SSO accounts (Google/GitHub login on huly.app)
+        // Get the token from your browser: huly.app → DevTools → Application →
+        // Local Storage → huly.app → look for the key "token"
+        const authedClient = (0, account_client_1.getClient)(accountsUrl, hulyToken);
+        const info = await authedClient.getLoginInfoByToken();
+        if (info == null) {
+            throw new Error('HULY_TOKEN is invalid or expired. Please get a fresh token from huly.app DevTools.');
+        }
+        if ('endpoint' in info && info.endpoint != null) {
+            // It's a WorkspaceLoginInfo — already has endpoint + workspace token
+            if (info.socialId == null) {
+                throw new Error('Token auth: no socialId in token. Try a workspace-scoped token.');
+            }
+            socialId = info.socialId;
+            endpoint = info.endpoint;
+            wsToken = info.token;
+            workspaceUuid = String(info.workspace ?? '');
+        }
+        else if ('token' in info && info.token != null) {
+            // It's a plain LoginInfo (account-level token) — still need selectWorkspace
+            if (info.socialId == null) {
+                throw new Error('Token auth: no socialId returned.');
+            }
+            socialId = info.socialId;
+            const wsInfo = await authedClient.selectWorkspace(workspaceUrl, 'external');
+            if (wsInfo.endpoint == null || wsInfo.token == null) {
+                throw new Error(`Workspace '${workspaceUrl}' not found or not accessible.`);
+            }
+            endpoint = wsInfo.endpoint;
+            wsToken = wsInfo.token;
+            workspaceUuid = String(wsInfo.workspace ?? '');
+        }
+        else {
+            throw new Error('Token auth: unexpected response from getLoginInfoByToken. Token may be incomplete.');
+        }
+    }
+    else {
+        // Email + password auth — for accounts with a password set on huly.app
+        if (email == null || password == null) {
+            throw new Error('Missing credentials. Provide HULY_TOKEN (for SSO accounts) or both HULY_EMAIL and HULY_PASSWORD.');
+        }
+        // Step 1: login → get account token + socialId
+        const unauthClient = (0, account_client_1.getClient)(accountsUrl);
+        const loginInfo = await unauthClient.login(email, password);
+        if (loginInfo.token == null) {
+            throw new Error('Login failed: no token returned. Check credentials.');
+        }
+        if (loginInfo.socialId == null) {
+            throw new Error('Login failed: no socialId returned.');
+        }
+        // Step 2: select workspace → get WS endpoint + workspace token
+        const authedAccountClient = (0, account_client_1.getClient)(accountsUrl, loginInfo.token);
+        const wsInfo = await authedAccountClient.selectWorkspace(workspaceUrl, 'external');
+        if (wsInfo.endpoint == null || wsInfo.token == null) {
+            throw new Error(`Workspace '${workspaceUrl}' not found or not accessible.`);
+        }
+        socialId = loginInfo.socialId;
+        endpoint = wsInfo.endpoint;
+        workspaceUuid = String(wsInfo.workspace ?? '');
+        wsToken = wsInfo.token;
+    }
+    // Step 3: open WebSocket connection
+    const rawConnection = await (0, server_client_1.createClient)(endpoint, wsToken);
+    const txClient = new core_1.TxOperations(rawConnection, socialId);
+    // Build workspace-scoped account client for member lookups
+    const accountClient = (0, account_client_1.getClient)(accountsUrl, wsToken);
+    return { txClient, rawConnection, accountClient, wsToken, workspaceUuid };
+}
+async function closeConnection() {
+    if (state !== null) {
+        await state.rawConnection.close();
+        state = null;
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};