@hexabot-ai/api 3.2.2-alpha.12 → 3.2.2-alpha.14

package/dist/utils/test/port.d.ts

@@ -0,0 +1,8 @@
+export declare const getJestPort: () => number;
+export declare const getJestHost: () => string;
+export declare const getJestBaseUrl: () => string;
+export declare const configureJestNetworkEnv: () => {
+    port: number;
+    baseUrl: string;
+    apiOrigin: string;
+};

package/dist/utils/test/port.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureJestNetworkEnv = exports.getJestBaseUrl = exports.getJestHost = exports.getJestPort = void 0;
+const DEFAULT_JEST_PORT = 3001;
+const JEST_HOST = '127.0.0.1';
+const parsePort = (value, envName) => {
+    if (!value) {
+        return DEFAULT_JEST_PORT;
+    }
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`Invalid ${envName} "${value}". Expected a TCP port between 1 and 65535.`);
+    }
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid ${envName} "${value}". Expected a TCP port between 1 and 65535.`);
+    }
+    return port;
+};
+const getJestPort = () => parsePort(process.env.JEST_PORT, 'JEST_PORT');
+exports.getJestPort = getJestPort;
+const getJestHost = () => JEST_HOST;
+exports.getJestHost = getJestHost;
+const getJestBaseUrl = () => `http://${(0, exports.getJestHost)()}:${(0, exports.getJestPort)()}`;
+exports.getJestBaseUrl = getJestBaseUrl;
+const configureJestNetworkEnv = () => {
+    const port = (0, exports.getJestPort)();
+    const baseUrl = `http://${(0, exports.getJestHost)()}:${port}`;
+    const apiOrigin = process.env.JEST_API_ORIGIN ?? `${baseUrl}/api`;
+    process.env.PORT = `${port}`;
+    process.env.API_ORIGIN = apiOrigin;
+    return { port, baseUrl, apiOrigin };
+};
+exports.configureJestNetworkEnv = configureJestNetworkEnv;
+//# sourceMappingURL=port.js.map

package/dist/utils/test/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../../src/utils/test/port.ts"],"names":[],"mappings":";;;AAMA,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAC/B,MAAM,SAAS,GAAG,WAAW,CAAC;AAC9B,MAAM,SAAS,GAAG,CAAC,KAAyB,EAAE,OAAe,EAAU,EAAE;IACvE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,WAAW,OAAO,KAAK,KAAK,6CAA6C,CAC1E,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAE3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,WAAW,OAAO,KAAK,KAAK,6CAA6C,CAC1E,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEK,MAAM,WAAW,GAAG,GAAW,EAAE,CACtC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AADnC,QAAA,WAAW,eACwB;AAEzC,MAAM,WAAW,GAAG,GAAW,EAAE,CAAC,SAAS,CAAC;AAAtC,QAAA,WAAW,eAA2B;AAE5C,MAAM,cAAc,GAAG,GAAW,EAAE,CACzC,UAAU,IAAA,mBAAW,GAAE,IAAI,IAAA,mBAAW,GAAE,EAAE,CAAC;AADhC,QAAA,cAAc,kBACkB;AAEtC,MAAM,uBAAuB,GAAG,GAAG,EAAE;IAC1C,MAAM,IAAI,GAAG,IAAA,mBAAW,GAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,UAAU,IAAA,mBAAW,GAAE,IAAI,IAAI,EAAE,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,GAAG,OAAO,MAAM,CAAC;IAElE,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,IAAI,EAAE,CAAC;IAC7B,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,SAAS,CAAC;IAEnC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACtC,CAAC,CAAC;AATW,QAAA,uBAAuB,2BASlC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hexabot-ai/api",
   "private": false,
-  "version": "3.2.2-alpha.12",
+  "version": "3.2.2-alpha.14",
   "description": "Hexabot is a solution for creating and managing chatbots across multiple channels, leveraging AI for advanced conversational capabilities. It provides a user-friendly interface for building, training, and deploying chatbots with integrated support for various messaging platforms.",
   "author": "Hexastack",
   "license": "FCL-1.0-ALv2",
