@hexabot-ai/api 3.2.2-alpha.9 → 3.2.2-beta.1

package/src/mcp/services/mcp-token.service.ts

@@ -0,0 +1,138 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { createHash, randomBytes } from 'crypto';
+
+import type { McpToken, User } from '@hexabot-ai/types';
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { FindManyOptions } from 'typeorm';
+
+import { UserOrmEntity } from '@/user/entities/user.entity';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { McpTokenCreateDto } from '../dto/mcp-token.dto';
+import { McpTokenOrmEntity } from '../entities/mcp-token.entity';
+import { McpTokenRepository } from '../repositories/mcp-token.repository';
+
+export const MCP_PERSONAL_TOKEN_PREFIX = 'hbt_mcp_';
+
+@Injectable()
+export class McpTokenService extends BaseOrmService<McpTokenOrmEntity> {
+  constructor(readonly repository: McpTokenRepository) {
+    super(repository);
+  }
+
+  async createPersonalToken(
+    ownerId: string,
+    dto: McpTokenCreateDto,
+  ): Promise<{ token: string; record: McpToken }> {
+    const token = this.generateToken();
+    const expiresAt = this.parseOptionalExpiry(dto.expiresAt);
+    const record = await this.repository.create({
+      name: dto.name,
+      owner: ownerId,
+      tokenHash: this.hashToken(token),
+      tokenPrefix: this.getTokenPrefix(token),
+      expiresAt,
+      lastUsedAt: null,
+      revokedAt: null,
+    } as any);
+
+    return { token, record };
+  }
+
+  async findOwnedTokens(ownerId: string): Promise<McpToken[]> {
+    return await this.repository.find({
+      where: { owner: { id: ownerId } },
+      order: { createdAt: 'DESC' },
+    } as FindManyOptions<McpTokenOrmEntity>);
+  }
+
+  async revokeOwnedToken(ownerId: string, id: string): Promise<McpToken> {
+    const token = await this.repository.findOne({
+      where: { id, owner: { id: ownerId } },
+    } as any);
+
+    if (!token) {
+      throw new NotFoundException(`MCP token ${id} not found`);
+    }
+
+    return await this.repository.updateOne(
+      {
+        where: { id, owner: { id: ownerId } },
+      } as any,
+      { revokedAt: new Date() } as any,
+    );
+  }
+
+  async authenticateBearerToken(
+    token: string,
+  ): Promise<{ user: User; tokenId: string }> {
+    if (!token.startsWith(MCP_PERSONAL_TOKEN_PREFIX)) {
+      throw new UnauthorizedException('Invalid MCP token');
+    }
+
+    const record = await this.repository.findOneByHash(this.hashToken(token));
+
+    if (!record) {
+      throw new UnauthorizedException('Invalid MCP token');
+    }
+
+    if (record.revokedAt) {
+      throw new UnauthorizedException('MCP token has been revoked');
+    }
+
+    if (record.expiresAt && record.expiresAt <= new Date()) {
+      throw new UnauthorizedException('MCP token has expired');
+    }
+
+    const owner = record.owner as UserOrmEntity | undefined;
+    if (!owner?.state) {
+      throw new UnauthorizedException('MCP token owner is inactive');
+    }
+
+    await this.repository.touchLastUsedAt(record.id);
+
+    return {
+      user: owner.toPlainCls() as User,
+      tokenId: record.id,
+    };
+  }
+
+  private generateToken(): string {
+    return `${MCP_PERSONAL_TOKEN_PREFIX}${randomBytes(32).toString('base64url')}`;
+  }
+
+  private hashToken(token: string): string {
+    return createHash('sha256').update(token).digest('hex');
+  }
+
+  private getTokenPrefix(token: string): string {
+    return token.slice(0, MCP_PERSONAL_TOKEN_PREFIX.length + 8);
+  }
+
+  private parseOptionalExpiry(value?: string | null): Date | null {
+    if (!value) {
+      return null;
+    }
+
+    const expiresAt = new Date(value);
+    if (Number.isNaN(expiresAt.getTime())) {
+      throw new BadRequestException('Invalid MCP token expiry date');
+    }
+
+    if (expiresAt <= new Date()) {
+      throw new BadRequestException('MCP token expiry must be in the future');
+    }
+
+    return expiresAt;
+  }
+}

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

