@hexabot-ai/api 3.2.2-alpha.1 → 3.2.2-alpha.11

package/src/mcp/README.md

@@ -0,0 +1,244 @@
+# Hexabot API MCP Server
+
+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.
+
+The implementation uses `@rekog/mcp-nest` with Streamable HTTP transport.
+Authentication is Hexabot-native: users create personal MCP bearer tokens from
+their Hexabot account and paste those tokens into MCP clients such as Codex or
+Claude Code.
+
+## Runtime endpoints
+
+All routes are mounted under the existing API prefix.
+
+| Route | Purpose |
+| --- | --- |
+| `/api/mcp` | Streamable HTTP MCP endpoint. |
+| `/api/mcp-token` | List and create MCP personal access tokens for the current Hexabot user. |
+| `/api/mcp-token/:id/revoke` | Revoke one MCP personal access token owned by the current Hexabot user. |
+
+The MCP endpoint is stateful and uses `mcp-session-id` headers for sessions.
+
+## Enabling the server
+
+Set the MCP variables in `packages/api/.env` and restart the API.
+
+```dotenv
+MCP_ENABLED=true
+MCP_SERVER_NAME=hexabot-api
+MCP_SERVER_TITLE=Hexabot API MCP Server
+MCP_SERVER_VERSION=1.0.0
+```
+
+## Authentication and authorization
+
+MCP requests use Hexabot-issued bearer tokens. Tokens are prefixed with
+`hbt_mcp_` and are shown only once when created.
+
+The guard chain is:
+
+1. `HexabotMcpTokenGuard` validates the bearer token hash and resolves its
+   active Hexabot owner.
+2. `McpPermissionGuard` checks the requested tool against Hexabot role
+   permissions.
+
+Token storage is intentionally secret-safe:
+
+- Raw token values are never stored.
+- Only a SHA-256 token hash and short display prefix are persisted.
+- The full token is returned only in the create-token response.
+- Revoked, expired, unknown, or inactive-owner tokens are rejected.
+
+The token owner must be an active Hexabot user.
+
+Tool permissions use `@McpPermission(model, action)` metadata and the existing
+`PermissionService`. For example, workflow read tools require the caller role to
+have `workflow:read`; workflow mutation tools require the corresponding create
+or update permission.
+
+## Creating a bearer token
+
+Use the authenticated Hexabot REST API to create a token for the current user:
+
+```http
+POST /api/mcp-token
+Content-Type: application/json
+
+{
+  "name": "Codex",
+  "expiresAt": "2026-12-31T23:59:59.000Z"
+}
+```
+
+The response includes the raw bearer token once:
+
+```json
+{
+  "token": "hbt_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "record": {
+    "id": "token-id",
+    "name": "Codex",
+    "tokenPrefix": "hbt_mcp_xxxxxxxx",
+    "owner": "user-id",
+    "expiresAt": "2026-12-31T23:59:59.000Z",
+    "lastUsedAt": null,
+    "revokedAt": null,
+    "createdAt": "2026-05-05T00:00:00.000Z",
+    "updatedAt": "2026-05-05T00:00:00.000Z"
+  }
+}
+```
+
+Copy the `token` value into the MCP client. After this response, Hexabot cannot
+show the raw token again.
+
+List token metadata:
+
+```http
+GET /api/mcp-token
+```
+
+Revoke a token:
+
+```http
+POST /api/mcp-token/{id}/revoke
+```
+
+## Connecting an MCP client
+
+Use a Streamable HTTP MCP client pointed at:
+
+```text
+http://localhost:3000/api/mcp
+```
+
+Production clients should use the public API origin, for example:
+
+```text
+https://api.example.com/api/mcp
+```
+
+If a client requires a JSON config entry, the exact field names depend on the
+client, but the effective configuration should be equivalent to:
+
+```json
+{
+  "mcpServers": {
+    "hexabot": {
+      "type": "http",
+      "url": "http://localhost:3000/api/mcp",
+      "headers": {
+        "Authorization": "Bearer hbt_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+## Tool surface
+
+### Workflows
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `hexabot_workflow_search` | `workflow:read` | Search workflows by metadata. |
+| `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_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.
+
+### Workflow versions and runs
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `hexabot_workflow_version_search` | `workflowversion:read` | List YAML versions for a workflow. |
+| `hexabot_workflow_version_get` | `workflowversion:read` | Read one workflow YAML version. |
+| `hexabot_workflow_version_update` | `workflowversion:update` | Update workflow version metadata. |
+| `hexabot_workflow_version_restore` | `workflowversion:create` | Restore a previous version by creating a new snapshot. |
+| `hexabot_workflow_run_search` | `workflowrun:read` | Search workflow runs by workflow and status. |
+| `hexabot_workflow_run_get` | `workflowrun:read` | Read one workflow run with populated workflow metadata. |
+
+### Memory definitions
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `hexabot_memory_definition_search` | `memorydefinition:read` | Search memory definitions. |
+| `hexabot_memory_definition_get` | `memorydefinition:read` | Read one memory definition. |
+| `hexabot_memory_definition_create` | `memorydefinition:create` | Create a memory definition. |
+| `hexabot_memory_definition_update` | `memorydefinition:update` | Update a memory definition. |
+
+### Actions and runtime bindings
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `hexabot_action_search` | `workflow:read` | Search available workflow actions and schemas. |
+| `hexabot_action_get` | `workflow:read` | Read one workflow action schema. |
+| `hexabot_binding_search` | `workflow:read` | Search runtime binding kind schemas. |
+| `hexabot_binding_get` | `workflow:read` | Read one runtime binding schema. |
+
+### Credentials
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `hexabot_credential_search` | `credential:read` | Search credential metadata by name or owner. |
+| `hexabot_credential_get` | `credential:read` | Read credential metadata. |
+
+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.
+
+### CMS and RAG content
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `hexabot_content_type_search` | `contenttype:read` | Search CMS content types. |
+| `hexabot_content_type_get` | `contenttype:read` | Read one content type. |
+| `hexabot_content_type_create` | `contenttype:create` | Create a content type. |
+| `hexabot_content_type_update` | `contenttype:update` | Update a content type. |
+| `hexabot_content_search` | `content:read` | Search CMS content records. |
+| `hexabot_content_get` | `content:read` | Read one content record. |
+| `hexabot_content_create` | `content:create` | Create a content record. |
+| `hexabot_content_update` | `content:update` | Update a content record. |
+| `hexabot_rag_content_search` | `content:read` | Search indexed CMS content through RAG retrieval. |
+
+## Extending the MCP module
+
+Add new tools in `tools/hexabot-mcp.tools.ts`.
+
+Each tool should:
+
+1. Use `@Tool()` with a stable `hexabot_*` name and a Zod parameter schema.
+2. Use `@ToolGuards([McpPermissionGuard])`.
+3. Use `@McpPermission(model, action)` with existing Hexabot permission models.
+4. Return plain JSON-serializable data.
+5. Avoid exposing secrets, tokens, connection strings, or raw credential values.
+
+If a tool changes API behavior or a public contract, update this README and the
+relevant tests in `packages/api/src/mcp`.
+
+## Tests
+
+Run the API checks from the repository root:
+
+```bash
+pnpm --filter @hexabot-ai/api run typecheck
+pnpm --filter @hexabot-ai/api run lint
+pnpm --filter @hexabot-ai/api run test
+pnpm --filter @hexabot-ai/api run test:e2e
+pnpm --filter @hexabot-ai/api run build
+```
+
+The MCP e2e tests are enabled only when `MCP_ENABLED=true`. A local test command
+is:
+
+```bash
+NODE_ENV=test MCP_ENABLED=true pnpm --filter @hexabot-ai/api run test:e2e
+```

