@gohcltech/bitbucket-mcp
Version:
Bitbucket integration for Claude via Model Context Protocol
323 lines • 12.3 kB
JavaScript
/**
* @fileoverview Zod validation schemas for Bitbucket pull request operations.
*
* This module provides comprehensive validation schemas for pull request-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 pull request API responses
* - Comment and discussion validation
* - Input parameter validation for pull request management tools
* - State transition and workflow validation
* - Type-safe schema definitions matching TypeScript interfaces
* - Comprehensive error reporting for validation failures
*/
import { z } from 'zod';
import { RepositoryBaseSchema } from '../common.js';
/**
* Zod schema for validating Bitbucket pull request API responses.
*
* This schema validates the structure of pull request objects returned by
* Bitbucket's REST API v2.0. It ensures that all required fields are present
* and correctly typed, including source/destination branch information,
* author details, and state tracking.
*
* @example
* ```typescript
* const apiResponse = await fetch('/2.0/repositories/gohcl/bitbucket-mcp/pullrequests/123');
* const rawData = await apiResponse.json();
* const pullRequest = PullRequestSchema.parse(rawData);
* ```
*/
export const PullRequestSchema = z.object({
/**
* Unique numeric identifier for the pull request.
* Must be a positive integer assigned sequentially by Bitbucket.
*/
id: z.number().int().positive('Pull request ID must be a positive integer'),
/**
* Pull request title summarizing the changes.
* Must be a non-empty string with reasonable length limits.
*/
title: z.string().min(1, 'Pull request title is required')
.max(200, 'Pull request title too long'),
/**
* Optional detailed description of the pull request.
* Can contain markdown formatting and comprehensive change details.
*/
description: z.string().max(10000, 'Pull request description too long').optional(),
/**
* Current lifecycle state of the pull request.
* Must be one of the predefined Bitbucket pull request states.
*/
state: z.enum(['OPEN', 'MERGED', 'DECLINED', 'SUPERSEDED'], {
errorMap: () => ({ message: 'Invalid pull request state' })
}),
/**
* Information about the pull request author.
* Contains identification details for the user who created the PR.
*/
author: z.object({
/** Display name of the pull request author */
display_name: z.string().min(1, 'Author display name is required'),
/** Unique UUID identifier for the author */
uuid: z.string().min(1, 'Author UUID is required'),
}),
/**
* Source branch and repository information.
* Defines where the changes are coming from.
*/
source: z.object({
/**
* Source branch containing the proposed changes.
*/
branch: z.object({
/** Name of the source branch */
name: z.string().min(1, 'Source branch name is required')
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._/-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$/, 'Invalid branch name format'),
}),
/**
* Repository containing the source branch.
*/
repository: z.object({
/** Name of the source repository */
name: z.string().min(1, 'Source repository name is required'),
}),
}),
/**
* Destination branch and repository information.
* Defines where the changes will be merged.
*/
destination: z.object({
/**
* Destination branch that will receive the changes.
*/
branch: z.object({
/** Name of the destination branch */
name: z.string().min(1, 'Destination branch name is required')
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._/-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$/, 'Invalid branch name format'),
}),
/**
* Repository containing the destination branch.
*/
repository: z.object({
/** Name of the destination repository */
name: z.string().min(1, 'Destination repository name is required'),
}),
}),
/**
* ISO 8601 timestamp when the pull request was created.
* Must be a valid datetime string with timezone information.
*/
created_on: z.string().datetime('Invalid creation timestamp format'),
/**
* ISO 8601 timestamp when the pull request was last modified.
* Must be a valid datetime string with timezone information.
*/
updated_on: z.string().datetime('Invalid update timestamp format'),
/**
* Collection of related URLs for the pull request.
* Provides navigation links to web interface and related resources.
*/
links: z.object({
/**
* Direct link to the pull request's page in Bitbucket web interface.
*/
html: z.object({
/** Full URL to the pull request page */
href: z.string().url('Invalid pull request HTML link'),
}),
}),
});
/**
* Zod schema for validating pull request comment API responses.
*
* This schema validates the structure of comment objects returned by
* Bitbucket's pull request comments API. It ensures proper formatting
* of comment content, author information, and timestamps.
*
* @example
* ```typescript
* const apiResponse = await fetch('/2.0/repositories/gohcl/bitbucket-mcp/pullrequests/123/comments');
* const rawData = await apiResponse.json();
* const comments = rawData.values.map(comment => CommentSchema.parse(comment));
* ```
*/
export const CommentSchema = z.object({
/**
* Unique numeric identifier for the comment.
* Must be a positive integer assigned by Bitbucket.
*/
id: z.number().int().positive('Comment ID must be a positive integer'),
/**
* Comment content in various formats.
* Contains the actual text and formatting information.
*/
content: z.object({
/**
* Raw comment text as entered by the user.
* May contain markdown, mentions, and other formatting.
*/
raw: z.string().min(1, 'Comment content cannot be empty')
.max(10000, 'Comment content too long'),
}),
/**
* Information about the comment author.
* Contains user identification for attribution.
*/
user: z.object({
/**
* Display name of the comment author.
* Must be a non-empty string for user identification.
*/
display_name: z.string().min(1, 'User display name is required'),
}),
/**
* ISO 8601 timestamp when the comment was created.
* Must be a valid datetime string with timezone information.
*/
created_on: z.string().datetime('Invalid comment creation timestamp format'),
/**
* ISO 8601 timestamp when the comment was last modified.
* Must be a valid datetime string with timezone information.
*/
updated_on: z.string().datetime('Invalid comment update timestamp format'),
});
/**
* Input validation schema for pull request-related MCP tool parameters.
*
* This schema validates the basic parameters required by pull request tools,
* extending the repository base schema with pull request-specific validation.
* Used by tools that operate on existing pull requests.
*
* @example
* ```typescript
* const input = {
* workspace: 'gohcl',
* repo_slug: 'bitbucket-mcp',
* pull_request_id: 123
* };
* const validatedInput = PullRequestInputSchema.parse(input);
* ```
*/
export const PullRequestInputSchema = RepositoryBaseSchema.extend({
/**
* Numeric identifier for the pull request.
* Must be a positive integer referencing an existing pull request.
*/
pull_request_id: z.number().int().positive('Pull request ID must be a positive integer'),
});
/**
* Input validation schema for the create_pull_request MCP tool.
*
* This schema validates parameters for creating new pull requests,
* including title, description, source/destination branches, and
* optional settings like auto-closing the source branch.
*
* @example
* ```typescript
* const input = {
* workspace: 'gohcl',
* repo_slug: 'bitbucket-mcp',
* title: 'Add OAuth 2.0 authentication',
* description: 'Implements secure OAuth flow...',
* source_branch: 'feature/oauth-auth',
* destination_branch: 'develop',
* close_source_branch: true
* };
* const validatedInput = CreatePullRequestInputSchema.parse(input);
* ```
*/
export const CreatePullRequestInputSchema = RepositoryBaseSchema.extend({
/**
* Pull request title summarizing the changes.
* Must be descriptive and within character limits.
*/
title: z.string().min(1, 'Title is required').max(200, 'Title too long'),
/**
* Optional detailed description of the pull request.
* Can contain markdown formatting and comprehensive change details.
*/
description: z.string().max(10000, 'Description too long').optional(),
/**
* Name of the source branch containing the changes.
* Must be a valid git branch name that exists in the repository.
*/
source_branch: z.string().min(1, 'Source branch is required')
.max(100, 'Source branch name too long')
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._/-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$/, 'Invalid source branch name format'),
/**
* Name of the destination branch that will receive the changes.
* Must be a valid git branch name that exists in the repository.
*/
destination_branch: z.string().min(1, 'Destination branch is required')
.max(100, 'Destination branch name too long')
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._/-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$/, 'Invalid destination branch name format'),
/**
* Whether to automatically close the source branch when PR is merged.
* Defaults to false to preserve branches unless explicitly requested.
*/
close_source_branch: z.boolean().optional().default(false),
});
/**
* Input validation schema for the list_pull_requests MCP tool.
*
* This schema validates parameters for listing pull requests with
* optional state filtering. Allows filtering by pull request state
* to show only PRs in specific lifecycle phases.
*
* @example
* ```typescript
* const input = {
* workspace: 'gohcl',
* repo_slug: 'bitbucket-mcp',
* state: 'OPEN'
* };
* const validatedInput = ListPullRequestsInputSchema.parse(input);
* ```
*/
export const ListPullRequestsInputSchema = RepositoryBaseSchema.extend({
/**
* Optional state filter for pull requests.
* When specified, only returns pull requests in the given state.
* If omitted, returns pull requests in all states.
*/
state: z.enum(['OPEN', 'MERGED', 'DECLINED', 'SUPERSEDED'], {
errorMap: () => ({ message: 'Invalid pull request state filter' })
}).optional(),
});
/**
* Input validation schema for pull request comment operations.
*
* This schema validates parameters for adding comments to pull requests,
* including the target pull request ID and comment content with length
* restrictions to ensure reasonable comment sizes.
*
* @example
* ```typescript
* const input = {
* workspace: 'gohcl',
* repo_slug: 'bitbucket-mcp',
* pull_request_id: 123,
* content: 'This implementation looks great! LGTM.'
* };
* const validatedInput = CommentInputSchema.parse(input);
* ```
*/
export const CommentInputSchema = RepositoryBaseSchema.extend({
/**
* Numeric identifier for the target pull request.
* Must reference an existing pull request in the repository.
*/
pull_request_id: z.number().int().positive('Pull request ID must be a positive integer'),
/**
* Comment content to be added to the pull request.
* Must be non-empty and within reasonable length limits.
* Can contain markdown formatting, mentions, and links.
*/
content: z.string().min(1, 'Comment content is required')
.max(10000, 'Comment content too long'),
});
//# sourceMappingURL=schemas.js.map