@@ -0,0 +1,122 @@
+/*
+ * 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 { ActionService } from '@/actions/actions.service';
+import { RuntimeBindingsService } from '@/bindings/runtime-bindings.service';
+import { WorkflowType } from '@/workflow/types';
+
+import { McpPermission } from '../decorators/mcp-permission.decorator';
+import { McpPermissionGuard } from '../guards/mcp-permission.guard';
+
+@Injectable()
+export class HexabotCatalogMcpTools {
+  constructor(
+    private readonly actionService: ActionService,
+    private readonly runtimeBindingsService: RuntimeBindingsService,
+  ) {}
+
+  @McpPermission('workflow', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_action_search',
+    description: 'Search available workflow actions and their schemas.',
+    parameters: z.object({
+      query: z.string().optional(),
+      workflowType: z.enum(WorkflowType).optional(),
+    }),
+  })
+  async searchActions(args: { query?: string; workflowType?: WorkflowType }) {
+    const query = args.query?.toLowerCase();
+    const actions = this.actionService.getAllSchemaDefinitions(
+      args.workflowType,
+    );
+
+    return {
+      items: query
+        ? actions.filter((action) =>
+            [
+              action.name,
+              action.description,
+              action.group,
+              ...(action.workflowTypes ?? []),
+            ]
+              .filter(Boolean)
+              .some((value) => `${value}`.toLowerCase().includes(query)),
+          )
+        : actions,
+    };
+  }
+
+  @McpPermission('workflow', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_action_get',
+    description: 'Read schema metadata for one workflow action.',
+    parameters: z.object({
+      name: z.string().min(1),
+    }),
+  })
+  async getAction(args: { name: string }) {
+    const action = this.actionService
+      .getAllSchemaDefinitions()
+      .find((entry) => entry.name === args.name);
+    if (!action) {
+      throw new NotFoundException(`Action ${args.name} not found`);
+    }
+
+    return action;
+  }
+
+  @McpPermission('workflow', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_binding_search',
+    description: 'Search workflow runtime binding kind schemas.',
+    parameters: z.object({
+      query: z.string().optional(),
+    }),
+  })
+  async searchBindings(args: { query?: string }) {
+    const query = args.query?.toLowerCase();
+    const entries = Object.entries(
+      this.runtimeBindingsService.getAllSchemaDefinitions(),
+    ).map(([kind, definition]) => ({ kind, ...definition }));
+
+    return {
+      items: query
+        ? entries.filter((entry) =>
+            [entry.kind, entry.icon, entry.color]
+              .filter(Boolean)
+              .some((value) => `${value}`.toLowerCase().includes(query)),
+          )
+        : entries,
+    };
+  }
+
+  @McpPermission('workflow', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_binding_get',
+    description: 'Read schema metadata for one workflow runtime binding kind.',
+    parameters: z.object({
+      kind: z.string().min(1),
+    }),
+  })
+  async getBinding(args: { kind: string }) {
+    const bindings = this.runtimeBindingsService.getAllSchemaDefinitions();
+    const binding = bindings[args.kind];
+    if (!binding) {
+      throw new NotFoundException(`Binding kind ${args.kind} not found`);
+    }
+
+    return { kind: args.kind, ...binding };
+  }
+}

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

@@ -0,0 +1,239 @@
+/*
+ * 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 { ContentTypeOrmEntity } from '@/cms/entities/content-type.entity';
+import { ContentOrmEntity } from '@/cms/entities/content.entity';
+import { ContentTypeService } from '@/cms/services/content-type.service';
+import { ContentService } from '@/cms/services/content.service';
+
+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 HexabotCmsMcpTools extends HexabotMcpToolBase {
+  constructor(
+    private readonly contentTypeService: ContentTypeService,
+    private readonly contentService: ContentService,
+  ) {
+    super();
+  }
+
+  @McpPermission('contenttype', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_content_type_search',
+    description: 'Search CMS content types.',
+    parameters: z.object({
+      query: z.string().optional(),
+      ...paginationSchema,
+    }),
+  })
+  async searchContentTypes(args: { query?: string } & PaginationArgs) {
+    const where = args.query ? { name: this.contains(args.query) } : {};
+
+    return await this.listWithCount(
+      this.contentTypeService,
+      this.findOptions<ContentTypeOrmEntity>(args, where),
+    );
+  }
+
+  @McpPermission('contenttype', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_content_type_get',
+    description: 'Read one CMS content type.',
+    parameters: z.object({
+      id: uuidSchema,
+    }),
+  })
+  async getContentType(args: { id: string }) {
+    const contentType = await this.contentTypeService.findOne(args.id);
+    if (!contentType) {
+      throw new NotFoundException(`Content type ${args.id} not found`);
+    }
+
+    return contentType;
+  }
+
+  @McpPermission('contenttype', Action.CREATE)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_content_type_create',
+    description: 'Create a CMS content type.',
+    parameters: z.object({
+      name: z.string().min(1),
+      schema: jsonObjectSchema,
+    }),
+  })
+  async createContentType(args: {
+    name: string;
+    schema: Record<string, unknown>;
+  }) {
+    return await this.contentTypeService.create(args as any);
+  }
+
+  @McpPermission('contenttype', Action.UPDATE)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_content_type_update',
+    description: 'Update a CMS content type.',
+    parameters: z.object({
+      id: uuidSchema,
+      name: z.string().min(1).optional(),
+      schema: jsonObjectSchema.optional(),
+    }),
+  })
+  async updateContentType(args: { id: string } & Record<string, unknown>) {
+    const { id, ...updates } = args;
+
+    return await this.contentTypeService.updateOne(id, updates as any);
+  }
+
+  @McpPermission('content', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_content_search',
+    description: 'Search CMS content records.',
+    parameters: z.object({
+      query: z.string().optional(),
+      contentTypeId: uuidSchema.optional(),
+      status: z.boolean().optional(),
+      ...paginationSchema,
+    }),
+  })
+  async searchContent(
+    args: {
+      query?: string;
+      contentTypeId?: string;
+      status?: boolean;
+    } & PaginationArgs,
+  ) {
+    if (args.query) {
+      return {
+        items: await this.contentService.textSearch(args.query, {
+          status: args.status,
+          contentTypeId: args.contentTypeId,
+          limit: args.limit,
+        }),
+        limit: args.limit,
+        skip: 0,
+      };
+    }
+
+    const where = {
+      ...(args.contentTypeId
+        ? { contentType: { id: args.contentTypeId } }
+        : {}),
+      ...(args.status !== undefined ? { status: args.status } : {}),
+    } as any;
+
+    return await this.listWithCount(
+      this.contentService,
+      this.findOptions<ContentOrmEntity>(args, where),
+    );
+  }
+
+  @McpPermission('content', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_content_get',
+    description: 'Read one CMS content record.',
+    parameters: z.object({
+      id: uuidSchema,
+    }),
+  })
+  async getContent(args: { id: string }) {
+    const content = await this.contentService.findOneAndPopulate(args.id);
+    if (!content) {
+      throw new NotFoundException(`Content ${args.id} not found`);
+    }
+
+    return content;
+  }
+
+  @McpPermission('content', Action.CREATE)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_content_create',
+    description: 'Create a CMS content record.',
+    parameters: z.object({
+      contentType: uuidSchema,
+      title: z.string().min(1),
+      status: z.boolean().optional(),
+      properties: jsonObjectSchema.optional(),
+    }),
+  })
+  async createContent(args: {
+    contentType: string;
+    title: string;
+    status?: boolean;
+    properties?: Record<string, unknown>;
+  }) {
+    return await this.contentService.create(args as any);
+  }
+
+  @McpPermission('content', Action.UPDATE)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_content_update',
+    description: 'Update a CMS content record.',
+    parameters: z.object({
+      id: uuidSchema,
+      contentType: uuidSchema.optional(),
+      title: z.string().min(1).optional(),
+      status: z.boolean().optional(),
+      properties: jsonObjectSchema.optional(),
+    }),
+  })
+  async updateContent(args: { id: string } & Record<string, unknown>) {
+    const { id, ...updates } = args;
+
+    return await this.contentService.updateOne(id, updates as any);
+  }
+
+  @McpPermission('content', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_rag_content_search',
+    description: 'Search indexed CMS content through Hexabot RAG retrieval.',
+    parameters: z.object({
+      query: z.string().min(1),
+      mode: z.enum(['embedding', 'lexical']).optional(),
+      limit: z.number().int().min(1).max(50).default(10),
+      contentTypeId: uuidSchema.optional(),
+      includeInactive: z.boolean().optional(),
+    }),
+  })
+  async searchRagContent(args: {
+    query: string;
+    mode?: 'embedding' | 'lexical';
+    limit: number;
+    contentTypeId?: string;
+    includeInactive?: boolean;
+  }) {
+    return {
+      items: await this.contentService.retrieve(args.query, {
+        mode: args.mode,
+        limit: args.limit,
+        contentTypeId: args.contentTypeId,
+        includeInactive: args.includeInactive,
+      }),
+    };
+  }
+}

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

@@ -0,0 +1,81 @@
+/*
+ * 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 { CredentialService } from '@/user/services/credential.service';
+
+import { McpPermission } from '../decorators/mcp-permission.decorator';
+import { McpPermissionGuard } from '../guards/mcp-permission.guard';
+
+import { HexabotMcpToolBase } from './hexabot-mcp-tool.base';
+import {
+  PaginationArgs,
+  paginationSchema,
+  uuidSchema,
+} from './hexabot-mcp.schemas';
+import { sanitizeCredential } from './hexabot-mcp.utils';
+
+@Injectable()
+export class HexabotCredentialMcpTools extends HexabotMcpToolBase {
+  constructor(private readonly credentialService: CredentialService) {
+    super();
+  }
+
+  @McpPermission('credential', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_credential_search',
+    description:
+      'Search credentials by metadata only. Secret credential values are never returned.',
+    parameters: z.object({
+      query: z.string().optional(),
+      ownerId: uuidSchema.optional(),
+      ...paginationSchema,
+    }),
+  })
+  async searchCredentials(
+    args: { query?: string; ownerId?: string } & PaginationArgs,
+  ) {
+    const where = {
+      ...(args.ownerId ? { owner: { id: args.ownerId } } : {}),
+      ...(args.query ? { name: this.contains(args.query) } : {}),
+    } as any;
+    const result = await this.listWithCount(
+      this.credentialService,
+      this.findOptions(args, where),
+    );
+
+    return {
+      ...result,
+      items: result.items.map((credential) =>
+        sanitizeCredential(credential as Record<string, unknown>),
+      ),
+    };
+  }
+
+  @McpPermission('credential', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_credential_get',
+    description:
+      'Read credential metadata. Secret credential values are never returned.',
+    parameters: z.object({
+      id: uuidSchema,
+    }),
+  })
+  async getCredential(args: { id: string }) {
+    const credential = await this.credentialService.findOneAndPopulate(args.id);
+    if (!credential) {
+      throw new NotFoundException(`Credential ${args.id} not found`);
+    }
+
+    return sanitizeCredential(credential as Record<string, unknown>);
+  }
+}

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

@@ -0,0 +1,74 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { User } from '@hexabot-ai/types';
+import { UnauthorizedException } from '@nestjs/common';
+import { FindManyOptions, Like } from 'typeorm';
+
+import { HexabotMcpRequest } from '../types';
+
+import { PaginationArgs } from './hexabot-mcp.schemas';
+
+export abstract class HexabotMcpToolBase {
+  protected findOptions<Entity>(
+    args: PaginationArgs,
+    where: FindManyOptions<Entity>['where'],
+  ): FindManyOptions<Entity> {
+    return {
+      where,
+      take: args.limit,
+      skip: args.skip,
+      order: { [args.sortBy]: args.sortDirection } as any,
+    };
+  }
+
+  protected async listWithCount<Entity>(
+    service: {
+      findAndPopulate(options?: FindManyOptions<Entity>): Promise<unknown[]>;
+      count(options?: FindManyOptions<Entity>): Promise<number>;
+    },
+    options: FindManyOptions<Entity>,
+  ) {
+    const [items, total] = await Promise.all([
+      service.findAndPopulate(options),
+      service.count({ where: options.where }),
+    ]);
+
+    return {
+      items,
+      total,
+      limit: options.take,
+      skip: options.skip,
+    };
+  }
+
+  protected contains(value: string) {
+    return Like(`%${value}%`);
+  }
+
+  protected resolveRelationId(
+    relation: string | { id?: string | null } | null | undefined,
+  ): string | null {
+    if (typeof relation === 'string') {
+      return relation;
+    }
+
+    return relation?.id ?? null;
+  }
+
+  protected getActor(request?: HexabotMcpRequest): User {
+    const actor = request?.hexabotUser ?? request?.user;
+    if (!actor?.id) {
+      throw new UnauthorizedException('MCP Hexabot user is required');
+    }
+
+    return actor as User;
+  }
+
+  protected getActorId(request?: HexabotMcpRequest): string {
+    return this.getActor(request).id;
+  }
+}

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';
+};