package/src/mcp/controllers/mcp-token.controller.ts

@@ -0,0 +1,64 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Post,
+  Req,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Request } from 'express';
+
+import { UuidParam } from '@/utils';
+
+import { McpTokenCreateDto } from '../dto/mcp-token.dto';
+import { McpTokenService } from '../services/mcp-token.service';
+
+type AuthenticatedRequest = Request & {
+  user?: { id?: string };
+  session?: Request['session'] & {
+    passport?: { user?: { id?: string } };
+  };
+};
+
+@Controller('mcp-token')
+export class McpTokenController {
+  constructor(private readonly mcpTokenService: McpTokenService) {}
+
+  @Get()
+  async list(@Req() req: AuthenticatedRequest) {
+    return await this.mcpTokenService.findOwnedTokens(this.getUserId(req));
+  }
+
+  @Post()
+  async create(
+    @Body() dto: McpTokenCreateDto,
+    @Req() req: AuthenticatedRequest,
+  ) {
+    return await this.mcpTokenService.createPersonalToken(
+      this.getUserId(req),
+      dto,
+    );
+  }
+
+  @Post(':id/revoke')
+  @HttpCode(200)
+  async revoke(@UuidParam('id') id: string, @Req() req: AuthenticatedRequest) {
+    return await this.mcpTokenService.revokeOwnedToken(this.getUserId(req), id);
+  }
+
+  private getUserId(req: AuthenticatedRequest): string {
+    const userId = req.user?.id ?? req.session?.passport?.user?.id;
+    if (!userId) {
+      throw new UnauthorizedException('Authenticated user is required');
+    }
+
+    return userId;
+  }
+}