@@ -92,8 +92,8 @@
     "typeorm": "^0.3.28",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@hexabot-ai/agentic": "3.1.2-alpha.12",
-    "@hexabot-ai/types": "3.0.2-alpha.12"
+    "@hexabot-ai/agentic": "3.1.2-alpha.14",
+    "@hexabot-ai/types": "3.0.2-alpha.14"
   },
   "devDependencies": {
     "@compodoc/compodoc": "^1.1.31",
@@ -144,7 +144,7 @@
     "tsconfig-paths": "^4.2.0",
     "tsconfig-paths-jest": "^0.0.1",
     "typescript": "^5.1.3",
-    "@hexabot-ai/frontend": "3.2.2-alpha.12"
+    "@hexabot-ai/frontend": "3.2.2-alpha.14"
   },
   "optionalDependencies": {
     "@css-inline/css-inline-linux-arm64-musl": "^0.14.1",

package/src/mcp/README.md

@@ -2,7 +2,7 @@
 
 This module exposes Hexabot API capabilities through the Model Context Protocol
 (MCP) so coding agents can inspect and manage workflows, workflow runs, memory
-definitions, actions, credentials, and CMS content.
+definitions, actions, credentials, MCP servers, and CMS content.
 
 The implementation uses `@rekog/mcp-nest` with Streamable HTTP transport.
 Authentication is Hexabot-native: users create personal MCP bearer tokens from
@@ -147,13 +147,15 @@ client, but the effective configuration should be equivalent to:
 | `hexabot_workflow_get` | `workflow:read` | Read one workflow with populated version metadata. |
 | `hexabot_workflow_create` | `workflow:create` | Create a workflow and optionally commit initial YAML. |
 | `hexabot_workflow_update` | `workflow:update` | Update workflow metadata and optionally commit YAML. |
+| `hexabot_workflow_yaml_validate` | `workflow:read` | Validate workflow definition YAML without creating a version. |
 | `hexabot_workflow_yaml_commit` | `workflowversion:create` | Validate and commit workflow definition YAML. |
 | `hexabot_workflow_publish` | `workflow:update` | Publish the current workflow version. |
 | `hexabot_workflow_unpublish` | `workflow:update` | Clear the published workflow version. |
 | `hexabot_workflow_run` | `workflowrun:create` | Run a manual or scheduled workflow and return the run summary. |
 
 Workflow YAML is validated with `parseWorkflowDefinition()` before a version is
-created.
+created. Coding agents can call `hexabot_workflow_yaml_validate` first to get
+structured validation errors without mutating workflow state.
 
 ### Workflow versions and runs
 
@@ -195,6 +197,15 @@ Credential secret values are never returned. The MCP tools remove the `value`
 field from all credential responses and do not support searching by secret
 value.
 
+### MCP servers
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `hexabot_mcp_server_search` | `mcpserver:read` | Search configured MCP servers. |
+| `hexabot_mcp_server_get` | `mcpserver:read` | Read one configured MCP server. |
+| `hexabot_mcp_server_create` | `mcpserver:create` | Create an MCP server configuration. |
+| `hexabot_mcp_server_update` | `mcpserver:update` | Update an MCP server configuration. |
+
 ### CMS and RAG content
 
 | Tool | Permission | Purpose |

package/src/mcp/tools/hexabot-mcp.tools.ts

@@ -4,6 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
+import { validateWorkflow } from '@hexabot-ai/agentic';
 import { Action, type User } from '@hexabot-ai/types';
 import {
   BadRequestException,
@@ -23,6 +24,7 @@ import { ContentTypeService } from '@/cms/services/content-type.service';
 import { ContentService } from '@/cms/services/content.service';
 import { CredentialService } from '@/user/services/credential.service';
 import { WorkflowNewVersionDto } from '@/workflow/dto/workflow-version.dto';
+import { McpServerOrmEntity } from '@/workflow/entities/mcp-server.entity';
 import { WorkflowRunOrmEntity } from '@/workflow/entities/workflow-run.entity';
 import { WorkflowVersionOrmEntity } from '@/workflow/entities/workflow-version.entity';
 import { WorkflowOrmEntity } from '@/workflow/entities/workflow.entity';
@@ -32,12 +34,14 @@ import {
 } from '@/workflow/lib/trigger-event-wrapper';
 import { parseWorkflowDefinition } from '@/workflow/lib/workflow-definition';
 import { AgenticService } from '@/workflow/services/agentic.service';
+import { McpServerService } from '@/workflow/services/mcp-server.service';
 import { MemoryDefinitionService } from '@/workflow/services/memory-definition.service';
 import { WorkflowRunService } from '@/workflow/services/workflow-run.service';
 import { WorkflowVersionService } from '@/workflow/services/workflow-version.service';
 import { WorkflowService } from '@/workflow/services/workflow.service';
 import {
   DirectionType,
+  McpServerTransport,
   MemoryScope,
   WorkflowType,
   WorkflowVersionAction,
@@ -67,6 +71,16 @@ const workflowPayloadSchema = {
   zoom: z.number().optional(),
   direction: z.enum(DirectionType).optional(),
 };
+const mcpServerPayloadSchema = {
+  name: z.string().min(1).optional(),
+  enabled: z.boolean().optional(),
+  transport: z.enum(McpServerTransport).optional(),
+  url: z.string().nullable().optional(),
+  command: z.string().nullable().optional(),
+  args: z.array(z.string()).nullable().optional(),
+  cwd: z.string().nullable().optional(),
+  credential: uuidSchema.nullable().optional(),
+};
 
 type PaginationArgs = {
   limit: number;
@@ -88,6 +102,7 @@ export class HexabotMcpTools {
     private readonly credentialService: CredentialService,
     private readonly contentTypeService: ContentTypeService,
     private readonly contentService: ContentService,
+    private readonly mcpServerService: McpServerService,
   ) {}
 
   @McpPermission('workflow', Action.READ)
@@ -257,6 +272,36 @@ export class HexabotMcpTools {
     });
   }
 
+  @McpPermission('workflow', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_workflow_yaml_validate',
+    description:
+      'Validate workflow definition YAML without creating a workflow version.',
+    parameters: z.object({
+      definitionYml: z.string().min(1),
+      validateActions: z.boolean().default(true),
+    }),
+  })
+  async validateWorkflowYaml(args: {
+    definitionYml: string;
+    validateActions?: boolean;
+  }) {
+    const validateActions = args.validateActions ?? true;
+    const validation = validateWorkflow(args.definitionYml, {
+      bindingKinds: this.runtimeBindingsService.getRegistry(),
+      ...(validateActions
+        ? { actions: this.getWorkflowValidationActions() }
+        : {}),
+    });
+
+    if (!validation.success) {
+      return { valid: false, errors: validation.errors };
+    }
+
+    return { valid: true, errors: [], definition: validation.data };
+  }
+
   @McpPermission('workflowversion', Action.READ)
   @ToolGuards([McpPermissionGuard])
   @Tool({
@@ -723,6 +768,109 @@ export class HexabotMcpTools {
     return HexabotMcpTools.sanitizeCredential(credential);
   }
 
+  @McpPermission('mcpserver', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_mcp_server_search',
+    description: 'Search configured MCP servers.',
+    parameters: z.object({
+      query: z.string().optional(),
+      enabled: z.boolean().optional(),
+      transport: z.enum(McpServerTransport).optional(),
+      credentialId: uuidSchema.optional(),
+      ...paginationSchema,
+    }),
+  })
+  async searchMcpServers(
+    args: {
+      query?: string;
+      enabled?: boolean;
+      transport?: McpServerTransport;
+      credentialId?: string;
+    } & PaginationArgs,
+  ) {
+    const base = {
+      ...(args.enabled !== undefined ? { enabled: args.enabled } : {}),
+      ...(args.transport ? { transport: args.transport } : {}),
+      ...(args.credentialId ? { credential: { id: args.credentialId } } : {}),
+    };
+    const where = args.query
+      ? [
+          { ...base, name: this.contains(args.query) },
+          { ...base, url: this.contains(args.query) },
+          { ...base, command: this.contains(args.query) },
+        ]
+      : base;
+
+    return await this.listWithCount(
+      this.mcpServerService,
+      this.findOptions<McpServerOrmEntity>(args, where as any),
+    );
+  }
+
+  @McpPermission('mcpserver', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_mcp_server_get',
+    description: 'Read one configured MCP server.',
+    parameters: z.object({
+      id: uuidSchema,
+    }),
+  })
+  async getMcpServer(args: { id: string }) {
+    const server = await this.mcpServerService.findOneAndPopulate(args.id);
+    if (!server) {
+      throw new NotFoundException(`MCP server ${args.id} not found`);
+    }
+
+    return server;
+  }
+
+  @McpPermission('mcpserver', Action.CREATE)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_mcp_server_create',
+    description: 'Create an MCP server configuration.',
+    parameters: z.object({
+      ...mcpServerPayloadSchema,
+      name: z.string().min(1),
+    }),
+  })
+  async createMcpServer(args: {
+    name: string;
+    enabled?: boolean;
+    transport?: McpServerTransport;
+    url?: string | null;
+    command?: string | null;
+    args?: string[] | null;
+    cwd?: string | null;
+    credential?: string | null;
+  }) {
+    return await this.mcpServerService.create({
+      enabled: true,
+      transport: McpServerTransport.http,
+      ...args,
+    } as any);
+  }
+
+  @McpPermission('mcpserver', Action.UPDATE)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_mcp_server_update',
+    description: 'Update an MCP server configuration.',
+    parameters: z.object({
+      id: uuidSchema,
+      ...mcpServerPayloadSchema,
+    }),
+  })
+  async updateMcpServer(args: { id: string } & Record<string, unknown>) {
+    const { id, ...updates } = args;
+
+    await this.getMcpServer({ id });
+
+    return await this.mcpServerService.updateOne(id, updates as any);
+  }
+
   @McpPermission('contenttype', Action.READ)
   @ToolGuards([McpPermissionGuard])
   @Tool({
@@ -1026,6 +1174,17 @@ export class HexabotMcpTools {
     return Like(`%${value}%`);
   }
 
+  private getWorkflowValidationActions() {
+    return Object.fromEntries(
+      Object.entries(this.actionService.getRegistry()).map(
+        ([actionName, action]) => [
+          actionName,
+          { supportedBindings: action.supportedBindings ?? [] },
+        ],
+      ),
+    );
+  }
+
   private getActor(request?: HexabotMcpRequest): User {
     const actor = request?.hexabotUser ?? request?.user;
     if (!actor?.id) {

package/src/utils/test/port.ts

@@ -0,0 +1,48 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+const DEFAULT_JEST_PORT = 3001;
+const JEST_HOST = '127.0.0.1';
+const parsePort = (value: string | undefined, envName: string): number => {
+  if (!value) {
+    return DEFAULT_JEST_PORT;
+  }
+
+  if (!/^\d+$/.test(value)) {
+    throw new Error(
+      `Invalid ${envName} "${value}". Expected a TCP port between 1 and 65535.`,
+    );
+  }
+
+  const port = Number(value);
+
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(
+      `Invalid ${envName} "${value}". Expected a TCP port between 1 and 65535.`,
+    );
+  }
+
+  return port;
+};
+
+export const getJestPort = (): number =>
+  parsePort(process.env.JEST_PORT, 'JEST_PORT');
+
+export const getJestHost = (): string => JEST_HOST;
+
+export const getJestBaseUrl = (): string =>
+  `http://${getJestHost()}:${getJestPort()}`;
+
+export const configureJestNetworkEnv = () => {
+  const port = getJestPort();
+  const baseUrl = `http://${getJestHost()}:${port}`;
+  const apiOrigin = process.env.JEST_API_ORIGIN ?? `${baseUrl}/api`;
+
+  process.env.PORT = `${port}`;
+  process.env.API_ORIGIN = apiOrigin;
+
+  return { port, baseUrl, apiOrigin };
+};