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