Bitbucket POST Request

Instructions

Implementation Reference

• src/controllers/atlassian.api.controller.ts:167-171 (handler)

  Core handler for bb_post - delegates to handleRequest with 'POST' method, executing the actual Bitbucket API POST request

  export async function handlePost(
  	options: RequestWithBodyArgsType,
  ): Promise<ControllerResponse> {
  	return handleRequest('POST', options);
  }

• src/controllers/atlassian.api.controller.ts:85-147 (handler)

  Shared request handler that normalizes the path, fetches Atlassian API, applies JQ filtering, and formats output (TOON/JSON)

  async function handleRequest(
  	method: HttpMethod,
  	options: RequestWithBodyOptions,
  ): Promise<ControllerResponse> {
  	const methodLogger = logger.forMethod(`handle${method}`);
  
  	try {
  		methodLogger.debug(`Making ${method} request`, {
  			path: options.path,
  			...(options.body && { bodyKeys: Object.keys(options.body) }),
  		});
  
  		// Get credentials
  		const credentials = getAtlassianCredentials();
  		if (!credentials) {
  			throw createAuthMissingError();
  		}
  
  		// Normalize path and append query params
  		let path = normalizePath(options.path);
  		path = appendQueryParams(path, options.queryParams);
  
  		methodLogger.debug(`${method}ing: ${path}`);
  
  		const fetchOptions: {
  			method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  			body?: Record<string, unknown>;
  		} = {
  			method,
  		};
  
  		// Add body for methods that support it
  		if (options.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
  			fetchOptions.body = options.body;
  		}
  
  		const response = await fetchAtlassian<unknown>(
  			credentials,
  			path,
  			fetchOptions,
  		);
  		methodLogger.debug('Successfully received response');
  
  		// Apply JQ filter if provided, otherwise return raw data
  		const result = applyJqFilter(response.data, options.jq);
  
  		// Convert to output format (TOON by default, JSON if requested)
  		const useToon = options.outputFormat !== 'json';
  		const content = await toOutputString(result, useToon);
  
  		return {
  			content,
  			rawResponsePath: response.rawResponsePath,
  		};
  	} catch (error) {
  		throw handleControllerError(error, {
  			entityType: 'API',
  			operation: `${method} request`,
  			source: `controllers/atlassian.api.controller.ts@handle${method}`,
  			additionalInfo: { path: options.path },
  		});
  	}
  }

• src/tools/atlassian.api.tool.ts:274-288 (registration)

  Registration of the 'bb_post' tool on the MCP server with title, description, input schema, annotations, and handler

  server.registerTool(
  	'bb_post',
  	{
  		title: 'Bitbucket POST Request',
  		description: BB_POST_DESCRIPTION,
  		inputSchema: RequestWithBodyArgs,
  		annotations: {
  			readOnlyHint: false,
  			destructiveHint: false,
  			idempotentHint: false,
  			openWorldHint: true,
  		},
  	},
  	post,
  );

• src/tools/atlassian.api.types.ts:84-94 (schema)

  Zod schema defining bb_post input arguments: path (required string), queryParams, jq filter, outputFormat, and body (record of unknown)

  export const RequestWithBodyArgs = z.object({
  	...BaseApiToolArgs,
  	body: bodyField,
  });
  export type RequestWithBodyArgsType = z.infer<typeof RequestWithBodyArgs>;
  
  /**
   * Schema for bb_post tool arguments (POST requests)
   */
  export const PostApiToolArgs = RequestWithBodyArgs;
  export type PostApiToolArgsType = RequestWithBodyArgsType;

• src/tools/atlassian.api.tool.ts:78-117 (helper)

  Factory function that creates the MCP tool handler wrapper for POST/PUT/PATCH, parsing args, calling the controller, truncating response, and formatting errors

  function createWriteHandler(
  	methodName: string,
  	handler: (
  		options: RequestWithBodyArgsType,
  	) => Promise<{ content: string; rawResponsePath?: string | null }>,
  ) {
  	return async (args: Record<string, unknown>) => {
  		const methodLogger = Logger.forContext(
  			'tools/atlassian.api.tool.ts',
  			methodName.toLowerCase(),
  		);
  		methodLogger.debug(`Making ${methodName} request with args:`, {
  			path: args.path,
  			bodyKeys: args.body ? Object.keys(args.body as object) : [],
  		});
  
  		try {
  			const result = await handler(args as RequestWithBodyArgsType);
  
  			methodLogger.debug(
  				'Successfully received response from controller',
  			);
  
  			return {
  				content: [
  					{
  						type: 'text' as const,
  						text: truncateForAI(
  							result.content,
  							result.rawResponsePath,
  						),
  					},
  				],
  			};
  		} catch (error) {
  			methodLogger.error(`Failed to make ${methodName} request`, error);
  			return formatErrorForMcpTool(error);
  		}
  	};
  }