package/src/mcp/decorators/mcp-permission.decorator.ts

@@ -0,0 +1,23 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { SetMetadata } from '@nestjs/common';
+
+import { Action } from '@/user/types/action.type';
+import { TModel } from '@/user/types/model.type';
+
+export const MCP_PERMISSION_METADATA_KEY = 'mcp:hexabot-permission';
+
+export type McpPermissionMetadata = {
+  model: TModel;
+  action: Action;
+};
+
+export const McpPermission = (model: TModel, action: Action): MethodDecorator =>
+  SetMetadata(MCP_PERMISSION_METADATA_KEY, {
+    model,
+    action,
+  } satisfies McpPermissionMetadata);

package/src/mcp/dto/mcp-token.dto.ts

@@ -0,0 +1,48 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { mcpTokenFullSchema, mcpTokenSchema } from '@hexabot-ai/types';
+import { ApiProperty, ApiPropertyOptional, PartialType } from '@nestjs/swagger';
+import {
+  IsDateString,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+
+import { TDto } from '@/utils/types/dto.types';
+
+export class McpTokenCreateDto {
+  @ApiProperty({
+    description: 'Human-readable MCP token name',
+    type: String,
+  })
+  @IsNotEmpty()
+  @IsString()
+  name!: string;
+
+  @ApiPropertyOptional({
+    description: 'Optional token expiry date',
+    type: String,
+    format: 'date-time',
+  })
+  @IsOptional()
+  @IsDateString()
+  expiresAt?: string | null;
+}
+
+export class McpTokenUpdateDto extends PartialType(McpTokenCreateDto) {}
+
+export type McpTokenDto = TDto<
+  {
+    plain: typeof mcpTokenSchema;
+    full: typeof mcpTokenFullSchema;
+  },
+  {
+    create: McpTokenCreateDto;
+    update: McpTokenUpdateDto;
+  }
+>;

package/src/mcp/entities/mcp-token.entity.ts

@@ -0,0 +1,60 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { mcpTokenFullSchema, mcpTokenSchema } from '@hexabot-ai/types';
+import {
+  Column,
+  Entity,
+  Index,
+  JoinColumn,
+  ManyToOne,
+  RelationId,
+} from 'typeorm';
+
+import { DatetimeColumn } from '@/database';
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+import { UserOrmEntity } from '@/user/entities/user.entity';
+import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
+
+import { McpTokenDto } from '../dto/mcp-token.dto';
+
+@Entity({ name: 'mcp_tokens' })
+@Index(['tokenHash'], { unique: true })
+@Index(['owner'])
+export class McpTokenOrmEntity extends BaseOrmEntity<McpTokenDto> {
+  plainCls = mcpTokenSchema;
+
+  fullCls = mcpTokenFullSchema;
+
+  @Column()
+  name!: string;
+
+  @Column({ name: 'token_hash', type: 'text' })
+  tokenHash!: string;
+
+  @Column({ name: 'token_prefix', length: 32 })
+  tokenPrefix!: string;
+
+  @ManyToOne(() => UserOrmEntity, {
+    nullable: false,
+    onDelete: 'CASCADE',
+  })
+  @JoinColumn({ name: 'owner_id' })
+  @AsRelation()
+  owner!: UserOrmEntity;
+
+  @RelationId((token: McpTokenOrmEntity) => token.owner)
+  private readonly ownerId!: string;
+
+  @DatetimeColumn({ name: 'expires_at', nullable: true })
+  expiresAt!: Date | null;
+
+  @DatetimeColumn({ name: 'last_used_at', nullable: true })
+  lastUsedAt!: Date | null;
+
+  @DatetimeColumn({ name: 'revoked_at', nullable: true })
+  revokedAt!: Date | null;
+}

package/src/mcp/guards/hexabot-mcp-token.guard.ts

@@ -0,0 +1,55 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { Request } from 'express';
+
+import { McpTokenService } from '../services/mcp-token.service';
+import { HexabotMcpRequest } from '../types';
+
+@Injectable()
+export class HexabotMcpTokenGuard implements CanActivate {
+  constructor(private readonly moduleRef: ModuleRef) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<HexabotMcpRequest>();
+    const token = this.extractTokenFromHeader(request);
+
+    if (!token) {
+      throw new UnauthorizedException('MCP bearer token is required');
+    }
+
+    const { user, tokenId } =
+      await this.getMcpTokenService().authenticateBearerToken(token);
+
+    request.hexabotUser = user;
+    request.user = user;
+    request.mcpTokenId = tokenId;
+
+    return true;
+  }
+
+  private extractTokenFromHeader(request: Request): string | undefined {
+    const authHeader = request.headers.authorization;
+    if (!authHeader) {
+      return undefined;
+    }
+
+    const [type, token] = authHeader.split(' ');
+
+    return type === 'Bearer' ? token : undefined;
+  }
+
+  private getMcpTokenService(): McpTokenService {
+    return this.moduleRef.get(McpTokenService, { strict: false });
+  }
+}

