Confluence MCP Server

Instructions

Implementation Reference

• src/handlers/page-handlers.ts:120-186 (handler)

  The main handler function that implements the find_confluence_page tool logic: searches for pages by title, handles single/multiple/no matches, fetches and converts content to markdown, returns structured response.

  export async function handleFindConfluencePage(
    client: ConfluenceClient,
    args: { title: string; spaceId?: string }
  ): Promise<{
    content: Array<{ type: "text"; text: string }>;
  }> {
    try {
      if (!args.title) {
        throw new McpError(ErrorCode.InvalidParams, "title is required");
      }
  
      const pages = await client.searchPageByName(args.title, args.spaceId);
      
      if (pages.length === 0) {
        throw new McpError(
          ErrorCode.InvalidParams,
          `No pages found with title "${args.title}"`
        );
      }
  
      if (pages.length > 1) {
        // If multiple pages found, return a list of matches
        const matches = pages.map(page => ({
          id: page.id,
          title: page.title,
          spaceId: page.spaceId,
          url: page._links.webui
        }));
        
        throw new McpError(
          ErrorCode.InvalidParams,
          `Multiple pages found with title "${args.title}". Please use get_confluence_page with one of these IDs: ${JSON.stringify(matches)}`
        );
      }
  
      // Get the full page content for the single match
      const page = await client.getConfluencePage(pages[0].id);
      
      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) {
      console.error("Error getting page by name:", 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/schemas/tool-schemas.ts:69-85 (schema)

  Zod/input schema definition and description for the find_confluence_page tool, defining parameters title (required) and spaceId (optional).

  find_confluence_page: {
    description: "Find and retrieve a Confluence page by its title. Returns the page content in markdown format, along with metadata. Optionally specify a spaceId to narrow the search. If multiple pages match the title, returns a list of matches to choose from. TIP: Use this when you know the exact page title, but prefer search_confluence_pages for partial matches.",
    inputSchema: {
      type: "object",
      properties: {
        title: {
          type: "string",
          description: "Title of the page to find",
        },
        spaceId: {
          type: "string",
          description: "Optional space ID to limit the search scope",
        },
      },
      required: ["title"],
    },
  },

• src/index.ts:219-223 (registration)

  Tool registration in the MCP server request handler switch statement, mapping 'find_confluence_page' calls to the handleFindConfluencePage function.

  case "find_confluence_page": {
    const { title, spaceId } = (args || {}) as { title: string; spaceId?: string };
    if (!title) throw new McpError(ErrorCode.InvalidParams, "title is required");
    return await handleFindConfluencePage(this.confluenceClient, { title, spaceId });
  }

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

  Helper function to convert full Page object and markdown content into the simplified response format used by the handler.

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