Confluence PUT Request
conf_putUpdate Confluence pages and blog posts by replacing entire resources. Use this tool to modify content, titles, and metadata while managing version numbers.
Instructions
Replace Confluence resources (full update). Returns TOON format by default.
IMPORTANT - Cost Optimization:
Use
jqparam to extract only needed fields from responseExample:
jq: "{id: id, version: version.number}"
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Update page:
/wiki/api/v2/pages/{id}body:{"id": "123", "status": "current", "title": "Updated Title", "spaceId": "456", "body": {"representation": "storage", "value": "<p>Content</p>"}, "version": {"number": 2}}Note: version.number must be incrementedUpdate blog post:
/wiki/api/v2/blogposts/{id}
Note: PUT replaces entire resource. Version number must be incremented.
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:259-267 (registration)Registers the 'conf_put' tool with the MCP server, specifying its title, description, Zod input schema (RequestWithBodyArgs), and the 'put' handler function.
server.registerTool( 'conf_put', { title: 'Confluence PUT Request', description: CONF_PUT_DESCRIPTION, inputSchema: RequestWithBodyArgs, }, put, ); - The handlePut controller function that executes the PUT logic for the conf_put tool by invoking the shared handleRequest with method 'PUT'.
/** * Generic PUT request to Confluence API * * @param options - Options containing path, body, queryParams, and optional jq filter * @returns Promise with raw JSON response (optionally filtered) */ export async function handlePut( options: RequestWithBodyArgsType, ): Promise<ControllerResponse> { return handleRequest('PUT', options); } - Zod schema definition (RequestWithBodyArgs) used as inputSchema for the conf_put tool, including path, queryParams, jq, outputFormat, and body fields.
export const RequestWithBodyArgs = z.object({ ...BaseApiToolArgs, body: bodyField, }); export type RequestWithBodyArgsType = z.infer<typeof RequestWithBodyArgs>; - src/tools/atlassian.api.tool.ts:78-117 (handler)createWriteHandler function that constructs the MCP tool executor for conf_put ('PUT'), handling logging, controller invocation (handlePut), response truncation, MCP content formatting, and error handling.
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); } }; } - Description string for the conf_put tool, providing usage instructions, examples, and optimization tips, referenced in tool registration.
const CONF_PUT_DESCRIPTION = `Replace Confluence resources (full update). Returns TOON format by default. **IMPORTANT - Cost Optimization:** - Use \`jq\` param to extract only needed fields from response - Example: \`jq: "{id: id, version: version.number}"\` **Output format:** TOON (default) or JSON (\`outputFormat: "json"\`) **Common operations:** 1. **Update page:** \`/wiki/api/v2/pages/{id}\` body: \`{"id": "123", "status": "current", "title": "Updated Title", "spaceId": "456", "body": {"representation": "storage", "value": "<p>Content</p>"}, "version": {"number": 2}}\` Note: version.number must be incremented 2. **Update blog post:** \`/wiki/api/v2/blogposts/{id}\` Note: PUT replaces entire resource. Version number must be incremented. API reference: https://developer.atlassian.com/cloud/confluence/rest/v2/`;