@gohcltech/bitbucket-mcp
Version:
Bitbucket integration for Claude via Model Context Protocol
270 lines • 9.85 kB
JavaScript
/**
* @fileoverview Zod validation schemas for Bitbucket issue operations.
*
* This module provides comprehensive validation schemas for issue tracking
* 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 issue and comment API responses
* - Project management entity validation (components, milestones, versions)
* - User and content validation across issue contexts
* - Input parameter validation for issue management tools
* - 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 issue state values.
* Ensures only valid lifecycle states are used for issues.
*/
export const IssueStateSchema = z.enum(['new', 'open', 'resolved', 'on hold', 'invalid', 'duplicate', 'wontfix', 'closed'], {
errorMap: () => ({ message: 'Invalid issue state' })
});
/**
* Zod schema for validating issue kind/category values.
* Ensures only valid issue types are used for classification.
*/
export const IssueKindSchema = z.enum(['bug', 'enhancement', 'proposal', 'task'], {
errorMap: () => ({ message: 'Invalid issue kind' })
});
/**
* Zod schema for validating issue priority values.
* Ensures only valid priority levels are used for issue prioritization.
*/
export const IssuePrioritySchema = z.enum(['trivial', 'minor', 'major', 'critical', 'blocker'], {
errorMap: () => ({ message: 'Invalid issue priority' })
});
/**
* Zod schema for validating formatted content entities.
* Used for issue descriptions, comments, and other rich text content.
*/
export const ContentSchema = z.object({
/**
* Raw content as entered by the user.
* Must be non-empty and within reasonable length limits.
*/
raw: z.string().min(1, 'Content cannot be empty')
.max(50000, 'Content too long'),
/**
* Markup language used for the content.
* Defaults to markdown for Bitbucket content.
*/
markup: z.string().min(1, 'Markup type is required').default('markdown'),
/**
* Optional HTML-rendered version of the content.
* Contains processed output when markup is rendered.
*/
html: z.string().optional(),
});
/**
* Zod schema for validating user entities.
* Used for assignees, reporters, and comment authors in issue contexts.
*/
export const UserSchema = z.object({
/**
* Human-readable display name for the user.
* Must be a non-empty string.
*/
display_name: z.string().min(1, 'Display name is required'),
/**
* Unique UUID identifier for the user.
* Must be a non-empty string in UUID format.
*/
uuid: z.string().min(1, 'User UUID is required'),
/**
* Atlassian account ID for cross-product integration.
* Must follow the Atlassian account ID format.
*/
account_id: z.string().min(1, 'Account ID is required')
.regex(/^557058:[a-f0-9-]+$/, 'Invalid account ID format'),
/**
* User's chosen nickname or username.
* Must be a non-empty string.
*/
nickname: z.string().min(1, 'Nickname is required'),
/**
* Entity type discriminator.
* Must always be "user" for user entities.
*/
type: z.literal('user'),
/**
* Optional collection of related URLs for the user.
*/
links: z.object({
/** API endpoint for this user's details */
self: z.object({ href: z.string().url('Invalid user self link') }),
/** URL to the user's avatar image */
avatar: z.object({ href: z.string().url('Invalid avatar link') }),
/** URL to the user's profile page */
html: z.object({ href: z.string().url('Invalid user profile link') }),
}).optional(),
});
/**
* Input validation schema for issue-related MCP tool parameters.
*
* This schema validates the basic parameters required by issue tools,
* extending the repository base schema with issue-specific validation.
* Used by tools that operate on existing issues.
*
* @example
* ```typescript
* const input = {
* workspace: 'gohcl',
* repo_slug: 'bitbucket-mcp',
* issue_id: 42
* };
* const validatedInput = IssueInputSchema.parse(input);
* ```
*/
export const IssueInputSchema = RepositoryBaseSchema.extend({
/**
* Numeric identifier for the target issue.
* Must be a positive integer referencing an existing issue.
*/
issue_id: z.number().int().positive('Issue ID must be a positive integer'),
});
/**
* Input validation schema for the create_issue MCP tool.
*
* This schema validates parameters for creating new issues, including
* required fields like title and optional metadata for categorization,
* assignment, and project management.
*
* @example
* ```typescript
* const input = {
* workspace: 'gohcl',
* repo_slug: 'bitbucket-mcp',
* title: 'Add OAuth 2.0 authentication support',
* content: 'We need to implement OAuth 2.0 for secure authentication...',
* kind: 'enhancement',
* priority: 'major',
* component: 'Authentication',
* assignee: 'kurtwolf'
* };
* const validatedInput = CreateIssueInputSchema.parse(input);
* ```
*/
export const CreateIssueInputSchema = RepositoryBaseSchema.extend({
/**
* Issue title summarizing the problem or request.
* Must be descriptive and within character limits.
*/
title: z.string().min(1, 'Title is required').max(255, 'Title too long'),
/**
* Optional detailed description of the issue.
* Can contain markdown formatting and comprehensive details.
*/
content: z.string().max(50000, 'Content too long').optional(),
/**
* Issue category or type (defaults to 'task').
* Helps classify the nature of the work being tracked.
*/
kind: IssueKindSchema.default('task'),
/**
* Issue priority level (defaults to 'minor').
* Indicates urgency and importance for prioritization.
*/
priority: IssuePrioritySchema.default('minor'),
/**
* Optional component name for functional categorization.
* Should match an existing component in the repository.
*/
component: z.string().min(1, 'Component name cannot be empty').optional(),
/**
* Optional milestone name for project planning.
* Should match an existing milestone in the repository.
*/
milestone: z.string().min(1, 'Milestone name cannot be empty').optional(),
/**
* Optional version name for release tracking.
* Should match an existing version in the repository.
*/
version: z.string().min(1, 'Version name cannot be empty').optional(),
/**
* Optional username to assign the issue to.
* Should be a valid Bitbucket username with repository access.
*/
assignee: z.string().min(1, 'Assignee username cannot be empty').optional(),
});
/**
* Input validation schema for the list_issues MCP tool.
*
* This schema validates parameters for listing issues with comprehensive
* filtering and sorting options. Supports filtering by state, category,
* priority, assignment, and project management metadata.
*
* @example
* ```typescript
* const input = {
* workspace: 'gohcl',
* repo_slug: 'bitbucket-mcp',
* state: 'open',
* kind: 'bug',
* priority: 'major',
* assignee: 'kurtwolf',
* sort: 'priority',
* limit: 25
* };
* const validatedInput = ListIssuesInputSchema.parse(input);
* ```
*/
export const ListIssuesInputSchema = RepositoryBaseSchema.extend({
/**
* Optional state filter for issues.
* When specified, only returns issues in the given state.
*/
state: IssueStateSchema.optional(),
/**
* Optional kind/category filter for issues.
* When specified, only returns issues of the given type.
*/
kind: IssueKindSchema.optional(),
/**
* Optional priority filter for issues.
* When specified, only returns issues with the given priority.
*/
priority: IssuePrioritySchema.optional(),
/**
* Optional component filter for issues.
* When specified, only returns issues assigned to the given component.
*/
component: z.string().min(1, 'Component name cannot be empty').optional(),
/**
* Optional milestone filter for issues.
* When specified, only returns issues assigned to the given milestone.
*/
milestone: z.string().min(1, 'Milestone name cannot be empty').optional(),
/**
* Optional version filter for issues.
* When specified, only returns issues assigned to the given version.
*/
version: z.string().min(1, 'Version name cannot be empty').optional(),
/**
* Optional assignee filter for issues.
* When specified, only returns issues assigned to the given user.
*/
assignee: z.string().min(1, 'Assignee username cannot be empty').optional(),
/**
* Optional reporter filter for issues.
* When specified, only returns issues reported by the given user.
*/
reporter: z.string().min(1, 'Reporter username cannot be empty').optional(),
/**
* Optional sort order for the results.
* Determines how the returned issues are ordered.
*/
sort: z.enum(['created_on', 'updated_on', 'priority', 'votes'], {
errorMap: () => ({ message: 'Invalid sort option' })
}).optional(),
/**
* Maximum number of issues to return (default: 50).
* Must be between 1 and 100 to prevent excessive response sizes.
*/
limit: z.number().int().min(1, 'Limit must be at least 1')
.max(100, 'Limit cannot exceed 100').default(50),
});
//# sourceMappingURL=schemas.js.map