add_confluence_label
Add organizational labels to Confluence pages to categorize content and improve searchability through the Confluence MCP Server.
Instructions
Add a label to a page. Labels help organize content and make it easier to find related pages through search_confluence_pages.
Label Format:
Must contain only letters, numbers, hyphens, and underscores
No spaces or special characters allowed
Error Handling:
Returns 400 for invalid label format
Returns 403 for insufficient permissions
Returns 404 if page not found
Returns 409 if label already exists on the page
Response includes:
Success status
Label details (id, name, prefix, creation date)
Operation message
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageId | Yes | ID of the page to add the label to | |
| label | Yes | Label to add (letters, numbers, hyphens, and underscores only) |
Implementation Reference
- Main handler function for the 'add_confluence_label' tool. Validates inputs, checks page existence, calls the Confluence client to add the label, handles various errors, and returns a formatted JSON response.export async function handleAddConfluenceLabel( client: ConfluenceClient, args: { pageId: string; label: string } ): Promise<{ content: Array<{ type: "text"; text: string }>; }> { try { if (!args.pageId || !args.label) { throw new McpError( ErrorCode.InvalidParams, "pageId and label are required" ); } // Validate label format if (!/^[a-zA-Z0-9-_]+$/.test(args.label)) { throw new McpError( ErrorCode.InvalidParams, "Label must contain only letters, numbers, hyphens, and underscores" ); } // First check if the page exists and is accessible try { await client.getConfluencePage(args.pageId); } catch (error: unknown) { if (error instanceof ConfluenceError) { switch (error.code) { case 'PAGE_NOT_FOUND': throw new McpError(ErrorCode.InvalidParams, "Page not found"); case 'INSUFFICIENT_PERMISSIONS': throw new McpError(ErrorCode.InvalidRequest, "Insufficient permissions to access page"); default: throw new McpError(ErrorCode.InternalError, error.message); } } throw error; } const label = await client.addConfluenceLabel(args.pageId, args.label); const simplified = { success: true, label: { id: label.id, name: label.name, prefix: label.prefix || null, createdDate: label.createdDate || null }, message: `Successfully added label '${args.label}' to page ${args.pageId}` }; return { content: [ { type: "text", text: JSON.stringify(simplified), }, ], }; } catch (error: unknown) { console.error("Error adding label:", error instanceof Error ? error.message : String(error)); if (error instanceof McpError) { throw error; } // Handle specific HTTP errors from the Confluence API if (error instanceof ConfluenceError) { switch (error.code) { case 'LABEL_EXISTS': throw new McpError(ErrorCode.InvalidRequest, `Label '${args.label}' already exists on this page`); case 'INVALID_LABEL': throw new McpError(ErrorCode.InvalidParams, "Invalid label format"); case 'PERMISSION_DENIED': throw new McpError(ErrorCode.InvalidRequest, "You don't have permission to add labels to this page"); default: throw new McpError(ErrorCode.InternalError, `Failed to add label: ${error.message}`); } } throw new McpError( ErrorCode.InternalError, `Failed to add label: ${error instanceof Error ? error.message : String(error)}` ); }
- src/schemas/tool-schemas.ts:175-191 (schema)Schema definition for the 'add_confluence_label' tool, including description, input properties (pageId, label), and required fields.add_confluence_label: { description: "Add a label to a page. Labels help organize content and make it easier to find related pages through search_confluence_pages.\n\nLabel Format:\n- Must contain only letters, numbers, hyphens, and underscores\n- No spaces or special characters allowed\n\nError Handling:\n- Returns 400 for invalid label format\n- Returns 403 for insufficient permissions\n- Returns 404 if page not found\n- Returns 409 if label already exists on the page\n\nResponse includes:\n- Success status\n- Label details (id, name, prefix, creation date)\n- Operation message", inputSchema: { type: "object", properties: { pageId: { type: "string", description: "ID of the page to add the label to", }, label: { type: "string", description: "Label to add (letters, numbers, hyphens, and underscores only)", }, }, required: ["pageId", "label"], }, },
- src/index.ts:266-270 (registration)Tool registration in the main switch statement within the CallToolRequestSchema handler. Dispatches to the handleAddConfluenceLabel function.case "add_confluence_label": { const { pageId, label } = (args || {}) as { pageId: string; label: string }; if (!pageId || !label) throw new McpError(ErrorCode.InvalidParams, "pageId and label are required"); return await handleAddConfluenceLabel(this.confluenceClient, { pageId, label }); }
- Helper method in ConfluenceClient that performs the actual API POST request to add a label to a page and handles API-specific errors.async addConfluenceLabel(pageId: string, label: string): Promise<Label> { try { const response = await this.v2Client.post(`/pages/${pageId}/labels`, { name: label }); return response.data; } catch (error) { if (axios.isAxiosError(error)) { switch (error.response?.status) { case 400: throw new ConfluenceError( 'Invalid label format or label already exists', 'INVALID_LABEL' ); case 403: throw new ConfluenceError( 'Insufficient permissions to add labels', 'PERMISSION_DENIED' ); case 404: throw new ConfluenceError( 'Page not found', 'PAGE_NOT_FOUND' ); case 409: throw new ConfluenceError( 'Label already exists on this page', 'LABEL_EXISTS' ); default: console.error('Error adding label:', error.response?.data); throw new ConfluenceError( `Failed to add label: ${error.message}`, 'UNKNOWN' ); } } throw error; }