Confluence MCP Server

Instructions

Implementation Reference

• src/handlers/search-label-handlers.ts:6-43 (handler)

  Main handler function implementing the search_confluence_pages tool. Validates input, calls ConfluenceClient.searchConfluenceContent, simplifies results, and returns JSON-formatted response.
  export async function handleSearchConfluencePages( client: ConfluenceClient, args: { query: string; limit?: number; start?: number } ): Promise<{ content: Array<{ type: "text"; text: string }>; }> { try { if (!args.query) { throw new McpError(ErrorCode.InvalidParams, "query is required"); } const results = await client.searchConfluenceContent(args.query, args.limit, args.start); const simplified = { results: results.results.map(result => ({ id: result.content.id, title: result.content.title, type: result.content.type, url: result.url, excerpt: result.excerpt || null })), next: results._links.next ? true : false }; return { content: [ { type: "text", text: JSON.stringify(simplified), }, ], }; } catch (error) { console.error("Error searching pages:", error instanceof Error ? error.message : String(error)); throw new McpError( ErrorCode.InternalError, `Failed to search pages: ${error instanceof Error ? error.message : String(error)}` ); } }
• src/index.ts:250-258 (registration)

  Registration of the search_confluence_pages tool in the main switch statement handling tool calls.
  case "search_confluence_pages": { const { query, limit, start } = (args || {}) as { query: string; limit?: number; start?: number }; if (!query) throw new McpError(ErrorCode.InvalidParams, "query is required"); return await handleSearchConfluencePages(this.confluenceClient, { query, limit, start }); }
• src/schemas/tool-schemas.ts:139-159 (schema)

  Schema definition for search_confluence_pages tool including detailed description and input schema with query (required), limit, and start parameters.
  search_confluence_pages: { description: "Search across Confluence pages using simple text or CQL (Confluence Query Language).\n\nQuery Types:\n\n1. Simple Text Search:\n - Just provide the search term directly (e.g., \"documentation\")\n - The system automatically wraps it in proper CQL syntax\n\n2. Advanced CQL Search:\n - Must include \"type =\" to signal raw CQL usage\n - Examples:\n * type = \"page\" AND text ~ \"project\"\n * type = \"page\" AND space.key = \"TEAM\"\n * type = \"page\" AND created >= \"2024-01-01\"\n\nSearch Capabilities:\n- Full text search across all pages\n- Space-specific searches\n- Content type filtering\n- Metadata-based filtering\n\nCQL Operators (for advanced queries):\n- ~ : contains\n- = : equals\n- != : not equals\n- AND, OR : combine conditions\n- () : group conditions\n- >= <= : date comparisons\n- IN : multiple values\n\nCommon Search Patterns:\n- Finding pages in specific space: type = \"page\" AND space.key = \"SPACENAME\" AND text ~ \"searchterm\"\n- Finding recent pages: type = \"page\" AND created >= \"2024-01-01\" AND text ~ \"searchterm\"\n- Finding pages by title: type = \"page\" AND title ~ \"exactname\"\n- Finding pages by label: type = \"page\" AND label = \"labelname\"\n\nResponse includes:\n- Page ID, title, and type\n- Space information\n- URL to the page\n- Last modified date\n- Content excerpt with search term highlighting\n\nPagination:\n- Use 'limit' to control results per page (default: 25)\n- Use 'start' for pagination offset\n\nWorkflow Tips:\n1. Start with list_confluence_spaces to get space keys\n2. Use space-specific searches for better results\n3. Use the returned pageId with get_confluence_page for full content\n4. Look for highlighted excerpts in results to identify most relevant matches\n\nBest Practices:\n1. Start with simple text searches when possible\n2. Use advanced CQL (with 'type =') for complex queries\n3. Use space-specific searches for better performance\n4. Use get_confluence_page to fetch full content of found pages", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query - either simple text (e.g., 'documentation') or CQL query (must include 'type =' for CQL mode, e.g., 'type = \"page\" AND text ~ \"project\"')", }, limit: { type: "number", description: "Maximum number of results to return (default: 25)", }, start: { type: "number", description: "Starting index for pagination (default: 0)", }, }, required: ["query"], }, },
• src/index.ts:29-29 (registration)

  Import of the handleSearchConfluencePages handler function used in tool registration.
  handleSearchConfluencePages,