Confluence PATCH Request
conf_patchUpdate specific Confluence resources like spaces, pages, or comments by sending partial modifications to the Confluence API, with options to optimize response data and reduce token usage.
Instructions
Partially update Confluence resources. Returns TOON format by default.
IMPORTANT - Cost Optimization: Use jq param to filter response fields.
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Update space:
/wiki/api/v2/spaces/{id}body:{"name": "New Name", "description": {"plain": {"value": "Desc", "representation": "plain"}}}Update comment:
/wiki/api/v2/footer-comments/{id}
Note: Confluence v2 API primarily uses PUT for updates.
API reference: https://developer.atlassian.com/cloud/confluence/rest/v2/
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 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}" | |
| queryParams | No | Optional query parameters as key-value pairs. Examples: {"limit": "25", "cursor": "...", "space-id": "123", "body-format": "storage"} | |
| jq | No | 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 | |
| outputFormat | No | Output format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax. | |
| body | Yes | 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>"}} |
Implementation Reference
- src/tools/atlassian.api.tool.ts:270-278 (registration)Registers the 'conf_patch' tool with the MCP server, providing title, description, input schema (RequestWithBodyArgs), and the 'patch' handler function created by createWriteHandler.
server.registerTool( 'conf_patch', { title: 'Confluence PATCH Request', description: CONF_PATCH_DESCRIPTION, inputSchema: RequestWithBodyArgs, }, patch, ); - src/tools/atlassian.api.tool.ts:78-117 (handler)Factory creating the MCP-compatible handler for conf_patch (PATCH requests). Parses args, logs, calls controller handlePatch, truncates response, formats as MCP content array, handles 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); } }; } - Controller handler specifically for conf_patch tool calls, delegates to shared handleRequest with 'PATCH' method.
export async function handlePatch( options: RequestWithBodyArgsType, ): Promise<ControllerResponse> { return handleRequest('PATCH', options); } - Core execution logic for conf_patch: calls Atlassian API service with PATCH method, applies jq filter if provided, converts to TOON/JSON output.
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 }, }); } } - Zod schema used as inputSchema for conf_patch tool, defining path, queryParams, jq, outputFormat, and body fields.
export const RequestWithBodyArgs = z.object({ ...BaseApiToolArgs, body: bodyField, }); export type RequestWithBodyArgsType = z.infer<typeof RequestWithBodyArgs>;