Confluence MCP Server

Instructions

Implementation Reference

• src/handlers/search-label-handlers.ts:81-164 (handler)

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

• src/client/confluence-client.ts:319-357 (helper)

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