Confluence MCP Server

Instructions

Implementation Reference

• src/handlers/search-label-handlers.ts:167-240 (handler)

  MCP tool handler: validates parameters, verifies page access, removes the label via client, handles errors, and returns formatted JSON response.

  export async function handleRemoveConfluenceLabel(
    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"
        );
      }
  
      // 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;
      }
  
      await client.removeConfluenceLabel(args.pageId, args.label);
      const simplified = {
        success: true,
        message: `Successfully removed label '${args.label}' from page ${args.pageId}`,
        details: {
          pageId: args.pageId,
          label: args.label,
          operation: 'remove'
        }
      };
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(simplified),
          },
        ],
      };
    } catch (error: unknown) {
      console.error("Error removing 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 'PAGE_NOT_FOUND':
            throw new McpError(ErrorCode.InvalidParams, "Page not found");
          case 'PERMISSION_DENIED':
            throw new McpError(ErrorCode.InvalidRequest, "You don't have permission to remove labels from this page");
          default:
            throw new McpError(ErrorCode.InternalError, `Failed to remove label: ${error.message}`);
        }
      }
  
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to remove label: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/schemas/tool-schemas.ts:193-210 (schema)

  Tool schema defining input parameters (pageId, label) and description for the remove_confluence_label tool.

    remove_confluence_label: {
      description: "Remove a label from a page.\n\nError Handling:\n- Returns 403 for insufficient permissions\n- Returns 404 if page or label not found\n\nResponse includes:\n- Success status\n- Operation details (pageId, label, operation type)\n- Success message",
      inputSchema: {
        type: "object",
        properties: {
          pageId: {
            type: "string",
            description: "ID of the page",
          },
          label: {
            type: "string",
            description: "Label to remove",
          },
        },
        required: ["pageId", "label"],
      },
    },
  } as const;

• src/index.ts:271-275 (registration)

  Tool registration in the main switch dispatcher: extracts arguments, validates, and calls the handler function.

  case "remove_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 handleRemoveConfluenceLabel(this.confluenceClient, { pageId, label });
  }

• src/client/confluence-client.ts:360-386 (helper)

  Low-level client method that makes the DELETE API call to remove a label from a Confluence page and handles API errors.

  async removeConfluenceLabel(pageId: string, label: string): Promise<void> {
    try {
      await this.v2Client.delete(`/pages/${pageId}/labels/${label}`);
    } catch (error) {
      if (axios.isAxiosError(error)) {
        switch (error.response?.status) {
          case 403:
            throw new ConfluenceError(
              'Insufficient permissions to remove labels',
              'PERMISSION_DENIED'
            );
          case 404:
            throw new ConfluenceError(
              'Page or label not found',
              'PAGE_NOT_FOUND'
            );
          default:
            console.error('Error removing label:', error.response?.data);
            throw new ConfluenceError(
              `Failed to remove label: ${error.message}`,
              'UNKNOWN'
            );
        }
      }
      throw error;
    }
  }