@hexabot-ai/api 3.2.2-alpha.8 → 3.2.2-beta.0

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

@@ -0,0 +1,55 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import {
+  DirectionType,
+  McpServerTransport,
+  WorkflowType,
+} from '@/workflow/types';
+
+export const uuidSchema = z.string().uuid();
+
+export const jsonObjectSchema = z.record(z.string(), z.unknown());
+
+export const paginationSchema = {
+  limit: z.number().int().min(1).max(100).default(20),
+  skip: z.number().int().min(0).default(0),
+  sortBy: z.string().default('createdAt'),
+  sortDirection: z.enum(['ASC', 'DESC']).default('DESC'),
+};
+
+export const workflowPayloadSchema = {
+  name: z.string().min(1).optional(),
+  description: z.string().optional(),
+  type: z.enum(WorkflowType).optional(),
+  schedule: z.string().nullable().optional(),
+  inputSchema: jsonObjectSchema.optional(),
+  builtin: z.boolean().optional(),
+  x: z.number().optional(),
+  y: z.number().optional(),
+  zoom: z.number().optional(),
+  direction: z.enum(DirectionType).optional(),
+};
+
+export 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(),
+};
+
+export type PaginationArgs = {
+  limit: number;
+  skip: number;
+  sortBy: string;
+  sortDirection: 'ASC' | 'DESC';
+};

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

@@ -0,0 +1,7 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './index';

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

@@ -0,0 +1,29 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export const sanitizeCredential = <T extends Record<string, unknown>>(
+  credential: T,
+): Omit<T, 'value'> => {
+  const { value: _value, ...safeCredential } = credential;
+
+  return safeCredential;
+};
+
+export const omitKeysDeep = <T>(value: T, keys: readonly string[]): T => {
+  if (Array.isArray(value)) {
+    return value.map((item) => omitKeysDeep(item, keys)) as T;
+  }
+
+  if (value === null || typeof value !== 'object' || value instanceof Date) {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([key]) => !keys.includes(key))
+      .map(([key, nestedValue]) => [key, omitKeysDeep(nestedValue, keys)]),
+  ) as T;
+};

package/src/mcp/tools/index.ts

@@ -0,0 +1,51 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { HexabotCatalogMcpTools } from './catalog-mcp.tools';
+import { HexabotCmsMcpTools } from './cms-mcp.tools';
+import { HexabotCredentialMcpTools } from './credential-mcp.tools';
+import { HexabotMcpServerTools } from './mcp-server-mcp.tools';
+import { HexabotMemoryDefinitionMcpTools } from './memory-definition-mcp.tools';
+import { HexabotWorkflowMcpHelper } from './workflow-mcp.helper';
+import { HexabotWorkflowMcpTools } from './workflow-mcp.tools';
+import { HexabotWorkflowRunMcpTools } from './workflow-run-mcp.tools';
+import { HexabotWorkflowVersionMcpTools } from './workflow-version-mcp.tools';
+
+export * from './catalog-mcp.tools';
+
+export * from './cms-mcp.tools';
+
+export * from './credential-mcp.tools';
+
+export * from './hexabot-mcp-tool.base';
+
+export * from './hexabot-mcp.schemas';
+
+export * from './hexabot-mcp.utils';
+
+export * from './memory-definition-mcp.tools';
+
+export * from './mcp-server-mcp.tools';
+
+export * from './workflow-mcp.helper';
+
+export * from './workflow-mcp.tools';
+
+export * from './workflow-run-mcp.tools';
+
+export * from './workflow-version-mcp.tools';
+
+export const HEXABOT_MCP_TOOL_PROVIDERS = [
+  HexabotWorkflowMcpHelper,
+  HexabotWorkflowMcpTools,
+  HexabotWorkflowVersionMcpTools,
+  HexabotWorkflowRunMcpTools,
+  HexabotMemoryDefinitionMcpTools,
+  HexabotCatalogMcpTools,
+  HexabotCredentialMcpTools,
+  HexabotMcpServerTools,
+  HexabotCmsMcpTools,
+];

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

