@firfi/huly-mcp 0.49.6 → 0.49.7

package/README.md

@@ -209,6 +209,18 @@ The `@latest` tag asks the package runner for the newest version. Some MCP clien
 | **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 |
 
+## Maintainer Production Release
+
+Publish from a clean, current `master` checkout with the preferred certified Node.js runtime:
+
+```bash
+mise exec node@24.15.0 -- pnpm local-release
+```
+
+Use this exact command even when a newer Node.js version is active on the host. The release build accepts only the
+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.
+
 ## HTTP Transport
 
 By default, the server uses stdio transport. For HTTP transport:

package/dist/index.cjs

@@ -125061,7 +125061,7 @@ var init_unavailable_diagnostics = __esm({
 });
 
 // src/huly/errors-base.ts
-var HulyError, NoUpdateFieldsError, HulyConnectionError, HulyDataInvalidError, HulyUnavailableError, HulyAuthError, HulyModelNameSchema, HulyModelFieldSchema, HulyModelMetadataError;
+var HulyError, NoUpdateFieldsError, HulyConnectionOperation, HulyHttpStatus, HulyConnectionDiagnostic, HulyConnectionError, HTTP_ERROR_STATUS_PATTERN, hulyHttpStatusFromCause, makeOperationConnectionError, HulyDataInvalidError, HulyUnavailableError, HulyAuthError, HulyModelNameSchema, HulyModelFieldSchema, HulyModelMetadataError;
 var init_errors_base = __esm({
   "src/huly/errors-base.ts"() {
     "use strict";
@@ -125080,11 +125080,67 @@ var init_errors_base = __esm({
         return `${this.operation} requires at least one update field: ${this.fields.join(", ")}`;
       }
     };
+    HulyConnectionOperation = Schema_exports.Literals([
+      "findAll",
+      "findOne",
+      "findAllInModel",
+      "createDoc",
+      "conditionalCreateDoc",
+      "updateDoc",
+      "conditionalUpdateDoc",
+      "addCollection",
+      "updateCollection",
+      "removeCollection",
+      "removeDoc",
+      "conditionalRemoveDoc",
+      "createMixin",
+      "updateMixin",
+      "uploadMarkup",
+      "fetchMarkup",
+      "updateMarkup",
+      "searchFulltext",
+      "getWorkspaceMembers",
+      "getPersonInfo",
+      "updateWorkspaceRole",
+      "getWorkspaceInfo",
+      "getUserWorkspaces",
+      "createWorkspace",
+      "deleteWorkspace",
+      "getUserProfile",
+      "setMyProfile",
+      "createAccessLink",
+      "updateAllowReadOnlyGuests",
+      "updateAllowGuestSignUp",
+      "getRegionInfo"
+    ]);
+    HulyHttpStatus = Schema_exports.Int.check(Schema_exports.isBetween({ minimum: 100, maximum: 599 })).pipe(
+      Schema_exports.brand("HulyHttpStatus")
+    );
+    HulyConnectionDiagnostic = Schema_exports.Struct({
+      operation: HulyConnectionOperation,
+      httpStatus: Schema_exports.optionalKey(HulyHttpStatus)
+    });
     HulyConnectionError = class extends Schema_exports.TaggedError()("HulyConnectionError", {
       message: Schema_exports.String,
-      cause: Schema_exports.optional(Schema_exports.Defect())
+      cause: Schema_exports.optional(Schema_exports.Defect()),
+      diagnostic: Schema_exports.optionalKey(HulyConnectionDiagnostic)
     }) {
     };
+    HTTP_ERROR_STATUS_PATTERN = /\bHTTP(?: error)?\s+(?<status>[1-5]\d{2})\b/i;
+    hulyHttpStatusFromCause = (cause) => {
+      if (!(cause instanceof Error)) return void 0;
+      const statusText = HTTP_ERROR_STATUS_PATTERN.exec(cause.message)?.groups?.status;
+      if (statusText === void 0) return void 0;
+      return HulyHttpStatus.make(Number(statusText));
+    };
+    makeOperationConnectionError = (operation, cause) => {
+      const httpStatus = hulyHttpStatusFromCause(cause);
+      const message = `${operation} failed${httpStatus === void 0 ? "" : ` with HTTP ${httpStatus}`}`;
+      return new HulyConnectionError({
+        message,
+        diagnostic: { operation, ...httpStatus === void 0 ? {} : { httpStatus } }
+      });
+    };
     HulyDataInvalidError = class extends Schema_exports.TaggedError()("HulyDataInvalidError", {
       operation: Schema_exports.String,
       entity: Schema_exports.String,
@@ -125144,7 +125200,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.49.6" : "0.0.0-dev";
+    VERSION = true ? "0.49.7" : "0.0.0-dev";
   }
 });
 
@@ -128260,7 +128316,7 @@ var init_tool_responses = __esm({
 });
 
 // src/mcp/error-mapping.ts
-var INVALID_PARAMS_TAGS, INTERNAL_ERROR_PREFIX, hulyUnavailableMessage, mapDomainErrorToMcp, isClientResolutionError, clientResolutionFailure, mapClientResolutionErrorToMcp, mapClientResolutionCauseToMcp, clientResolutionErrorMessage, clientResolutionCauseMessage, mapParseErrorToMcp, mapParseCauseToMcp, mapDomainCauseToMcp;
+var INVALID_PARAMS_TAGS, INTERNAL_ERROR_PREFIX, CONNECTION_ERROR_GUIDANCE, hulyConnectionMessage, hulyUnavailableMessage, mapDomainErrorToMcp, isClientResolutionError, clientResolutionFailure, redactResolutionDetail, mapClientResolutionErrorToMcp, mapClientResolutionCauseToMcp, clientResolutionErrorMessage, clientResolutionCauseMessage, mapParseErrorToMcp, mapParseCauseToMcp, mapDomainCauseToMcp;
 var init_error_mapping = __esm({
   "src/mcp/error-mapping.ts"() {
     "use strict";
@@ -128472,9 +128528,13 @@ var init_error_mapping = __esm({
     INTERNAL_ERROR_PREFIX = {
       FileUploadError: "File upload error",
       HulyStorageConfigError: "Storage configuration error",
-      HulyConnectionError: "Connection error",
       HulyAuthError: "Authentication error"
     };
+    CONNECTION_ERROR_GUIDANCE = "Verify HULY_URL, workspace, and network connectivity before retrying.";
+    hulyConnectionMessage = (error3) => {
+      const diagnostic = error3.diagnostic;
+      return diagnostic === void 0 ? `Connection error while communicating with Huly. ${CONNECTION_ERROR_GUIDANCE}` : `Connection error while communicating with Huly: ${diagnostic.operation} failed${diagnostic.httpStatus === void 0 ? "" : ` with HTTP ${diagnostic.httpStatus}`}. ${CONNECTION_ERROR_GUIDANCE}`;
+    };
     hulyUnavailableMessage = (error3) => {
       const failureGuidance = error3.failureKind === "timeout" ? " The request timed out; verify HULY_CONNECTION_TIMEOUT before retrying." : error3.failureKind === "dns" || error3.failureKind === "tls" ? " Verify the hostname, certificate, DNS, and proxy configuration before retrying." : "";
       if (isDefaultHulyCloudOrigin(error3.endpointOrigin)) {
@@ -128487,12 +128547,7 @@ var init_error_mapping = __esm({
         return createErrorResponse(hulyUnavailableMessage(error3), McpErrorCode.InternalError, error3._tag, warnings);
       }
       if (error3 instanceof HulyConnectionError) {
-        return createErrorResponse(
-          "Connection error while communicating with Huly. Verify HULY_URL, workspace, and network connectivity before retrying.",
-          McpErrorCode.InternalError,
-          error3._tag,
-          warnings
-        );
+        return createErrorResponse(hulyConnectionMessage(error3), McpErrorCode.InternalError, error3._tag, warnings);
       }
       if (INVALID_PARAMS_TAGS.has(error3._tag)) {
         return createErrorResponse(error3.message, McpErrorCode.InvalidParams, error3._tag, warnings);
@@ -128507,9 +128562,10 @@ var init_error_mapping = __esm({
       if (!Cause_exports.isCause(error3)) return void 0;
       return findRecoverableCauseFailure(error3, isClientResolutionError);
     };
+    redactResolutionDetail = (failure) => failure instanceof HulyConnectionError ? new HulyConnectionError({ message: "" }) : failure;
     mapClientResolutionErrorToMcp = (error3) => {
       const failure = clientResolutionFailure(error3);
-      return failure === void 0 ? mapDomainErrorToMcp(new HulyError({ message: "Failed to initialize Huly clients" })) : mapDomainErrorToMcp(failure);
+      return failure === void 0 ? mapDomainErrorToMcp(new HulyError({ message: "Failed to initialize Huly clients" })) : mapDomainErrorToMcp(redactResolutionDetail(failure));
     };
     mapClientResolutionCauseToMcp = (cause) => mapClientResolutionErrorToMcp(cause);
     clientResolutionErrorMessage = (error3) => mapClientResolutionErrorToMcp(error3).content[0].text;
@@ -178671,39 +178727,36 @@ var init_client = __esm({
           );
           const markupUrlConfig = { refUrl: UrlString.make(refUrl), imageUrl: UrlString.make(imageUrl) };
           const workbenchUrlConfig = { baseUrl: UrlString.make(config2.url), workspaceUrlSlug };
-          const withClient = (op, errorMsg) => Effect_exports.tryPromise({
-            try: () => op(client),
-            catch: (e) => new HulyConnectionError({ message: `${errorMsg}: ${String(e)}`, cause: e })
-          });
+          const withClient = (op, operation) => Effect_exports.tryPromise({ try: () => op(client), catch: (error3) => makeOperationConnectionError(operation, error3) });
           const operations = {
             getAccountUuid: () => accountUuid,
             getPrimarySocialId: () => primarySocialId,
             getSocialIds: () => socialIds,
             workbenchUrlConfig,
             markupUrlConfig,
-            findAll: (_class, query, options) => withClient((client2) => client2.findAll(_class, query, options), "findAll failed"),
-            findOne: (_class, query, options) => withClient((client2) => client2.findOne(_class, query, options), "findOne failed"),
+            findAll: (_class, query, options) => withClient((client2) => client2.findAll(_class, query, options), "findAll"),
+            findOne: (_class, query, options) => withClient((client2) => client2.findOne(_class, query, options), "findOne"),
             findAllInModel: (_class, query, options) => withClient(
               (client2) => Promise.resolve(client2.getModel().findAllSync(_class, query, options)),
-              "findAllInModel failed"
+              "findAllInModel"
             ),
-            createDoc: (_class, space, attributes, id2) => withClient((client2) => client2.createDoc(_class, space, attributes, id2), "createDoc failed"),
+            createDoc: (_class, space, attributes, id2) => withClient((client2) => client2.createDoc(_class, space, attributes, id2), "createDoc"),
             createDocIfNotMatched: (_class, space, attributes, id2, matchClass, matchQuery, scope3) => withClient(async (client2) => {
               const apply2 = client2.apply(scope3);
               apply2.notMatch(matchClass, matchQuery);
               await apply2.createDoc(_class, space, attributes, id2);
               return (await apply2.commit()).result ? "applied" : "condition-not-met";
-            }, "conditional createDoc failed"),
-            updateDoc: (_class, space, objectId, ops, retrieve) => withClient((client2) => client2.updateDoc(_class, space, objectId, ops, retrieve), "updateDoc failed"),
+            }, "conditionalCreateDoc"),
+            updateDoc: (_class, space, objectId, ops, retrieve) => withClient((client2) => client2.updateDoc(_class, space, objectId, ops, retrieve), "updateDoc"),
             updateDocIfMatched: (_class, space, objectId, matchQuery, operations2, scope3) => withClient(async (client2) => {
               const apply2 = client2.apply(scope3);
               apply2.match(_class, matchQuery);
               await apply2.updateDoc(_class, space, objectId, operations2);
               return (await apply2.commit()).result ? "applied" : "condition-not-met";
-            }, "conditional updateDoc failed"),
+            }, "conditionalUpdateDoc"),
             addCollection: (_class, space, attachedTo, attachedToClass, collection, attributes, id2) => withClient(
               (client2) => client2.addCollection(_class, space, attachedTo, attachedToClass, collection, attributes, id2),
-              "addCollection failed"
+              "addCollection"
             ),
             updateCollection: (_class, space, objectId, attachedTo, attachedToClass, collection, operations2, retrieve) => withClient(
               (client2) => client2.updateCollection(
@@ -178716,40 +178769,40 @@ var init_client = __esm({
                 operations2,
                 retrieve
               ),
-              "updateCollection failed"
+              "updateCollection"
             ),
             removeCollection: (_class, space, objectId, attachedTo, attachedToClass, collection) => withClient(
               (client2) => client2.removeCollection(_class, space, objectId, attachedTo, attachedToClass, collection),
-              "removeCollection failed"
+              "removeCollection"
             ),
-            removeDoc: (_class, space, objectId) => withClient((client2) => client2.removeDoc(_class, space, objectId), "removeDoc failed"),
+            removeDoc: (_class, space, objectId) => withClient((client2) => client2.removeDoc(_class, space, objectId), "removeDoc"),
             removeDocIfMatched: (_class, space, objectId, matchQuery, scope3) => withClient(async (client2) => {
               const apply2 = client2.apply(scope3);
               apply2.match(_class, matchQuery);
               await apply2.removeDoc(_class, space, objectId);
               return (await apply2.commit()).result ? "applied" : "condition-not-met";
-            }, "conditional removeDoc failed"),
+            }, "conditionalRemoveDoc"),
             createMixin: (objectId, objectClass, objectSpace, mixin, attributes) => withClient(
               (client2) => client2.createMixin(objectId, objectClass, objectSpace, mixin, attributes),
-              "createMixin failed"
+              "createMixin"
             ),
             updateMixin: (objectId, objectClass, objectSpace, mixin, attributes) => withClient(
               (client2) => client2.updateMixin(objectId, objectClass, objectSpace, mixin, attributes),
-              "updateMixin failed"
+              "updateMixin"
             ),
             uploadMarkup: (objectClass, objectId, objectAttr, markup, format5) => Effect_exports.tryPromise({
               try: () => markupOps.uploadMarkup(objectClass, objectId, objectAttr, markup, format5),
-              catch: (e) => new HulyConnectionError({ message: `uploadMarkup failed: ${String(e)}`, cause: e })
+              catch: (error3) => makeOperationConnectionError("uploadMarkup", error3)
             }),
             fetchMarkup: (objectClass, objectId, objectAttr, id2, format5) => Effect_exports.tryPromise({
               try: () => markupOps.fetchMarkup(objectClass, objectId, objectAttr, id2, format5),
-              catch: (e) => new HulyConnectionError({ message: `fetchMarkup failed: ${String(e)}`, cause: e })
+              catch: (error3) => makeOperationConnectionError("fetchMarkup", error3)
             }),
             updateMarkup: (objectClass, objectId, objectAttr, markup, format5) => Effect_exports.tryPromise({
               try: () => markupOps.updateMarkup(objectClass, objectId, objectAttr, markup, format5),
-              catch: (e) => new HulyConnectionError({ message: `updateMarkup failed: ${String(e)}`, cause: e })
+              catch: (error3) => makeOperationConnectionError("updateMarkup", error3)
             }),
-            searchFulltext: (query, options) => withClient((client2) => client2.searchFulltext(query, options), "searchFulltext failed")
+            searchFulltext: (query, options) => withClient((client2) => client2.searchFulltext(query, options), "searchFulltext")
           };
           return operations;
         })
@@ -183437,10 +183490,7 @@ var init_workspace_client = __esm({
             { url: config2.url, auth: config2.auth, workspace: config2.workspace },
             sdk
           );
-          const withClient = (op, errorMsg) => Effect_exports.tryPromise({
-            try: () => op(client),
-            catch: (e) => new HulyConnectionError({ message: `${errorMsg}: ${String(e)}`, cause: e })
-          });
+          const withClient = (op, operation) => Effect_exports.tryPromise({ try: () => op(client), catch: (error3) => makeOperationConnectionError(operation, error3) });
           const accessLinkIdentityOptions = (options) => ({
             ...options.firstName !== void 0 ? { firstName: options.firstName } : {},
             ...options.lastName !== void 0 ? { lastName: options.lastName } : {},
@@ -183454,25 +183504,19 @@ var init_workspace_client = __esm({
           });
           const toAccountClientAccessLinkOptions = (options) => options === void 0 ? void 0 : { ...accessLinkIdentityOptions(options), ...accessLinkTimingOptions(options) };
           const operations = {
-            getWorkspaceMembers: () => withClient((c) => c.getWorkspaceMembers(), "Failed to get workspace members"),
-            getPersonInfo: (account) => withClient((c) => c.getPersonInfo(account), "Failed to get person info"),
-            updateWorkspaceRole: (account, role) => withClient((c) => c.updateWorkspaceRole(account, role), "Failed to update workspace role"),
-            getWorkspaceInfo: (updateLastVisit) => withClient((c) => c.getWorkspaceInfo(updateLastVisit), "Failed to get workspace info"),
-            getUserWorkspaces: () => withClient((c) => c.getUserWorkspaces(), "Failed to get user workspaces"),
-            createWorkspace: (name, region) => withClient((c) => c.createWorkspace(name, region), "Failed to create workspace"),
-            deleteWorkspace: () => withClient((c) => c.deleteWorkspace(), "Failed to delete workspace"),
-            getUserProfile: (personUuid) => withClient((c) => c.getUserProfile(personUuid), "Failed to get user profile"),
-            setMyProfile: (profile) => withClient((c) => c.setMyProfile(profile), "Failed to set my profile"),
-            createAccessLink: (role, options) => withClient(
-              (c) => c.createAccessLink(role, toAccountClientAccessLinkOptions(options)),
-              "Failed to create access link"
-            ),
-            updateAllowReadOnlyGuests: (readOnlyGuestsAllowed) => withClient(
-              (c) => c.updateAllowReadOnlyGuests(readOnlyGuestsAllowed),
-              "Failed to update read-only guest setting"
-            ),
-            updateAllowGuestSignUp: (guestSignUpAllowed) => withClient((c) => c.updateAllowGuestSignUp(guestSignUpAllowed), "Failed to update guest sign-up setting"),
-            getRegionInfo: () => withClient((c) => c.getRegionInfo(), "Failed to get region info")
+            getWorkspaceMembers: () => withClient((c) => c.getWorkspaceMembers(), "getWorkspaceMembers"),
+            getPersonInfo: (account) => withClient((c) => c.getPersonInfo(account), "getPersonInfo"),
+            updateWorkspaceRole: (account, role) => withClient((c) => c.updateWorkspaceRole(account, role), "updateWorkspaceRole"),
+            getWorkspaceInfo: (updateLastVisit) => withClient((c) => c.getWorkspaceInfo(updateLastVisit), "getWorkspaceInfo"),
+            getUserWorkspaces: () => withClient((c) => c.getUserWorkspaces(), "getUserWorkspaces"),
+            createWorkspace: (name, region) => withClient((c) => c.createWorkspace(name, region), "createWorkspace"),
+            deleteWorkspace: () => withClient((c) => c.deleteWorkspace(), "deleteWorkspace"),
+            getUserProfile: (personUuid) => withClient((c) => c.getUserProfile(personUuid), "getUserProfile"),
+            setMyProfile: (profile) => withClient((c) => c.setMyProfile(profile), "setMyProfile"),
+            createAccessLink: (role, options) => withClient((c) => c.createAccessLink(role, toAccountClientAccessLinkOptions(options)), "createAccessLink"),
+            updateAllowReadOnlyGuests: (readOnlyGuestsAllowed) => withClient((c) => c.updateAllowReadOnlyGuests(readOnlyGuestsAllowed), "updateAllowReadOnlyGuests"),
+            updateAllowGuestSignUp: (guestSignUpAllowed) => withClient((c) => c.updateAllowGuestSignUp(guestSignUpAllowed), "updateAllowGuestSignUp"),
+            getRegionInfo: () => withClient((c) => c.getRegionInfo(), "getRegionInfo")
           };
           return operations;
         })
@@ -223136,7 +223180,7 @@ if (unsupportedRuntime) {
     detectedNodeVersion: process.versions.node,
     executable: process.execPath,
     requiredNodeVersion: nodeEngineRequirement,
-    serverVersion: "0.49.6"
+    serverVersion: "0.49.7"
   });
   startUnsupportedNodeMcp(config2);
 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firfi/huly-mcp",
-  "version": "0.49.6",
+  "version": "0.49.7",
   "description": "Huly MCP: feature-complete MCP server for Huly integration",
   "mcpName": "io.github.dearlordylord/huly-mcp",
   "type": "module",