Confluence POST Request

Instructions

Implementation Reference

• src/controllers/atlassian.api.controller.ts:118-122 (handler)

  The handlePost function is the actual handler that executes the conf_post tool logic. It calls the shared handleRequest function with 'POST' method, which calls the Atlassian API service and applies JQ filtering and output formatting.

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

• src/tools/atlassian.api.tool.ts:247-256 (registration)

  The conf_post tool is registered with the MCP server using server.registerTool() with name 'conf_post', description CONF_POST_DESCRIPTION, inputSchema RequestWithBodyArgs, and the 'post' handler (which wraps handlePost).

  // Register the POST tool using modern registerTool API
  server.registerTool(
  	'conf_post',
  	{
  		title: 'Confluence POST Request',
  		description: CONF_POST_DESCRIPTION,
  		inputSchema: RequestWithBodyArgs,
  	},
  	post,
  );

• src/tools/atlassian.api.types.ts:82-85 (schema)

  The input schema for conf_post is RequestWithBodyArgs, a Zod schema extending BaseApiToolArgs with a 'body' field (a JSON record) for POST request bodies.

  export const RequestWithBodyArgs = z.object({
  	...BaseApiToolArgs,
  	body: bodyField,
  });

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

  The createWriteHandler function wraps the controller's handlePost into an MCP tool handler. It handles formatting the response and error formatting for the tool output.

  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);
  		}
  	};
  }

• src/controllers/atlassian.api.controller.ts:55-98 (helper)

  The shared handleRequest function handles all HTTP methods (GET, POST, PUT, PATCH, DELETE). For POST, it calls atlassianApiService.request with method 'POST', then applies JQ filtering and converts output to TOON or JSON format.

  async function handleRequest(
  	method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
  	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) }),
  		});
  
  		// Call the service layer (returns TransportResponse with data and rawResponsePath)
  		const response = await atlassianApiService.request<unknown>(
  			options.path,
  			{
  				method,
  				queryParams: options.queryParams,
  				body: options.body,
  			},
  		);
  
  		methodLogger.debug('Successfully received response from service');
  
  		// 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 },
  		});
  	}
  }