@@ -0,0 +1,135 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Action } from '@hexabot-ai/types';
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { Tool, ToolGuards } from '@rekog/mcp-nest';
+import { z } from 'zod';
+
+import { McpServerOrmEntity } from '@/workflow/entities/mcp-server.entity';
+import { McpServerService } from '@/workflow/services/mcp-server.service';
+import { McpServerTransport } from '@/workflow/types';
+
+import { McpPermission } from '../decorators/mcp-permission.decorator';
+import { McpPermissionGuard } from '../guards/mcp-permission.guard';
+
+import { HexabotMcpToolBase } from './hexabot-mcp-tool.base';
+import {
+  mcpServerPayloadSchema,
+  PaginationArgs,
+  paginationSchema,
+  uuidSchema,
+} from './hexabot-mcp.schemas';
+
+@Injectable()
+export class HexabotMcpServerTools extends HexabotMcpToolBase {
+  constructor(private readonly mcpServerService: McpServerService) {
+    super();
+  }
+
+  @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);
+  }
+}

package/src/mcp/tools/memory-definition-mcp.tools.ts

@@ -0,0 +1,125 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Action } from '@hexabot-ai/types';
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { Tool, ToolGuards } from '@rekog/mcp-nest';
+import { z } from 'zod';
+
+import { MemoryDefinitionService } from '@/workflow/services/memory-definition.service';
+import { MemoryScope } from '@/workflow/types';
+
+import { McpPermission } from '../decorators/mcp-permission.decorator';
+import { McpPermissionGuard } from '../guards/mcp-permission.guard';
+
+import { HexabotMcpToolBase } from './hexabot-mcp-tool.base';
+import {
+  jsonObjectSchema,
+  PaginationArgs,
+  paginationSchema,
+  uuidSchema,
+} from './hexabot-mcp.schemas';
+
+@Injectable()
+export class HexabotMemoryDefinitionMcpTools extends HexabotMcpToolBase {
+  constructor(
+    private readonly memoryDefinitionService: MemoryDefinitionService,
+  ) {
+    super();
+  }
+
+  @McpPermission('memorydefinition', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_memory_definition_search',
+    description: 'Search workflow memory definitions.',
+    parameters: z.object({
+      query: z.string().optional(),
+      scope: z.enum(MemoryScope).optional(),
+      ...paginationSchema,
+    }),
+  })
+  async searchMemoryDefinitions(
+    args: { query?: string; scope?: MemoryScope } & PaginationArgs,
+  ) {
+    const base = args.scope ? { scope: args.scope } : {};
+    const where = args.query
+      ? [
+          { ...base, name: this.contains(args.query) },
+          { ...base, slug: this.contains(args.query) },
+        ]
+      : base;
+
+    return await this.listWithCount(
+      this.memoryDefinitionService,
+      this.findOptions(args, where),
+    );
+  }
+
+  @McpPermission('memorydefinition', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_memory_definition_get',
+    description: 'Read one workflow memory definition.',
+    parameters: z.object({
+      id: uuidSchema,
+    }),
+  })
+  async getMemoryDefinition(args: { id: string }) {
+    const definition = await this.memoryDefinitionService.findOne(args.id);
+    if (!definition) {
+      throw new NotFoundException(`Memory definition ${args.id} not found`);
+    }
+
+    return definition;
+  }
+
+  @McpPermission('memorydefinition', Action.CREATE)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_memory_definition_create',
+    description: 'Create a workflow memory definition.',
+    parameters: z.object({
+      name: z.string().min(1),
+      slug: z.string().regex(/^[a-z0-9_]+$/),
+      scope: z.enum(MemoryScope),
+      schema: jsonObjectSchema,
+      ttlSeconds: z.number().int().min(1).nullable().optional(),
+    }),
+  })
+  async createMemoryDefinition(args: {
+    name: string;
+    slug: string;
+    scope: MemoryScope;
+    schema: Record<string, unknown>;
+    ttlSeconds?: number | null;
+  }) {
+    return await this.memoryDefinitionService.create(args as any);
+  }
+
+  @McpPermission('memorydefinition', Action.UPDATE)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_memory_definition_update',
+    description: 'Update a workflow memory definition.',
+    parameters: z.object({
+      id: uuidSchema,
+      name: z.string().min(1).optional(),
+      slug: z
+        .string()
+        .regex(/^[a-z0-9_]+$/)
+        .optional(),
+      scope: z.enum(MemoryScope).optional(),
+      schema: jsonObjectSchema.optional(),
+      ttlSeconds: z.number().int().min(1).nullable().optional(),
+    }),
+  })
+  async updateMemoryDefinition(args: { id: string } & Record<string, unknown>) {
+    const { id, ...updates } = args;
+
+    return await this.memoryDefinitionService.updateOne(id, updates as any);
+  }
+}

