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,