@gohcltech/bitbucket-mcp
Version:
Bitbucket integration for Claude via Model Context Protocol
143 lines • 5.8 kB
JavaScript
/**
* @fileoverview Zod validation schemas for Bitbucket workspace operations.
*
* This module provides comprehensive validation schemas for workspace-related
* operations using Zod for runtime type checking and validation. These schemas
* ensure that data conforms to Bitbucket API v2.0 specifications and provide
* type-safe validation for MCP tool inputs and API responses.
*
* Key features:
* - Runtime validation of workspace API responses
* - Input parameter validation for workspace tools
* - Type-safe schema definitions that match TypeScript interfaces
* - Comprehensive error reporting for validation failures
*/
import { z } from 'zod';
import { WorkspaceBaseSchema } from '../common.js';
// =============================================================================
// RESPONSE SCHEMAS
// =============================================================================
/**
* Zod schema for validating Bitbucket workspace API responses.
*
* This schema validates the structure of workspace objects returned by
* Bitbucket's REST API v2.0. It ensures that all required fields are present
* and correctly typed, while allowing optional fields to be undefined.
*
* The schema uses `satisfies z.ZodType<Workspace>` to guarantee that the
* validation schema matches the TypeScript interface exactly, preventing
* drift between runtime validation and compile-time types.
*
* @example
* ```typescript
* const apiResponse = await fetch('/2.0/workspaces/gohcl');
* const rawData = await apiResponse.json();
* const workspace = WorkspaceSchema.parse(rawData);
* ```
*/
export const WorkspaceSchema = z.object({
/**
* Unique UUID identifier for the workspace.
* Must be a non-empty string in UUID format.
*/
uuid: z.string().min(1, 'Workspace UUID is required'),
/**
* Human-readable workspace name.
* Must be a non-empty string, can contain any valid Unicode characters.
*/
name: z.string().min(1, 'Workspace name is required'),
/**
* URL-safe workspace identifier.
* Must follow Bitbucket's slug naming conventions:
* - Alphanumeric characters, hyphens, and underscores only
* - No consecutive special characters
* - Cannot start or end with special characters
*/
slug: z.string().min(1, 'Workspace slug is required')
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid workspace slug format'),
/**
* Privacy flag indicating workspace visibility.
* Boolean value determining if workspace is publicly visible.
*/
is_private: z.boolean(),
/**
* ISO 8601 timestamp of workspace creation.
* Must be a valid ISO string format (YYYY-MM-DDTHH:mm:ss.sssZ).
*/
created_on: z.string().datetime('Invalid creation timestamp format'),
/**
* ISO 8601 timestamp of last workspace modification.
* Must be a valid ISO string format (YYYY-MM-DDTHH:mm:ss.sssZ).
*/
updated_on: z.string().datetime('Invalid update timestamp format'),
/**
* Collection of related URLs and resources for the workspace.
* Contains links to web interface and optional avatar image.
*/
links: z.object({
/**
* Link to the workspace's main page in Bitbucket web interface.
* Always present and contains the direct URL to the workspace.
*/
html: z.object({
/** Full URL to the workspace page, must be a valid HTTP(S) URL */
href: z.string().url('Invalid workspace HTML link'),
}),
/**
* Optional link to the workspace's avatar image.
* May be undefined if no custom avatar is configured.
*/
avatar: z.object({
/** Full URL to the avatar image, must be a valid HTTP(S) URL */
href: z.string().url('Invalid avatar link'),
}).optional(),
}),
});
// =============================================================================
// INPUT VALIDATION SCHEMAS
// =============================================================================
/**
* Base validation schema for workspace-related tool parameters.
*
* This schema validates the fundamental workspace identifier required by
* most workspace-related MCP tools. It reuses the common WorkspaceBaseSchema
* to ensure consistent validation across all workspace operations.
*
* Validates:
* - Workspace slug format (alphanumeric, hyphens, underscores)
* - Required field presence
* - Length constraints
*/
export const WorkspaceInputSchema = WorkspaceBaseSchema;
/**
* Input validation schema for the get_workspace MCP tool.
*
* This schema validates parameters passed to the get_workspace tool,
* ensuring that only the required workspace identifier is provided.
* It uses Zod's `pick` method to extract only the workspace field
* from the base schema, providing focused validation.
*
* @example
* ```typescript
* const input = { workspace: 'gohcl' };
* const validatedInput = GetWorkspaceInputSchema.parse(input);
* ```
*/
export const GetWorkspaceInputSchema = WorkspaceInputSchema.pick({ workspace: true });
// =============================================================================
// TYPE GUARDS
// =============================================================================
/**
* Type guard functions for workspace-related data validation.
*
* Note: The isWorkspaceInput type guard function is exported from
* common.ts to avoid circular dependencies and ensure it's available
* across all domain modules. This centralized approach prevents
* conflicts and maintains consistency in type checking.
*
* Available type guards:
* - isWorkspaceInput(input): Validates workspace input parameters
*
* @see {@link ../common.ts} for type guard implementations
*/
//# sourceMappingURL=schemas.js.map