package/src/mcp/tools/workflow-mcp.helper.ts

@@ -0,0 +1,219 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  type WorkflowFull,
+  type WorkflowVersion,
+  type WorkflowVersionFull,
+} from '@hexabot-ai/types';
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+
+import { WorkflowNewVersionDto } from '@/workflow/dto/workflow-version.dto';
+import { parseWorkflowDefinition } from '@/workflow/lib/workflow-definition';
+import { WorkflowVersionService } from '@/workflow/services/workflow-version.service';
+import { WorkflowService } from '@/workflow/services/workflow.service';
+import { WorkflowVersionAction } from '@/workflow/types';
+
+type WorkflowVersionLike = WorkflowVersion | WorkflowVersionFull;
+
+type WorkflowVersionSummary = Pick<
+  WorkflowVersion,
+  | 'id'
+  | 'version'
+  | 'checksum'
+  | 'message'
+  | 'action'
+  | 'createdAt'
+  | 'updatedAt'
+> & {
+  parentVersion:
+    | WorkflowVersion['parentVersion']
+    | WorkflowVersionFull['parentVersion'];
+  workflow: WorkflowVersion['workflow'] | WorkflowVersionFull['workflow'];
+  createdBy: WorkflowVersion['createdBy'] | WorkflowVersionFull['createdBy'];
+  definitionYmlByteLength?: number;
+};
+
+type WorkflowSummary = Omit<
+  WorkflowFull,
+  'currentVersion' | 'publishedVersion' | 'definitionYml' | 'definition'
+> & {
+  currentVersion: WorkflowVersionSummary | null;
+  publishedVersion: WorkflowVersionSummary | null;
+  currentVersionId: string | null;
+  publishedVersionId: string | null;
+};
+
+@Injectable()
+export class HexabotWorkflowMcpHelper {
+  constructor(
+    private readonly workflowService: WorkflowService,
+    private readonly workflowVersionService: WorkflowVersionService,
+  ) {}
+
+  async requireWorkflow(id: string) {
+    const workflow = await this.workflowService.findOneAndPopulate(id);
+    if (!workflow) {
+      throw new NotFoundException(`Workflow ${id} not found`);
+    }
+
+    return workflow;
+  }
+
+  async commitWorkflowDefinition(params: {
+    workflowId: string;
+    definitionYml: string;
+    message?: string | null;
+    parentVersion?: string | null;
+    action?: WorkflowVersionAction;
+    createdBy: string;
+  }) {
+    const workflow = await this.requireWorkflow(params.workflowId);
+    try {
+      parseWorkflowDefinition(params.definitionYml);
+    } catch (error) {
+      throw new BadRequestException(
+        error instanceof Error ? error.message : 'Invalid workflow YAML',
+      );
+    }
+    const parentVersion =
+      params.parentVersion === undefined
+        ? this.resolveRelationId(workflow.currentVersion)
+        : params.parentVersion;
+    const payload: WorkflowNewVersionDto = {
+      workflow: params.workflowId,
+      definitionYml: params.definitionYml,
+      message: params.message ?? undefined,
+      parentVersion: parentVersion ?? undefined,
+      action: params.action ?? WorkflowVersionAction.update,
+      createdBy: params.createdBy,
+    };
+
+    return await this.workflowVersionService.commit(payload);
+  }
+
+  async restoreWorkflowVersionSnapshot(
+    args: { workflowId: string; versionId: string; message?: string },
+    updatedBy: string,
+  ) {
+    return await this.workflowVersionService.restoreVersion(
+      args.workflowId,
+      args.versionId,
+      {
+        updatedBy,
+        message: args.message,
+      },
+    );
+  }
+
+  buildWorkflowVersionStatus(workflow: WorkflowFull) {
+    const currentVersion = this.summarizeWorkflowVersion(
+      workflow.currentVersion,
+    );
+    const publishedVersion = this.summarizeWorkflowVersion(
+      workflow.publishedVersion,
+    );
+    const currentVersionId = currentVersion?.id ?? null;
+    const publishedVersionId = publishedVersion?.id ?? null;
+
+    return {
+      workflow: {
+        id: workflow.id,
+        name: workflow.name,
+        type: workflow.type,
+      },
+      currentVersion,
+      publishedVersion,
+      currentVersionId,
+      publishedVersionId,
+      isPublished: Boolean(publishedVersionId),
+      isCurrentVersionPublished:
+        Boolean(currentVersionId) && currentVersionId === publishedVersionId,
+      hasUnpublishedChanges:
+        Boolean(currentVersionId) && currentVersionId !== publishedVersionId,
+    };
+  }
+
+  summarizeWorkflow(workflow: WorkflowFull): WorkflowSummary {
+    const {
+      currentVersion,
+      publishedVersion,
+      definitionYml: _definitionYml,
+      definition: _definition,
+      ...metadata
+    } = workflow;
+    const currentVersionSummary = this.summarizeWorkflowVersion(currentVersion);
+    const publishedVersionSummary =
+      this.summarizeWorkflowVersion(publishedVersion);
+
+    return {
+      ...metadata,
+      currentVersion: currentVersionSummary,
+      publishedVersion: publishedVersionSummary,
+      currentVersionId: currentVersionSummary?.id ?? null,
+      publishedVersionId: publishedVersionSummary?.id ?? null,
+    };
+  }
+
+  summarizeWorkflowVersion(
+    version: WorkflowVersionLike | null | undefined,
+    options?: { includeDefinitionYmlByteLength?: boolean },
+  ): WorkflowVersionSummary | null {
+    if (!version) {
+      return null;
+    }
+    const {
+      id,
+      version: versionNumber,
+      checksum,
+      message,
+      action,
+      parentVersion,
+      workflow,
+      createdBy,
+      createdAt,
+      updatedAt,
+    } = version;
+    const summary = {
+      id,
+      version: versionNumber,
+      checksum,
+      message,
+      action,
+      parentVersion,
+      workflow,
+      createdBy,
+      createdAt,
+      updatedAt,
+      ...(options?.includeDefinitionYmlByteLength
+        ? {
+            definitionYmlByteLength:
+              typeof version.definitionYml === 'string'
+                ? Buffer.byteLength(version.definitionYml, 'utf8')
+                : undefined,
+          }
+        : {}),
+    };
+
+    return Object.fromEntries(
+      Object.entries(summary).filter(([, value]) => value !== undefined),
+    ) as WorkflowVersionSummary;
+  }
+
+  private resolveRelationId(
+    relation: string | { id?: string | null } | null | undefined,
+  ): string | null {
+    if (typeof relation === 'string') {
+      return relation;
+    }
+
+    return relation?.id ?? null;
+  }
+}