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