Atlassian Confluence MCP Server

Instructions

Implementation Reference

• src/tools/atlassian.api.tool.ts:237-245 (registration)

  Registers the 'conf_get' MCP tool with the server, providing title, description reference, input schema (GetApiToolArgs), and the 'get' handler function.

  server.registerTool(
  	'conf_get',
  	{
  		title: 'Confluence GET Request',
  		description: CONF_GET_DESCRIPTION,
  		inputSchema: GetApiToolArgs,
  	},
  	get,
  );

• src/tools/atlassian.api.types.ts:19-77 (schema)

  Zod schema definition for 'conf_get' tool input arguments: path (required), optional queryParams, jq filter, outputFormat. Base schema used by GetApiToolArgs.

  const BaseApiToolArgs = {
  	/**
  	 * The API endpoint path (without base URL)
  	 * Examples:
  	 * - "/wiki/api/v2/spaces" - list spaces
  	 * - "/wiki/api/v2/spaces/{id}" - get space
  	 * - "/wiki/api/v2/pages" - list/create pages
  	 * - "/wiki/api/v2/pages/{id}" - get page
  	 * - "/wiki/api/v2/pages/{id}/body" - get page body
  	 */
  	path: z
  		.string()
  		.min(1, 'Path is required')
  		.describe(
  			'The Confluence API endpoint path (without base URL). Must start with "/". Examples: "/wiki/api/v2/spaces", "/wiki/api/v2/pages", "/wiki/api/v2/pages/{id}"',
  		),
  
  	/**
  	 * Optional query parameters as key-value pairs
  	 */
  	queryParams: z
  		.record(z.string(), z.string())
  		.optional()
  		.describe(
  			'Optional query parameters as key-value pairs. Examples: {"limit": "25", "cursor": "...", "space-id": "123", "body-format": "storage"}',
  		),
  
  	/**
  	 * Optional JMESPath expression to filter/transform the response
  	 * IMPORTANT: Always use this to reduce response size and token costs
  	 */
  	jq: z
  		.string()
  		.optional()
  		.describe(
  			'JMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "results[*].{id: id, title: title}" (extract specific fields), "results[0]" (first result), "results[*].id" (IDs only). See https://jmespath.org',
  		),
  
  	/**
  	 * Output format for the response
  	 * Defaults to TOON (token-efficient), can be set to JSON if needed
  	 */
  	outputFormat: OutputFormat,
  };
  
  /**
   * Body field for requests that include a request body (POST, PUT, PATCH)
   */
  const bodyField = z
  	.record(z.string(), z.unknown())
  	.describe(
  		'Request body as a JSON object. Structure depends on the endpoint. Example for page: {"spaceId": "123", "title": "Page Title", "body": {"representation": "storage", "value": "<p>Content</p>"}}',
  	);
  
  /**
   * Schema for conf_get tool arguments (GET requests - no body)
   */
  export const GetApiToolArgs = z.object(BaseApiToolArgs);
  export type GetApiToolArgsType = z.infer<typeof GetApiToolArgs>;

• src/tools/atlassian.api.tool.ts:33-69 (handler)

  Factory function that creates the MCP-compatible handler for 'conf_get' (GET requests). Takes args, calls controller's handleGet, truncates output for AI, returns MCP content format or error.

  function createReadHandler(
  	methodName: string,
  	handler: (
  		options: GetApiToolArgsType,
  	) => 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:`, args);
  
  		try {
  			const result = await handler(args as GetApiToolArgsType);
  
  			methodLogger.debug(
  				'Successfully retrieved 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:106-110 (handler)

  Controller handler specifically for GET requests (used by conf_get tool). Delegates to shared handleRequest which performs API call, JQ filtering, and output formatting.

  export async function handleGet(
  	options: GetApiToolArgsType,
  ): Promise<ControllerResponse> {
  	return handleRequest('GET', options);
  }

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

  Core helper function that executes the HTTP request via Atlassian API service, applies JMESPath (jq) filtering, converts to TOON/JSON format, and handles errors. Used by all conf_* tools including conf_get.

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