search_confluence_pages

Instructions

Implementation Reference

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

  Handler function that executes the search_confluence_pages tool logic. Calls ConfluenceClient.searchConfluenceContent, simplifies results to id/title/type/url/excerpt, and returns JSON.

  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/schemas/tool-schemas.ts:139-159 (schema)

  Schema definition for search_confluence_pages tool, including detailed description of CQL search capabilities, input parameters (query, limit, start), and required fields.

  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:249-258 (registration)

  Registration of search_confluence_pages in the CallToolRequestSchema handler. Extracts query/limit/start from args, validates query is present, and delegates to handleSearchConfluencePages.

  // Search operation
  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/client/confluence-client.ts:266-310 (helper)

  ConfluenceClient method that performs the actual API call to Confluence's v1 /search endpoint with CQL. If query contains 'type =', it's used as raw CQL; otherwise it's wrapped in text search syntax. Returns simplified SearchResult with content, url, lastModified, and excerpt.

  async searchConfluenceContent(query: string, limit = 25, start = 0): Promise<SearchResult> {
    try {
      console.error('Searching Confluence with CQL:', query);
      
      // Use the v1 search endpoint with CQL
      const response = await this.v1Client.get('/search', {
        params: {
          cql: query.includes('type =') ? query : `text ~ "${query}"`,
          limit,
          start,
          expand: 'content.space,content.version,content.body.view.value'
        }
      });
  
      console.error(`Found ${response.data.results?.length || 0} results`);
  
      return {
        results: (response.data.results || []).map((result: any) => ({
          content: {
            id: result.content.id,
            type: result.content.type,
            status: result.content.status,
            title: result.content.title,
            spaceId: result.content.space?.id,
            _links: result.content._links
          },
          url: `https://${this.domain}/wiki${result.content._links?.webui || ''}`,
          lastModified: result.content.version?.when,
          excerpt: result.excerpt || ''
        })),
        _links: {
          next: response.data._links?.next,
          base: this.baseURL + '/rest/api'
        }
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        console.error('Error searching content:', error.message, error.response?.data);
        throw new ConfluenceError(
          `Failed to search content: ${error.message}`,
          'SEARCH_FAILED'
        );
      }
      throw error;
    }