Confluence MCP Server

Instructions

Implementation Reference

• src/handlers/page-handlers.ts:61-118 (handler)

  The main handler function that executes the get_confluence_page tool logic: fetches the page using ConfluenceClient, converts content to markdown, simplifies the response, and returns it as MCP content.

  export async function handleGetConfluencePage(
    client: ConfluenceClient,
    args: { pageId: string }
  ): Promise<{
    content: Array<{ type: "text"; text: string }>;
  }> {
    try {
      if (!args.pageId) {
        throw new McpError(ErrorCode.InvalidParams, "pageId is required");
      }
  
      try {
        const page = await client.getConfluencePage(args.pageId);
        
        if (!page.body?.storage?.value) {
          throw new McpError(
            ErrorCode.InternalError,
            "Page content is empty"
          );
        }
  
        const markdownContent = convertStorageToMarkdown(page.body.storage.value);
        const simplified = convertToSimplifiedPage(page, markdownContent);
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(simplified),
            },
          ],
        };
      } catch (error) {
        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");
            case 'EMPTY_CONTENT':
              throw new McpError(ErrorCode.InternalError, "Page content is empty");
            default:
              throw new McpError(ErrorCode.InternalError, error.message);
          }
        }
        throw error;
      }
    } catch (error) {
      console.error("Error getting page:", error instanceof Error ? error.message : String(error));
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to get page: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/index.ts:214-218 (registration)

  Tool registration and dispatch in the main switch statement: handles the 'get_confluence_page' case by calling the handler function.

  case "get_confluence_page": {
    const { pageId } = (args || {}) as { pageId: string };
    if (!pageId) throw new McpError(ErrorCode.InvalidParams, "pageId is required");
    return await handleGetConfluencePage(this.confluenceClient, { pageId });
  }

• src/schemas/tool-schemas.ts:55-67 (schema)

  Input schema and description for the get_confluence_page tool.

  get_confluence_page: {
    description: "Get a specific Confluence page by its ID. Returns the complete page content in markdown format, along with metadata like version history and space information. The page ID can be found in search results, page listings, or other API responses. TIP: Save page IDs from searches for direct access to frequently needed pages.",
    inputSchema: {
      type: "object",
      properties: {
        pageId: {
          type: "string",
          description: "ID of the page to retrieve",
        },
      },
      required: ["pageId"],
    },
  },

• src/client/confluence-client.ts:193-226 (helper)

  Core API client method that fetches Confluence page metadata and content, used by the handler.

  async getConfluencePage(pageId: string): Promise<Page> {
    try {
      // Get page metadata
      const pageResponse = await this.v2Client.get(`/pages/${pageId}`);
      const page = pageResponse.data;
  
      try {
        // Get page content
        const content = await this.getPageContent(pageId);
        return {
          ...page,
          body: {
            storage: {
              value: content,
              representation: 'storage'
            }
          }
        };
      } catch (contentError) {
        if (contentError instanceof ConfluenceError && 
            contentError.code === 'EMPTY_CONTENT') {
          return page; // Return metadata only for empty pages
        }
        throw contentError;
      }
    } catch (error) {
      if (axios.isAxiosError(error)) {
        console.error('Error fetching page:', error.message);
        throw error;
      }
      console.error('Error fetching page:', error instanceof Error ? error.message : 'Unknown error');
      throw new Error('Failed to fetch page content');
    }
  }

• src/handlers/page-handlers.ts:8-20 (helper)

  Helper function to convert full Page object and markdown content to simplified response format.

  function convertToSimplifiedPage(page: Page, markdownContent: string): SimplifiedPage {
    return {
      title: page.title,
      content: markdownContent,
      metadata: {
        id: page.id,
        spaceId: page.spaceId,
        version: page.version.number,
        lastModified: page.version.createdAt,
        url: page._links.webui
      }
    };
  }