@bgx4k3p/huly-mcp-server 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bgx4k3p
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,457 @@
+# Huly MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+[![Tests](https://img.shields.io/badge/tests-162%20passing-brightgreen)](test/integration.test.mjs)
+[![Coverage](https://img.shields.io/badge/coverage-100%25%20methods-brightgreen)](test/integration.test.mjs)
+[![npm](https://img.shields.io/npm/v/@bgx4k3p/huly-mcp-server)](https://www.npmjs.com/package/@bgx4k3p/huly-mcp-server)
+[![Huly SDK](https://img.shields.io/badge/Huly%20SDK-0.7.x-purple)](https://huly.io)
+[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)](Dockerfile)
+
+MCP and HTTP REST server providing full coverage of the
+[Huly](https://huly.io) SDK — issues, projects, workspaces, members,
+and account management. Tested against self-hosted Huly.
+May also work with [Huly Cloud](https://app.huly.io) (not yet tested).
+
+## Why This Exists
+
+Huly has no REST API. The only programmatic access is through their JavaScript SDK,
+which connects via WebSocket. This server wraps that SDK and exposes **MCP tools**
+and a **full HTTP REST API** with OpenAPI spec, authentication, rate limiting, and SSE events.
+
+## Quick Start
+
+```bash
+git clone https://github.com/bgx4k3p/huly-mcp-server.git
+cd huly-mcp-server
+npm install
+```
+
+### Authentication
+
+You can authenticate with either **email/password** or a **token**.
+
+#### Email and Password
+
+```bash
+export HULY_URL=https://your-huly-instance.com
+export HULY_EMAIL=your@email.com
+export HULY_PASSWORD=your-password
+export HULY_WORKSPACE=your-workspace
+```
+
+#### Token (recommended)
+
+Get a token from your Huly credentials — no env vars needed beforehand:
+
+```bash
+node src/index.mjs --get-token -e your@email.com -p your-password -u https://your-huly-instance.com
+```
+
+Then use it:
+
+```bash
+export HULY_URL=https://your-huly-instance.com
+export HULY_TOKEN=<paste-token-from-above>
+export HULY_WORKSPACE=your-workspace
+```
+
+The token does not expire. You can store it in a secrets manager or
+`~/.secrets` file and stop exposing your password in environment variables.
+
+---
+
+## Integrations
+
+### Claude Code (MCP)
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "huly": {
+      "command": "node",
+      "args": ["path/to/huly-mcp-server/src/index.mjs"],
+      "env": {
+        "HULY_URL": "https://your-huly-instance.com",
+        "HULY_EMAIL": "${HULY_EMAIL}",
+        "HULY_PASSWORD": "${HULY_PASSWORD}",
+        "HULY_WORKSPACE": "${HULY_WORKSPACE}"
+      }
+    }
+  }
+}
+```
+
+Then ask Claude things like:
+
+- "List my issues in the OPS project"
+- "Create a bug report for the login page crash"
+- "Summarize the PROJ project — what's overdue?"
+- "Break down this feature into subtasks using the feature template"
+
+All tools have detailed descriptions optimized for AI agents.
+MCP Resources are also available at `huly://projects/{id}` and `huly://issues/{id}`.
+
+### n8n / Automation Workflows
+
+Start the HTTP server:
+
+```bash
+npm run start:server
+# Listening on port 3001
+```
+
+Use HTTP Request nodes pointing to `http://localhost:3001/api/...`:
+
+```bash
+# List projects
+curl http://localhost:3001/api/projects
+
+# Create an issue
+curl -X POST http://localhost:3001/api/projects/OPS/issues \
+  -H "Content-Type: application/json" \
+  -d '{"title": "New issue", "priority": "high"}'
+
+# Get project summary
+curl http://localhost:3001/api/projects/OPS/summary
+```
+
+OpenAPI spec available at `GET /api/openapi.json` for auto-discovery in n8n and other tools.
+
+### Docker
+
+```bash
+docker build -t huly-mcp-server .
+
+docker run -d \
+  -p 3001:3001 \
+  -e HULY_URL=https://your-huly-instance.com \
+  -e HULY_EMAIL=admin@example.com \
+  -e HULY_PASSWORD=secret \
+  -e HULY_WORKSPACE=my-workspace \
+  huly-mcp-server
+```
+
+For MCP stdio mode in Docker:
+
+```bash
+docker run -i \
+  -e HULY_URL=https://your-huly-instance.com \
+  -e HULY_EMAIL=admin@example.com \
+  -e HULY_PASSWORD=secret \
+  -e HULY_WORKSPACE=my-workspace \
+  huly-mcp-server node src/mcp.mjs
+```
+
+---
+
+## Server Configuration
+
+These settings control the MCP server itself — authentication, rate limiting,
+connection pooling. They are separate from the Huly credentials above.
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| **Huly Connection** | | | |
+| `HULY_URL` | No | `http://localhost:8087` | Huly instance URL |
+| `HULY_TOKEN` | No | - | Auth token (alternative to email/password) |
+| `HULY_EMAIL` | No | - | Huly login email (required if no token) |
+| `HULY_PASSWORD` | No | - | Huly login password (required if no token) |
+| `HULY_WORKSPACE` | Yes* | - | Default workspace slug |
+| **Server Settings** | | | |
+| `PORT` | No | `3001` | HTTP server port |
+| `MCP_AUTH_TOKEN` | No | - | Bearer token for HTTP server auth (disabled if unset) |
+| `HULY_RATE_LIMIT` | No | `100` | Max requests per minute per IP |
+| `HULY_POOL_TTL_MS` | No | `1800000` | Connection pool TTL in ms (30 min) |
+
+*`HULY_WORKSPACE` is required for MCP mode. For HTTP mode it can be
+omitted if every request specifies a workspace via header or query param.
+
+### HTTP Server Authentication
+
+The HTTP server optionally requires a bearer token. This protects **your server**
+from unauthorized access — it's separate from Huly's own authentication.
+
+```bash
+# Generate a token
+openssl rand -hex 32
+
+# Start with auth enabled
+MCP_AUTH_TOKEN=your-token-here npm run start:server
+
+# Clients must include it in requests
+curl -H "Authorization: Bearer your-token-here" http://localhost:3001/api/projects
+```
+
+If `MCP_AUTH_TOKEN` is not set, auth is disabled (fine for local-only usage).
+
+MCP stdio mode (Claude Code) does not use this token — stdio is inherently local.
+
+### Rate Limiting
+
+Per-IP rate limiting is always active. Response headers show current state:
+
+```text
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 97
+X-RateLimit-Reset: 1710000000
+```
+
+Returns `429 Too Many Requests` when exceeded.
+
+### SSE Event Stream
+
+Subscribe to real-time mutation events:
+
+```bash
+curl -N http://localhost:3001/api/events
+```
+
+Events: `issue.created`, `issue.updated`, `issue.moved`, `issue.assigned`,
+`issue.comment_added`, `issue.label_added`, `issues.batch_created`,
+`issues.template_created`, and more.
+
+### Multi-Workspace
+
+All tools/endpoints accept an optional workspace parameter. The connection pool caches clients by workspace slug:
+
+```bash
+# MCP: pass workspace in tool arguments
+{"tool": "list_projects", "arguments": {"workspace": "workspace-a"}}
+
+# HTTP: via header or query param
+curl -H "X-Huly-Workspace: workspace-a" http://localhost:3001/api/projects
+curl "http://localhost:3001/api/projects?workspace=workspace-b"
+```
+
+---
+
+## Testing
+
+Uses Node.js built-in `node:test` and `node:assert` — no test framework dependencies.
+
+```bash
+npm test
+```
+
+| Section | Tests | Description |
+| --- | --- | --- |
+| **Unit** | 28 | Constants, ID parsing, route matching, rate limiting, auth |
+| **Integration** | 43 | Full CRUD lifecycle against live Huly |
+| **Account-Level** | 11 | Workspaces, profile, social IDs |
+| **Mock** | 28 | Destructive ops, token auth via mocks |
+| **HTTP Server** | 52 | Every REST endpoint via real HTTP requests |
+
+**100% method coverage.** All test issues are prefixed with `[TEST]` and cleaned up after each run.
+
+---
+
+## Network Configurations
+
+- **Local:** `HULY_URL=http://localhost:8087`
+- **Remote:** `HULY_URL=https://huly.example.com`
+- **Behind nginx proxy:** Point to the proxy port
+
+### Cloudflare Access / Tunnel
+
+If Huly is behind Cloudflare Access with MFA, create a
+bypass Application for `/_*` or these individual paths:
+
+- `/_accounts`
+- `/_transactor`
+- `/_collaborator`
+- `/_rekoni`
+- `/config.json`
+
+---
+
+## Architecture
+
+```text
+src/
+  client.mjs    # HulyClient class - all business logic
+  pool.mjs      # Connection pool - caches clients by workspace with TTL
+  mcp.mjs       # MCP stdio entry point - MCP tools + resources
+  server.mjs    # HTTP REST entry point - auth, rate limiting, SSE, OpenAPI
+  index.mjs     # Backwards compat - re-exports mcp.mjs
+```
+
+```text
+Claude Code -> stdio -> mcp.mjs   -> pool.mjs -> client.mjs -> REST -> Huly
+n8n / curl  -> HTTP  -> server.mjs -> pool.mjs -> client.mjs -> REST -> Huly
+```
+
+---
+
+## API Reference
+
+Full list of all MCP tools and HTTP endpoints available through this server.
+
+### MCP Tools
+
+#### Account & Workspace Management
+
+| Tool | Description |
+| --- | --- |
+| `list_workspaces` | List all accessible workspaces |
+| `get_workspace_info` | Get workspace details by slug |
+| `create_workspace` | Create a new workspace |
+| `update_workspace_name` | Rename a workspace |
+| `delete_workspace` | Permanently delete a workspace |
+| `get_workspace_members` | List workspace members and roles |
+| `update_workspace_role` | Change a member's role |
+| `get_account_info` | Get current user's account info |
+| `get_user_profile` | Get current user's profile |
+| `set_my_profile` | Update profile fields |
+| `change_password` | Change password |
+| `change_username` | Change username |
+
+#### Invites
+
+| Tool | Description |
+| --- | --- |
+| `send_invite` | Send workspace invite email |
+| `resend_invite` | Resend pending invite |
+| `create_invite_link` | Generate shareable invite link |
+
+#### Integrations, Mailboxes, Social IDs, Subscriptions
+
+| Tool | Description |
+| --- | --- |
+| `list_integrations` / `get_integration` / `create_integration` / `update_integration` / `delete_integration` | Full CRUD for integrations |
+| `list_mailboxes` / `create_mailbox` / `delete_mailbox` | Mailbox management |
+| `find_person_by_social_key` / `get_social_ids` / `add_email_social_id` | Person/social ID management |
+| `list_subscriptions` | List account subscriptions |
+
+#### Projects & Issues
+
+| Tool | Description |
+| --- | --- |
+| `list_projects` / `get_project` | Browse projects |
+| `list_issues` / `get_issue` / `create_issue` / `update_issue` | Full issue CRUD with filtering |
+| `search_issues` | Full-text search across projects |
+| `get_my_issues` | Issues assigned to current user |
+| `batch_create_issues` | Create multiple issues at once |
+| `move_issue` | Move issue between projects |
+| `summarize_project` | Aggregated project metrics |
+| `get_issue_history` | Activity timeline for an issue |
+| `create_issues_from_template` | Create from feature/bug/sprint/release templates |
+
+#### Labels, Relations, Milestones, Members, Comments, Time Tracking
+
+| Tool | Description |
+| --- | --- |
+| `list_labels` / `create_label` / `add_label` / `remove_label` | Label management |
+| `add_relation` / `add_blocked_by` / `set_parent` | Issue relationships |
+| `list_milestones` / `get_milestone` / `create_milestone` / `set_milestone` | Milestone management |
+| `list_members` / `assign_issue` | Member management |
+| `add_comment` / `list_comments` | Comments |
+| `set_due_date` / `set_estimation` / `log_time` | Time tracking |
+| `list_task_types` / `list_statuses` | Metadata |
+
+### HTTP REST Endpoints
+
+#### System Routes
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/health` | Health check |
+| GET | `/api/openapi.json` | OpenAPI 3.0.3 spec |
+| GET | `/api/events` | SSE event stream |
+
+#### Account & Workspace Routes
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/api/workspaces` | List workspaces |
+| GET | `/api/workspaces/:slug/info` | Get workspace info |
+| POST | `/api/workspaces` | Create workspace |
+| PATCH | `/api/workspaces/:slug/name` | Rename workspace |
+| DELETE | `/api/workspaces/:slug` | Delete workspace |
+| GET | `/api/workspaces/:slug/members` | List members |
+| PATCH | `/api/workspaces/:slug/role` | Update member role |
+| POST | `/api/workspaces/:slug/invites` | Send invite |
+| POST | `/api/workspaces/:slug/invite-link` | Create invite link |
+| GET | `/api/account` | Get account info |
+| GET | `/api/profile` | Get user profile |
+| PATCH | `/api/profile` | Update profile |
+| GET | `/api/integrations` | List integrations |
+| POST | `/api/integrations` | Create integration |
+| DELETE | `/api/integrations/:id` | Delete integration |
+| GET | `/api/mailboxes` | List mailboxes |
+| GET | `/api/social-ids` | List social IDs |
+| GET | `/api/subscriptions` | List subscriptions |
+
+#### Project & Issue Routes
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/api/projects` | List all projects |
+| GET | `/api/projects/:identifier` | Get project by identifier |
+| GET | `/api/projects/:project/summary` | Project summary with metrics |
+| GET | `/api/projects/:project/issues` | List issues (query: status, priority, label, milestone, limit) |
+| GET | `/api/projects/:project/issues/:number` | Get issue |
+| POST | `/api/projects/:project/issues` | Create issue |
+| PATCH | `/api/issues/:issueId` | Update issue |
+| POST | `/api/issues/:issueId/move` | Move to different project |
+| GET | `/api/issues/:issueId/history` | Get activity history |
+| GET | `/api/my-issues` | Issues assigned to current user |
+| POST | `/api/projects/:project/batch-issues` | Batch create issues |
+| POST | `/api/projects/:project/template` | Create from template |
+| GET | `/api/search?query=...&project=...&limit=...` | Search issues |
+
+#### Other Resource Routes
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/api/labels` | List all labels |
+| POST | `/api/labels` | Create label |
+| POST | `/api/issues/:issueId/labels` | Add label to issue |
+| DELETE | `/api/issues/:issueId/labels/:label` | Remove label |
+| POST | `/api/issues/:issueId/relations` | Add relation |
+| POST | `/api/issues/:issueId/blocked-by` | Add blocked-by |
+| POST | `/api/issues/:issueId/parent` | Set parent |
+| GET | `/api/projects/:project/task-types` | List task types |
+| GET | `/api/statuses` | List all statuses |
+| GET | `/api/projects/:project/milestones` | List milestones |
+| GET | `/api/projects/:project/milestones/:name` | Get milestone |
+| POST | `/api/projects/:project/milestones` | Create milestone |
+| PATCH | `/api/issues/:issueId/milestone` | Set/clear milestone |
+| GET | `/api/members` | List workspace members |
+| PATCH | `/api/issues/:issueId/assignee` | Assign/unassign issue |
+| GET | `/api/issues/:issueId/comments` | List comments |
+| POST | `/api/issues/:issueId/comments` | Add comment |
+| PATCH | `/api/issues/:issueId/due-date` | Set/clear due date |
+| PATCH | `/api/issues/:issueId/estimation` | Set estimation |
+| POST | `/api/issues/:issueId/time-logs` | Log time |
+
+### Issue Templates
+
+Use `create_issues_from_template` (MCP) or `POST /api/projects/:project/template` (HTTP):
+
+| Template | Creates |
+| --- | --- |
+| `feature` | Epic + design/implement/test/docs/review sub-issues |
+| `bug` | Bug + reproduce/root-cause/fix/regression-test sub-issues |
+| `sprint` | Planning/standup/review/retro ceremony issues |
+| `release` | Epic + freeze/QA/changelog/staging/prod/verify sub-issues |
+
+---
+
+## Security
+
+`npm audit` reports moderate vulnerabilities in Svelte (SSR XSS).
+These come from Huly SDK transitive dependencies — the SDK shares packages
+with Huly's web frontend. This server never renders HTML or uses Svelte.
+The vulnerabilities are **not exploitable** in this context.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bgx4k3p/huly-mcp-server",
+  "version": "2.0.0",
+  "description": "MCP and HTTP REST server for Huly issue tracking with multi-workspace support",
+  "type": "module",
+  "license": "MIT",
+  "author": "bgx4k3p",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bgx4k3p/huly-mcp-server.git"
+  },
+  "homepage": "https://github.com/bgx4k3p/huly-mcp-server",
+  "keywords": [
+    "mcp",
+    "huly",
+    "model-context-protocol",
+    "issue-tracker",
+    "rest-api",
+    "claude",
+    "ai-agent"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "huly-mcp-server": "src/index.mjs"
+  },
+  "scripts": {
+    "start": "node src/index.mjs",
+    "start:mcp": "node src/mcp.mjs",
+    "start:server": "node src/server.mjs",
+    "test": "node --test test/integration.test.mjs"
+  },
+  "dependencies": {
+    "@hcengineering/api-client": "^0.7.3",
+    "@hcengineering/chunter": "^0.7.0",
+    "@hcengineering/core": "^0.7.4",
+    "@hcengineering/tags": "^0.7.0",
+    "@hcengineering/task": "^0.7.0",
+    "@hcengineering/tracker": "^0.7.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "jsdom": "^29.0.0"
+  }
+}