cwiki_search_pages

Instructions

Implementation Reference

• src/incubator_cwiki_mcp/tools.py:49-84 (handler)

  The main handler function for the cwiki_search_pages tool. Decorated with @mcp.tool(), it accepts a query string, limit, start, and force_refresh parameters. It validates inputs, builds a CQL query searching the configured Confluence space for pages matching the text query, calls the Confluence REST API, and returns results including page summaries and text excerpts.

  @mcp.tool()
  def cwiki_search_pages(
      query: str,
      limit: int = 10,
      start: int = 0,
      force_refresh: bool = False,
  ) -> dict[str, Any]:
      """Search pages in the configured Apache Incubator Confluence space."""
      if not query.strip():
          raise ValueError("query must not be empty")
      validate_range("limit", limit, 1, 50)
      validate_range("start", start, 0, 1_000_000)
  
      cql = f'space = "{escape_cql(client.SPACE_KEY)}" and type = page and text ~ "{escape_cql(query)}"'
      pages = client.confluence_get(
          "/rest/api/content/search",
          {
              "cql": cql,
              "limit": str(limit),
              "start": str(start),
              "expand": "body.view,version",
          },
          force_refresh=force_refresh,
      )
  
      return {
          "cql": cql,
          **client.pagination(pages),
          "pages": [
              {
                  **client.page_summary(page),
                  "excerpt": html_to_text(page.get("body", {}).get("view", {}).get("value", ""))[:800],
              }
              for page in pages.get("results", [])
          ],
      }

• src/incubator_cwiki_mcp/tools.py:49-49 (registration)

  The @mcp.tool() decorator registers cwiki_search_pages as an MCP tool on the FastMCP instance 'mcp' (defined on line 12).

  @mcp.tool()

• src/incubator_cwiki_mcp/tools.py:183-184 (helper)

  Helper function that escapes backslashes and double quotes in CQL values to prevent injection.

  def escape_cql(value: str) -> str:
      return value.replace("\\", "\\\\").replace('"', '\\"')

• src/incubator_cwiki_mcp/tools.py:178-180 (helper)

  Helper function to validate numeric parameters are within a given range.

  def validate_range(name: str, value: int, minimum: int, maximum: int) -> None:
      if value < minimum or value > maximum:
          raise ValueError(f"{name} must be between {minimum} and {maximum}")

• src/incubator_cwiki_mcp/tools.py:187-193 (helper)

  Helper function that converts HTML to plain text for the excerpt, using the _TextExtractor HTMLParser subclass.

  def html_to_text(html: str) -> str:
      parser = _TextExtractor()
      parser.feed(html)
      parser.close()
      text = parser.text()
      lines = [line.strip() for line in text.splitlines()]
      return "\n".join(line for line in lines if line)