huly-mcp-selfhost 1.0.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +17 -9
- package/LICENSE +80 -0
- package/README.md +210 -111
- package/dist/connection.d.ts +65 -4
- package/dist/connection.js +230 -93
- package/dist/connection.js.map +1 -1
- package/dist/schemas.d.ts +173 -325
- package/dist/schemas.js +100 -3
- package/dist/schemas.js.map +1 -1
- package/dist/server.js +57 -6
- package/dist/server.js.map +1 -1
- package/dist/tools/attachments.d.ts +3 -0
- package/dist/tools/attachments.js +5 -5
- package/dist/tools/attachments.js.map +1 -1
- package/dist/tools/channels.d.ts +7 -2
- package/dist/tools/channels.js +5 -5
- package/dist/tools/channels.js.map +1 -1
- package/dist/tools/comments.d.ts +4 -1
- package/dist/tools/comments.js +3 -3
- package/dist/tools/comments.js.map +1 -1
- package/dist/tools/components.d.ts +27 -1
- package/dist/tools/components.js +72 -4
- package/dist/tools/components.js.map +1 -1
- package/dist/tools/documents.d.ts +11 -2
- package/dist/tools/documents.js +16 -14
- package/dist/tools/documents.js.map +1 -1
- package/dist/tools/issues.d.ts +7 -2
- package/dist/tools/issues.js +11 -10
- package/dist/tools/issues.js.map +1 -1
- package/dist/tools/labels.d.ts +4 -0
- package/dist/tools/labels.js +4 -4
- package/dist/tools/labels.js.map +1 -1
- package/dist/tools/log-time.d.ts +1 -0
- package/dist/tools/log-time.js +1 -1
- package/dist/tools/log-time.js.map +1 -1
- package/dist/tools/members.d.ts +3 -1
- package/dist/tools/members.js +2 -2
- package/dist/tools/members.js.map +1 -1
- package/dist/tools/milestones.d.ts +38 -1
- package/dist/tools/milestones.js +104 -12
- package/dist/tools/milestones.js.map +1 -1
- package/dist/tools/organizations.d.ts +7 -2
- package/dist/tools/organizations.js +10 -9
- package/dist/tools/organizations.js.map +1 -1
- package/dist/tools/projects.d.ts +6 -2
- package/dist/tools/projects.js +4 -4
- package/dist/tools/projects.js.map +1 -1
- package/dist/tools/relations.d.ts +3 -0
- package/dist/tools/relations.js +3 -3
- package/dist/tools/relations.js.map +1 -1
- package/dist/tools/search.d.ts +2 -1
- package/dist/tools/search.js +1 -1
- package/dist/tools/search.js.map +1 -1
- package/dist/tools/statuses.d.ts +4 -1
- package/dist/tools/statuses.js +3 -3
- package/dist/tools/statuses.js.map +1 -1
- package/dist/tools/workspaces.d.ts +6 -0
- package/dist/tools/workspaces.js +19 -0
- package/dist/tools/workspaces.js.map +1 -0
- package/dist/utils/format.d.ts +2 -0
- package/dist/utils/format.js +35 -0
- package/dist/utils/format.js.map +1 -1
- package/package.json +10 -5
- package/scripts/cleanup-issues.js +15 -6
- package/scripts/demo.js +10 -2
- package/scripts/import-csv.js +13 -5
- package/scripts/setup.js +22 -20
package/README.md
CHANGED
|
@@ -1,18 +1,27 @@
|
|
|
1
|
-
# huly-mcp-
|
|
1
|
+
# huly-mcp-selfhost
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/huly-mcp-selfhost)
|
|
4
|
+
[](https://hub.docker.com/r/jokeks2023/huly-mcp)
|
|
5
|
+
[](https://hub.docker.com/r/jokeks2023/huly-mcp)
|
|
6
|
+
[](https://github.com/JoKeks2023/huly-mcp/actions/workflows/docker-publish.yml)
|
|
7
|
+
[](LICENSE)
|
|
2
8
|
|
|
3
9
|
> The most complete MCP server for [Huly](https://huly.app) — the open-source project management platform.
|
|
4
10
|
|
|
5
|
-
Connects **Claude Desktop** (and any [MCP](https://modelcontextprotocol.io)-compatible client) directly to your Huly
|
|
11
|
+
Connects **Claude Desktop** (and any [MCP](https://modelcontextprotocol.io)-compatible client) directly to your Huly workspaces — one account, as many workspaces as it can access. Manage projects, issues, milestones, components, documents, labels, chat, attachments, organizations, and more — all via natural language.
|
|
6
12
|
|
|
7
13
|
## About this fork
|
|
8
14
|
|
|
9
|
-
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.
|
|
15
|
+
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. Published separately as **[`huly-mcp-selfhost`](https://www.npmjs.com/package/huly-mcp-selfhost)** on npm and as a Docker image — `huly-mcp-sdk` on npm is the *original* upstream package, not this one. See [Installing this fork](#installing-this-fork) below.
|
|
10
16
|
|
|
11
17
|
**Fixed vs. upstream:**
|
|
12
18
|
- **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).
|
|
13
19
|
- **`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.
|
|
14
20
|
|
|
15
|
-
**
|
|
21
|
+
**Multi-workspace:** one login, all workspaces of the account — see [Workspaces](#workspaces-one-account-several-workspaces).
|
|
22
|
+
|
|
23
|
+
**New tool categories** (upstream had 33 tools across Projects/Issues/Comments/Time/Labels/Relations/Members/Milestones/Components/Documents/Search; this fork adds 15 more):
|
|
24
|
+
- **Workspaces** — `list_workspaces`
|
|
16
25
|
- **Chat** — `list_channels`, `create_channel`, `start_direct_message`, `send_message`, `list_messages`
|
|
17
26
|
- **Attachments** — `attach_file`, `list_attachments`, `delete_attachment` (generic files on issues, any content type)
|
|
18
27
|
- **Issue Statuses** — `list_issue_statuses`, `create_issue_status` (custom workflow states)
|
|
@@ -22,11 +31,14 @@ This is a fork of [varaprasadreddy9676/huly-mcp](https://github.com/varaprasadre
|
|
|
22
31
|
|
|
23
32
|
---
|
|
24
33
|
|
|
25
|
-
## Tools (
|
|
34
|
+
## Tools (53 total)
|
|
35
|
+
|
|
36
|
+
All tools except `list_workspaces` take a `workspace` argument — required for every change, optional for reads when only one workspace is available.
|
|
26
37
|
|
|
27
38
|
| Category | Tool | Description |
|
|
28
39
|
|----------|------|-------------|
|
|
29
|
-
| **
|
|
40
|
+
| **Workspaces** | `list_workspaces` | List the workspaces this account can access (name, slug, id) |
|
|
41
|
+
| **Projects** | `list_projects` | List all projects in a workspace |
|
|
30
42
|
| | `get_project` | Get project details + available statuses |
|
|
31
43
|
| | `create_project` | Create a new tracker project with a unique identifier |
|
|
32
44
|
| **Issues** | `list_issues` | List issues with optional status / priority filters |
|
|
@@ -48,8 +60,13 @@ This is a fork of [varaprasadreddy9676/huly-mcp](https://github.com/varaprasadre
|
|
|
48
60
|
| **Members** | `list_members` | List workspace members |
|
|
49
61
|
| **Milestones** | `list_milestones` | List milestones for a project |
|
|
50
62
|
| | `create_milestone` | Create a milestone with a target date and status |
|
|
63
|
+
| | `get_milestone` | Milestone details with progress (done/open/canceled issues) and the open issues |
|
|
64
|
+
| | `update_milestone` | Change name, target date, status or description |
|
|
65
|
+
| | `delete_milestone` | Delete a milestone; its issues are unassigned or moved (`moveIssuesTo`) |
|
|
51
66
|
| **Components** | `list_components` | List components (sub-areas) in a project |
|
|
52
67
|
| | `create_component` | Create a new component with optional lead |
|
|
68
|
+
| | `update_component` | Change name, description or lead |
|
|
69
|
+
| | `delete_component` | Delete a component; its issues are unassigned or moved (`moveIssuesTo`) |
|
|
53
70
|
| **Documents** | `list_teamspaces` | List document teamspaces |
|
|
54
71
|
| | `create_teamspace` | Create a new teamspace (top-level document folder) |
|
|
55
72
|
| | `list_documents` | List documents in a teamspace |
|
|
@@ -58,7 +75,7 @@ This is a fork of [varaprasadreddy9676/huly-mcp](https://github.com/varaprasadre
|
|
|
58
75
|
| | `create_document` | Create a new document in a teamspace |
|
|
59
76
|
| | `update_document` | Write Markdown content to a document — Mermaid diagrams render natively |
|
|
60
77
|
| | `link_document` | Link a document to an issue — appears in the Relations panel |
|
|
61
|
-
| **Search** | `search_issues` | Full-text search across all issues |
|
|
78
|
+
| **Search** | `search_issues` | Full-text search across all issues of a workspace |
|
|
62
79
|
| **Chat** | `list_channels` | List all channels in the workspace |
|
|
63
80
|
| | `create_channel` | Create a new channel |
|
|
64
81
|
| | `start_direct_message` | Start (or find) a 1:1 direct message with a workspace member |
|
|
@@ -85,7 +102,18 @@ This is a fork of [varaprasadreddy9676/huly-mcp](https://github.com/varaprasadre
|
|
|
85
102
|
|
|
86
103
|
## Installing this fork
|
|
87
104
|
|
|
88
|
-
This fork
|
|
105
|
+
This fork is published separately as **[`huly-mcp-selfhost`](https://www.npmjs.com/package/huly-mcp-selfhost)** (`huly-mcp-sdk` is the upstream package). Three ways to run it:
|
|
106
|
+
|
|
107
|
+
### npm / npx
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
"command": "npx",
|
|
111
|
+
"args": ["-y", "huly-mcp-selfhost"]
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Every client example below uses this form.
|
|
115
|
+
|
|
116
|
+
### Clone and build
|
|
89
117
|
|
|
90
118
|
```bash
|
|
91
119
|
git clone https://github.com/JoKeks2023/huly-mcp.git
|
|
@@ -94,28 +122,65 @@ npm install
|
|
|
94
122
|
npm run build
|
|
95
123
|
```
|
|
96
124
|
|
|
97
|
-
Then in any client config below, replace `"command": "npx", "args": ["huly-mcp-sdk"]` with:
|
|
98
|
-
|
|
99
125
|
```json
|
|
100
126
|
"command": "node",
|
|
101
127
|
"args": ["/absolute/path/to/huly-mcp/dist/index.js"]
|
|
102
128
|
```
|
|
103
129
|
|
|
104
|
-
|
|
130
|
+
### Docker (network-reachable server, not local stdio)
|
|
131
|
+
|
|
132
|
+
For deployments where the MCP server needs to be reachable over the network (behind a reverse proxy, remote MCP clients, etc.) rather than launched locally per-client, a prebuilt image is published to GHCR on every push to `main`:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
docker pull jokeks2023/huly-mcp:latest
|
|
136
|
+
# also mirrored at ghcr.io/jokeks2023/huly-mcp:latest
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Or with Compose — copy `.env.example` to `.env`, fill in your credentials (no workspace needed), then:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
docker compose up -d
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
The container wraps the server with [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy) to expose it over HTTP/SSE at `:8000/sse`, since standard MCP stdio transport can't be reached over a network directly. See [`Dockerfile`](Dockerfile) / [`docker-compose.yml`](docker-compose.yml).
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## Workspaces (one account, several workspaces)
|
|
150
|
+
|
|
151
|
+
A single Huly account can belong to several workspaces — e.g. a personal one and a team one. This server logs in **once** with your account credentials and discovers every workspace that account can access via the account service (`getUserWorkspaces()`). You **don't configure a workspace** in the environment.
|
|
152
|
+
|
|
153
|
+
- **`list_workspaces`** returns name, slug and id of every available workspace.
|
|
154
|
+
- **Every other tool takes a `workspace` argument** — the slug, the name or the id (case-insensitive):
|
|
155
|
+
`list_projects(workspace="jokeks2023")`, `get_issue(workspace="acme", identifier="PROJ-1")`, `log_time(workspace="jokeks2023", identifier="WEB-12", hours=2)`.
|
|
156
|
+
- **Changes always require `workspace`.** Every tool that creates, updates, deletes, links, sends, attaches or logs something has `workspace` as a required argument — the server never falls back to an implicit, default or "last used" workspace for a write.
|
|
157
|
+
- **Reads may omit `workspace` only if exactly one workspace is available.** With several, the call fails and lists the options.
|
|
158
|
+
- **IDs are per workspace.** `PROJ-1`, a document id or a comment id identifies something only together with its workspace — the same id can exist in two workspaces. Pass the same `workspace` you got the id from.
|
|
159
|
+
- Each workspace gets its own lazily opened, cached WebSocket connection with its own workspace token (via `selectWorkspace()`), so workspaces never share state.
|
|
160
|
+
|
|
161
|
+
**Workspace slug:** the part of the Huly URL after the domain: `huly.app/workbench/`**`myteam`** → `myteam`. You don't need to look it up — `list_workspaces` (or `npm run setup`) prints it.
|
|
162
|
+
|
|
163
|
+
**Legacy `HULY_WORKSPACE`:** still honoured, but only as an optional *restriction*: if set, this server exposes just that one workspace (as before). Leave it unset to use all workspaces.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Configuration
|
|
168
|
+
|
|
169
|
+
| Variable | Required | Purpose |
|
|
170
|
+
|----------|----------|---------|
|
|
171
|
+
| `HULY_EMAIL` + `HULY_PASSWORD` | one auth option | Account login (needs a password set on your Huly account) |
|
|
172
|
+
| `HULY_TOKEN` | one auth option | Account token for SSO accounts (Google/GitHub) — get it with `npm run setup` |
|
|
173
|
+
| `HULY_ACCOUNTS_URL` | self-hosted only | Account service — login and workspace discovery. Default `https://account.huly.app`. Self-hosted: your instance's accounts URL, e.g. `https://huly.example.com/_accounts` |
|
|
174
|
+
| `HULY_FRONT_URL` | self-hosted (optional on Cloud) | Front service — document/description content and file uploads. Not involved in login or workspace discovery. Self-hosted: e.g. `https://huly.example.com` |
|
|
175
|
+
| `HULY_WORKSPACE` | no (legacy) | Restrict the server to a single workspace |
|
|
105
176
|
|
|
106
177
|
---
|
|
107
178
|
|
|
108
179
|
## Compatible Clients
|
|
109
180
|
|
|
110
|
-
The same MCP server works across all major AI coding tools.
|
|
181
|
+
The same MCP server works across all major AI coding tools. All examples use **email + password** and the npm package via `npx`; for SSO accounts replace the two credentials with `"HULY_TOKEN": "your-token"` (see [Authentication](#authentication)). To run a local build instead, replace `npx` + args with `node` + `["/absolute/path/to/huly-mcp/dist/index.js"]`.
|
|
111
182
|
|
|
112
|
-
|
|
113
|
-
> ```json
|
|
114
|
-
> "HULY_EMAIL": "your@email.com",
|
|
115
|
-
> "HULY_PASSWORD": "yourpassword",
|
|
116
|
-
> "HULY_WORKSPACE": "your-workspace-slug"
|
|
117
|
-
> ```
|
|
118
|
-
> See [Manual Auth](#manual-auth) for details on both options.
|
|
183
|
+
**Self-hosted:** add `HULY_ACCOUNTS_URL` and `HULY_FRONT_URL` to every `env` block below.
|
|
119
184
|
|
|
120
185
|
---
|
|
121
186
|
|
|
@@ -129,10 +194,10 @@ The same MCP server works across all major AI coding tools. Pick your client, th
|
|
|
129
194
|
"mcpServers": {
|
|
130
195
|
"huly": {
|
|
131
196
|
"command": "npx",
|
|
132
|
-
"args": ["huly-mcp-
|
|
197
|
+
"args": ["-y", "huly-mcp-selfhost"],
|
|
133
198
|
"env": {
|
|
134
|
-
"
|
|
135
|
-
"
|
|
199
|
+
"HULY_EMAIL": "you@example.com",
|
|
200
|
+
"HULY_PASSWORD": "your-password"
|
|
136
201
|
}
|
|
137
202
|
}
|
|
138
203
|
}
|
|
@@ -146,43 +211,40 @@ Restart Claude Desktop after saving.
|
|
|
146
211
|
### Claude Code (CLI)
|
|
147
212
|
|
|
148
213
|
```bash
|
|
149
|
-
claude mcp add huly
|
|
214
|
+
claude mcp add huly \
|
|
215
|
+
-e HULY_EMAIL=you@example.com \
|
|
216
|
+
-e HULY_PASSWORD=your-password \
|
|
217
|
+
-- npx -y huly-mcp-selfhost
|
|
150
218
|
```
|
|
151
219
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
```bash
|
|
155
|
-
claude mcp add huly --scope project -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
Verify it's connected: `claude mcp list`
|
|
220
|
+
Add `--scope project` (writes `.mcp.json`, shared with the repo — don't commit secrets) or `--scope user` (all your projects) after `add huly`. Verify with `claude mcp list`.
|
|
159
221
|
|
|
160
222
|
---
|
|
161
223
|
|
|
162
224
|
### Cursor
|
|
163
225
|
|
|
164
|
-
Create or edit `~/.cursor/mcp.json
|
|
226
|
+
Create or edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
|
|
165
227
|
|
|
166
228
|
```json
|
|
167
229
|
{
|
|
168
230
|
"mcpServers": {
|
|
169
231
|
"huly": {
|
|
170
232
|
"command": "npx",
|
|
171
|
-
"args": ["huly-mcp-
|
|
233
|
+
"args": ["-y", "huly-mcp-selfhost"],
|
|
172
234
|
"env": {
|
|
173
|
-
"
|
|
174
|
-
"
|
|
235
|
+
"HULY_EMAIL": "you@example.com",
|
|
236
|
+
"HULY_PASSWORD": "your-password"
|
|
175
237
|
}
|
|
176
238
|
}
|
|
177
239
|
}
|
|
178
240
|
}
|
|
179
241
|
```
|
|
180
242
|
|
|
181
|
-
|
|
243
|
+
The tools appear in the Agent panel under MCP.
|
|
182
244
|
|
|
183
245
|
---
|
|
184
246
|
|
|
185
|
-
### Windsurf
|
|
247
|
+
### Windsurf
|
|
186
248
|
|
|
187
249
|
Create or edit `~/.codeium/windsurf/mcp_config.json`:
|
|
188
250
|
|
|
@@ -191,34 +253,35 @@ Create or edit `~/.codeium/windsurf/mcp_config.json`:
|
|
|
191
253
|
"mcpServers": {
|
|
192
254
|
"huly": {
|
|
193
255
|
"command": "npx",
|
|
194
|
-
"args": ["huly-mcp-
|
|
256
|
+
"args": ["-y", "huly-mcp-selfhost"],
|
|
195
257
|
"env": {
|
|
196
|
-
"
|
|
197
|
-
"
|
|
258
|
+
"HULY_EMAIL": "you@example.com",
|
|
259
|
+
"HULY_PASSWORD": "your-password"
|
|
198
260
|
}
|
|
199
261
|
}
|
|
200
262
|
}
|
|
201
263
|
}
|
|
202
264
|
```
|
|
203
265
|
|
|
204
|
-
|
|
266
|
+
Refresh the MCP servers in the Cascade panel.
|
|
205
267
|
|
|
206
268
|
---
|
|
207
269
|
|
|
208
|
-
### VS Code — Cline
|
|
270
|
+
### VS Code — Cline
|
|
209
271
|
|
|
210
|
-
|
|
211
|
-
2. Open Cline settings → **MCP Servers** → **Edit MCP Settings**
|
|
212
|
-
3. Add:
|
|
272
|
+
Cline → **MCP Servers** → **Installed** → **Configure MCP Servers** (opens `cline_mcp_settings.json`):
|
|
213
273
|
|
|
214
274
|
```json
|
|
215
275
|
{
|
|
216
|
-
"
|
|
217
|
-
"
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
"
|
|
221
|
-
|
|
276
|
+
"mcpServers": {
|
|
277
|
+
"huly": {
|
|
278
|
+
"command": "npx",
|
|
279
|
+
"args": ["-y", "huly-mcp-selfhost"],
|
|
280
|
+
"env": {
|
|
281
|
+
"HULY_EMAIL": "you@example.com",
|
|
282
|
+
"HULY_PASSWORD": "your-password"
|
|
283
|
+
},
|
|
284
|
+
"disabled": false
|
|
222
285
|
}
|
|
223
286
|
}
|
|
224
287
|
}
|
|
@@ -226,44 +289,36 @@ Restart Windsurf. MCP tools are available to the Cascade AI panel.
|
|
|
226
289
|
|
|
227
290
|
---
|
|
228
291
|
|
|
229
|
-
### VS Code — Continue
|
|
292
|
+
### VS Code / JetBrains — Continue
|
|
230
293
|
|
|
231
|
-
|
|
232
|
-
2. Edit `~/.continue/config.json` and add to the `mcpServers` array:
|
|
294
|
+
Add to `~/.continue/config.yaml` (MCP tools are available in Agent mode):
|
|
233
295
|
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
"HULY_TOKEN": "your-token",
|
|
243
|
-
"HULY_WORKSPACE": "your-workspace-slug"
|
|
244
|
-
}
|
|
245
|
-
}
|
|
246
|
-
]
|
|
247
|
-
}
|
|
296
|
+
```yaml
|
|
297
|
+
mcpServers:
|
|
298
|
+
- name: huly
|
|
299
|
+
command: npx
|
|
300
|
+
args: ["-y", "huly-mcp-selfhost"]
|
|
301
|
+
env:
|
|
302
|
+
HULY_EMAIL: you@example.com
|
|
303
|
+
HULY_PASSWORD: your-password
|
|
248
304
|
```
|
|
249
305
|
|
|
250
306
|
---
|
|
251
307
|
|
|
252
308
|
### Zed
|
|
253
309
|
|
|
254
|
-
|
|
310
|
+
Add to `~/.config/zed/settings.json`:
|
|
255
311
|
|
|
256
312
|
```json
|
|
257
313
|
{
|
|
258
314
|
"context_servers": {
|
|
259
315
|
"huly": {
|
|
260
|
-
"
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
}
|
|
316
|
+
"source": "custom",
|
|
317
|
+
"command": "npx",
|
|
318
|
+
"args": ["-y", "huly-mcp-selfhost"],
|
|
319
|
+
"env": {
|
|
320
|
+
"HULY_EMAIL": "you@example.com",
|
|
321
|
+
"HULY_PASSWORD": "your-password"
|
|
267
322
|
}
|
|
268
323
|
}
|
|
269
324
|
}
|
|
@@ -274,35 +329,27 @@ Edit `~/.config/zed/settings.json` and add a `context_servers` entry:
|
|
|
274
329
|
|
|
275
330
|
### OpenAI Codex CLI
|
|
276
331
|
|
|
277
|
-
|
|
332
|
+
Add to `~/.codex/config.toml`:
|
|
278
333
|
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
"command": "npx",
|
|
285
|
-
"args": ["huly-mcp-sdk"],
|
|
286
|
-
"env": {
|
|
287
|
-
"HULY_TOKEN": "your-token",
|
|
288
|
-
"HULY_WORKSPACE": "your-workspace-slug"
|
|
289
|
-
}
|
|
290
|
-
}
|
|
291
|
-
}
|
|
292
|
-
}
|
|
334
|
+
```toml
|
|
335
|
+
[mcp_servers.huly]
|
|
336
|
+
command = "npx"
|
|
337
|
+
args = ["-y", "huly-mcp-selfhost"]
|
|
338
|
+
env = { HULY_EMAIL = "you@example.com", HULY_PASSWORD = "your-password" }
|
|
293
339
|
```
|
|
294
340
|
|
|
341
|
+
or: `codex mcp add huly --env HULY_EMAIL=you@example.com --env HULY_PASSWORD=your-password -- npx -y huly-mcp-selfhost`
|
|
342
|
+
|
|
295
343
|
---
|
|
296
344
|
|
|
297
345
|
### Any other MCP-compatible client
|
|
298
346
|
|
|
299
|
-
The server uses standard **stdio transport
|
|
347
|
+
The server uses standard **stdio transport**:
|
|
300
348
|
|
|
301
|
-
- **command:** `node`
|
|
302
|
-
- **
|
|
303
|
-
- **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))
|
|
349
|
+
- **command:** `npx` with args `["-y", "huly-mcp-selfhost"]`, or `node` with `["/absolute/path/to/huly-mcp/dist/index.js"]`
|
|
350
|
+
- **env:** `HULY_EMAIL` + `HULY_PASSWORD` (or `HULY_TOKEN`); self-hosted also `HULY_ACCOUNTS_URL` + `HULY_FRONT_URL` — see [Configuration](#configuration)
|
|
304
351
|
|
|
305
|
-
|
|
352
|
+
For network access (HTTP/SSE) use the [Docker image](#docker-network-reachable-server-not-local-stdio).
|
|
306
353
|
|
|
307
354
|
---
|
|
308
355
|
|
|
@@ -310,6 +357,11 @@ Consult your tool's MCP documentation for the exact config file location.
|
|
|
310
357
|
|
|
311
358
|
## Example Prompts
|
|
312
359
|
|
|
360
|
+
**Workspaces:**
|
|
361
|
+
- *"Which Huly workspaces do I have?"*
|
|
362
|
+
- *"List the projects in my Acme workspace"*
|
|
363
|
+
- *"In the jokeks2023 workspace, log 2 hours on WEB-12"*
|
|
364
|
+
|
|
313
365
|
**Projects & issues:**
|
|
314
366
|
- *"Create a new project called 'Mobile App' with identifier MOBILE"*
|
|
315
367
|
- *"List all in-progress issues in the PROJ project"*
|
|
@@ -324,6 +376,9 @@ Consult your tool's MCP documentation for the exact config file location.
|
|
|
324
376
|
- *"List milestones for the PROJ project"*
|
|
325
377
|
- *"Create a component called 'Auth' in PROJ"*
|
|
326
378
|
- *"List all components in PROJ"*
|
|
379
|
+
- *"How far along is milestone v2.0 Launch in PROJ?"*
|
|
380
|
+
- *"Move the v2.0 Launch milestone to 2026-07-15 and set it to In Progress"*
|
|
381
|
+
- *"Delete milestone 'Beta' in PROJ and move its issues to 'v2.0 Launch'"*
|
|
327
382
|
|
|
328
383
|
**Labels & relations:**
|
|
329
384
|
- *"Add the label 'bug' to PROJ-42"*
|
|
@@ -352,12 +407,14 @@ Consult your tool's MCP documentation for the exact config file location.
|
|
|
352
407
|
|
|
353
408
|
```json
|
|
354
409
|
"env": {
|
|
355
|
-
"
|
|
356
|
-
"
|
|
410
|
+
"HULY_EMAIL": "...",
|
|
411
|
+
"HULY_PASSWORD": "...",
|
|
357
412
|
"HULY_FRONT_URL": "https://front.huly.app"
|
|
358
413
|
}
|
|
359
414
|
```
|
|
360
415
|
|
|
416
|
+
`HULY_FRONT_URL` only serves document/description content and file uploads — each request uses the token of the workspace named in the tool call. It plays no part in login or workspace discovery (that is `HULY_ACCOUNTS_URL`).
|
|
417
|
+
|
|
361
418
|
For **self-hosted** Huly, set `HULY_FRONT_URL` to your own front service URL (e.g. `http://localhost:8083`).
|
|
362
419
|
|
|
363
420
|
### Writing: `update_document`
|
|
@@ -413,9 +470,12 @@ The Mermaid block renders as a live interactive diagram in Huly's document edito
|
|
|
413
470
|
Import many issues at once from a CSV file — useful for migrating from other tools:
|
|
414
471
|
|
|
415
472
|
```bash
|
|
416
|
-
|
|
473
|
+
npm run build
|
|
474
|
+
node scripts/import-csv.js tasks.csv PROJ --workspace=myteam
|
|
417
475
|
```
|
|
418
476
|
|
|
477
|
+
The target workspace is required (`--workspace=<slug>`, or `HULY_WORKSPACE` as a fallback), since the script writes data. Credentials come from the environment as for the server.
|
|
478
|
+
|
|
419
479
|
**CSV format:**
|
|
420
480
|
|
|
421
481
|
```csv
|
|
@@ -429,9 +489,9 @@ Required column: `title`. Optional: `priority` (Urgent/High/Medium/Low), `status
|
|
|
429
489
|
|
|
430
490
|
---
|
|
431
491
|
|
|
432
|
-
##
|
|
492
|
+
## Authentication
|
|
433
493
|
|
|
434
|
-
Create a `.env` file in the project root (or pass via `env` in your client config)
|
|
494
|
+
Create a `.env` file in the project root (or pass via `env` in your client config). No workspace is needed in either option.
|
|
435
495
|
|
|
436
496
|
**Option A — Email + password (recommended):**
|
|
437
497
|
|
|
@@ -440,40 +500,79 @@ Works if you have a password set on your Huly account (Profile → Security →
|
|
|
440
500
|
```bash
|
|
441
501
|
HULY_EMAIL=your@email.com
|
|
442
502
|
HULY_PASSWORD=yourpassword
|
|
443
|
-
HULY_WORKSPACE=your-workspace-slug
|
|
444
503
|
```
|
|
445
504
|
|
|
446
|
-
**Option B — Token:**
|
|
505
|
+
**Option B — Token (SSO accounts: Google/GitHub):**
|
|
506
|
+
|
|
507
|
+
```bash
|
|
508
|
+
npm run setup
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
The wizard sends a one-time code to your email, saves the resulting account token as `HULY_TOKEN` in `.env`, and lists the workspaces the account can access (a discovery test).
|
|
447
512
|
|
|
448
513
|
```bash
|
|
449
|
-
HULY_WORKSPACE=your-workspace-slug
|
|
450
514
|
HULY_TOKEN=your-token-here
|
|
451
515
|
```
|
|
452
516
|
|
|
453
|
-
|
|
517
|
+
A token copied from the browser (DevTools → Application → Local Storage → `token`) also works, but may be scoped to the single workspace open in that tab. If the account service refuses to list workspaces for such a token, the server falls back to that one workspace. Use `npm run setup` for full multi-workspace discovery.
|
|
454
518
|
|
|
455
|
-
> Tokens expire after some time. If you get an auth error,
|
|
519
|
+
> Tokens expire after some time. If you get an auth error, run `npm run setup` again or switch to email + password.
|
|
456
520
|
|
|
457
521
|
**Self-hosted Huly:**
|
|
458
522
|
|
|
459
523
|
```bash
|
|
460
|
-
HULY_ACCOUNTS_URL=https://your-huly-instance.com/
|
|
461
|
-
HULY_FRONT_URL=https://your-huly-instance.com
|
|
524
|
+
HULY_ACCOUNTS_URL=https://your-huly-instance.com/_accounts # login + workspace discovery
|
|
525
|
+
HULY_FRONT_URL=https://your-huly-instance.com # document content + file uploads
|
|
462
526
|
```
|
|
463
527
|
|
|
464
528
|
---
|
|
465
529
|
|
|
466
530
|
## Architecture
|
|
467
531
|
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
532
|
+
```text
|
|
533
|
+
HULY_EMAIL + HULY_PASSWORD (or HULY_TOKEN)
|
|
534
|
+
↓
|
|
535
|
+
account login (once) account-level client: getUserWorkspaces(), selectWorkspace()
|
|
536
|
+
↓
|
|
537
|
+
getUserWorkspaces() → workspace discovery (cached)
|
|
538
|
+
↓
|
|
539
|
+
WorkspaceConnectionManager
|
|
540
|
+
├── workspace A: selectWorkspace(A) → endpoint + token → WebSocket (cached)
|
|
541
|
+
├── workspace B: selectWorkspace(B) → endpoint + token → WebSocket (cached)
|
|
542
|
+
└── … workspace-level client (workspace token): getWorkspaceMembers()
|
|
543
|
+
↓
|
|
544
|
+
MCP tools (each call names its workspace)
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
- **One login, many workspaces** — the account session is shared; each workspace gets its own long-lived connection via `@hcengineering/server-client` (model load takes 1–3 s, so connections are reused, not opened per call)
|
|
548
|
+
- **Lazy** — nothing connects until the first tool call, and a workspace connects only when first used, so auth errors surface clearly in the client
|
|
549
|
+
- **No current workspace** — there is no global or "last used" workspace; see [Workspaces](#workspaces-one-account-several-workspaces)
|
|
550
|
+
- **Stdio transport** — standard MCP transport; the Docker image adds HTTP/SSE via `mcp-proxy`
|
|
551
|
+
|
|
552
|
+
See [`src/connection.ts`](src/connection.ts).
|
|
472
553
|
|
|
473
554
|
---
|
|
474
555
|
|
|
475
556
|
## Changelog
|
|
476
557
|
|
|
558
|
+
### 2.1.0 — milestones & components, security updates
|
|
559
|
+
|
|
560
|
+
- **New: `get_milestone`, `update_milestone`, `delete_milestone`** — progress overview, edit name/date/status/description, delete with issues unassigned or moved via `moveIssuesTo`
|
|
561
|
+
- **New: `update_component`, `delete_component`** — edit name/description/lead, delete with issues unassigned or moved via `moveIssuesTo`
|
|
562
|
+
- **Changed: `list_components`** renders Markdown/ProseMirror descriptions as text
|
|
563
|
+
- **Security:** all open dependency advisories fixed — `@modelcontextprotocol/sdk` 1.32, `ws` 8.22, `zod` 4, `dompurify` 3.4.17 (override)
|
|
564
|
+
|
|
565
|
+
### 2.0.0 — multi-workspace
|
|
566
|
+
|
|
567
|
+
Breaking: tools that change data require `workspace`; `HULY_WORKSPACE` only restricts the server to one workspace.
|
|
568
|
+
|
|
569
|
+
- **New: multi-workspace support** — one account login, workspaces discovered via `getUserWorkspaces()`, one cached connection per workspace; `HULY_WORKSPACE` is no longer required (still honoured as an optional single-workspace restriction)
|
|
570
|
+
- **New: `list_workspaces`**
|
|
571
|
+
- **Changed: every tool takes `workspace`** — required for all tools that change data; reads may omit it only when exactly one workspace is available
|
|
572
|
+
- **New: `huly-mcp-selfhost` bin alias** — `npx huly-mcp-selfhost` now starts the server directly
|
|
573
|
+
- **Changed: `npm run setup`** no longer asks for a workspace; it lists the discovered workspaces instead
|
|
574
|
+
- **Changed: `scripts/import-csv.js`, `cleanup-issues.js`, `demo.js`** need `--workspace=<slug>` (or `HULY_WORKSPACE`)
|
|
575
|
+
|
|
477
576
|
### Fork — self-hosted support, chat, attachments, statuses, organizations
|
|
478
577
|
- **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
|
|
479
578
|
- **New: `description` on `create_issue`/`update_issue`** — was missing entirely upstream
|
package/dist/connection.d.ts
CHANGED
|
@@ -1,9 +1,70 @@
|
|
|
1
1
|
import { type AccountClient } from '@hcengineering/account-client';
|
|
2
|
-
import { TxOperations } from '@hcengineering/core';
|
|
3
|
-
export
|
|
4
|
-
|
|
5
|
-
|
|
2
|
+
import { TxOperations, type PersonId } from '@hcengineering/core';
|
|
3
|
+
export interface WorkspaceRef {
|
|
4
|
+
uuid: string;
|
|
5
|
+
/** Workspace slug, as in huly.app/<slug>. Passed to selectWorkspace(). */
|
|
6
|
+
url: string;
|
|
7
|
+
name: string;
|
|
8
|
+
mode?: string;
|
|
9
|
+
isDisabled?: boolean;
|
|
10
|
+
}
|
|
11
|
+
export interface WorkspaceConnection {
|
|
12
|
+
workspace: WorkspaceRef;
|
|
13
|
+
client: TxOperations;
|
|
14
|
+
/** Workspace-scoped account client (token carries the workspace) — e.g. getWorkspaceMembers(). */
|
|
15
|
+
accountClient: AccountClient;
|
|
16
|
+
wsToken: string;
|
|
17
|
+
workspaceUuid: string;
|
|
18
|
+
}
|
|
19
|
+
interface OpenConnection {
|
|
20
|
+
client: TxOperations;
|
|
21
|
+
close: () => Promise<void>;
|
|
22
|
+
}
|
|
23
|
+
export interface ConnectionManagerOptions {
|
|
24
|
+
accountsUrl: string;
|
|
25
|
+
email?: string;
|
|
26
|
+
password?: string;
|
|
27
|
+
token?: string;
|
|
28
|
+
/** Legacy HULY_WORKSPACE: restricts this server to that single workspace. */
|
|
29
|
+
restrictTo?: string;
|
|
30
|
+
createAccountClient?: (accountsUrl: string, token?: string) => AccountClient;
|
|
31
|
+
openConnection?: (endpoint: string, token: string, socialId: PersonId) => Promise<OpenConnection>;
|
|
32
|
+
}
|
|
33
|
+
export declare class WorkspaceConnectionManager {
|
|
34
|
+
private readonly opts;
|
|
35
|
+
private readonly createAccountClient;
|
|
36
|
+
private readonly openConnection;
|
|
37
|
+
private session;
|
|
38
|
+
private workspaces;
|
|
39
|
+
private generation;
|
|
40
|
+
private readonly connections;
|
|
41
|
+
constructor(opts: ConnectionManagerOptions);
|
|
42
|
+
/** All workspaces this account can use (after the optional legacy HULY_WORKSPACE restriction). */
|
|
43
|
+
listWorkspaces(): Promise<WorkspaceRef[]>;
|
|
44
|
+
/**
|
|
45
|
+
* Resolve user input (slug, name or UUID; case-insensitive) to a workspace.
|
|
46
|
+
* Without input, succeeds only if exactly one workspace is available.
|
|
47
|
+
*/
|
|
48
|
+
resolveWorkspace(input?: string): Promise<WorkspaceRef>;
|
|
49
|
+
/** Cached connection for the given workspace (see resolveWorkspace for the input rules). */
|
|
50
|
+
getWorkspace(input?: string): Promise<WorkspaceConnection>;
|
|
51
|
+
closeAll(): Promise<void>;
|
|
52
|
+
private match;
|
|
53
|
+
private getSession;
|
|
54
|
+
private login;
|
|
55
|
+
private discover;
|
|
56
|
+
private connect;
|
|
57
|
+
}
|
|
58
|
+
export declare function getConnectionManager(): WorkspaceConnectionManager;
|
|
59
|
+
/** Replace the process-wide manager (tests). */
|
|
60
|
+
export declare function setConnectionManager(next: WorkspaceConnectionManager | null): void;
|
|
61
|
+
export declare function listWorkspaces(): Promise<WorkspaceRef[]>;
|
|
62
|
+
export declare function getWorkspace(workspace?: string): Promise<WorkspaceConnection>;
|
|
63
|
+
export declare function getConnection(workspace?: string): Promise<TxOperations>;
|
|
64
|
+
export declare function getAccountClient(workspace?: string): Promise<AccountClient>;
|
|
65
|
+
export declare function getWorkspaceInfo(workspace?: string): Promise<{
|
|
6
66
|
wsToken: string;
|
|
7
67
|
workspaceUuid: string;
|
|
8
68
|
}>;
|
|
9
69
|
export declare function closeConnection(): Promise<void>;
|
|
70
|
+
export {};
|