package/src/mcp/guards/mcp-permission.guard.ts

@@ -0,0 +1,61 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+
+import {
+  MCP_PERMISSION_METADATA_KEY,
+  McpPermissionMetadata,
+} from '@/mcp/decorators/mcp-permission.decorator';
+import { PermissionService } from '@/user/services/permission.service';
+
+import { HexabotMcpRequest } from '../types';
+
+@Injectable()
+export class McpPermissionGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly permissionService: PermissionService,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const permission = this.reflector.getAllAndOverride<McpPermissionMetadata>(
+      MCP_PERMISSION_METADATA_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!permission) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<HexabotMcpRequest>();
+    const user = request.hexabotUser ?? request.user;
+    const roleIds = Array.isArray(user?.roles) ? user.roles : [];
+
+    if (roleIds.length === 0) {
+      throw new ForbiddenException('MCP tool requires a Hexabot role');
+    }
+
+    const permissions = await this.permissionService.getPermissions();
+    const hasPermission = roleIds.some((roleId) =>
+      permissions[roleId]?.[permission.model]?.includes(permission.action),
+    );
+
+    if (!hasPermission) {
+      throw new ForbiddenException(
+        `MCP tool requires ${permission.action} permission on ${permission.model}`,
+      );
+    }
+
+    return true;
+  }
+}

package/src/mcp/mcp-api.module.ts

@@ -0,0 +1,61 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { randomUUID } from 'crypto';
+
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { McpModule, McpTransportType } from '@rekog/mcp-nest';
+
+import { ActionsModule } from '@/actions/actions.module';
+import { BindingsModule } from '@/bindings/bindings.module';
+import { CmsModule } from '@/cms/cms.module';
+import { config } from '@/config';
+import { UserModule } from '@/user/user.module';
+import { WorkflowModule } from '@/workflow/workflow.module';
+
+import { McpTokenController } from './controllers/mcp-token.controller';
+import { McpTokenOrmEntity } from './entities/mcp-token.entity';
+import { HexabotMcpTokenGuard } from './guards/hexabot-mcp-token.guard';
+import { McpPermissionGuard } from './guards/mcp-permission.guard';
+import { McpTokenRepository } from './repositories/mcp-token.repository';
+import { McpTokenService } from './services/mcp-token.service';
+import { HexabotMcpTools } from './tools/hexabot-mcp.tools';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([McpTokenOrmEntity]),
+    McpModule.forRoot({
+      name: config.mcp.serverName,
+      title: config.mcp.serverTitle,
+      version: config.mcp.serverVersion,
+      description: config.mcp.serverDescription,
+      instructions: config.mcp.serverInstructions,
+      transport: McpTransportType.STREAMABLE_HTTP,
+      mcpEndpoint: 'mcp',
+      guards: [HexabotMcpTokenGuard],
+      streamableHttp: {
+        enableJsonResponse: false,
+        sessionIdGenerator: () => randomUUID(),
+        statelessMode: false,
+      },
+    }),
+    ActionsModule,
+    BindingsModule,
+    CmsModule,
+    UserModule,
+    WorkflowModule,
+  ],
+  providers: [
+    HexabotMcpTokenGuard,
+    McpPermissionGuard,
+    McpTokenRepository,
+    McpTokenService,
+    HexabotMcpTools,
+  ],
+  controllers: [McpTokenController],
+})
+export class McpApiModule {}

package/src/mcp/repositories/mcp-token.repository.ts

@@ -0,0 +1,34 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+
+import { McpTokenOrmEntity } from '../entities/mcp-token.entity';
+
+@Injectable()
+export class McpTokenRepository extends BaseOrmRepository<McpTokenOrmEntity> {
+  constructor(
+    @InjectRepository(McpTokenOrmEntity)
+    repository: Repository<McpTokenOrmEntity>,
+  ) {
+    super(repository, ['owner']);
+  }
+
+  async findOneByHash(tokenHash: string): Promise<McpTokenOrmEntity | null> {
+    return await this.repository.findOne({
+      where: { tokenHash },
+      relations: ['owner', 'owner.roles'],
+    });
+  }
+
+  async touchLastUsedAt(id: string, lastUsedAt = new Date()): Promise<void> {
+    await this.repository.update(id, { lastUsedAt });
+  }
+}