Confluence MCP Server

Instructions

    搜索 Confluence 页面内容

    Args:
        query: 搜索关键词（支持字符串、数字等格式，会自动转换为字符串）
        limit: 返回结果数量限制，默认10条
        ctx: MCP 上下文

    Returns:
        Dict: 包含搜索结果的字典
    

Implementation Reference

• servers/confluence_mcp.py:17-60 (handler)

  Main search_confluence tool handler - decorated with @mcp.tool() for registration, accepts query parameter and optional limit, converts query to string, logs the operation, calls confluence.search_by_key(), and returns formatted results with error handling

  @mcp.tool()
  async def search_confluence(
      query: Union[str, int, float],
      ctx: Context,
      limit: int = 10
  ) -> Dict:
      """
      搜索 Confluence 页面内容
  
      Args:
          query: 搜索关键词（支持字符串、数字等格式，会自动转换为字符串）
          limit: 返回结果数量限制，默认10条
          ctx: MCP 上下文
  
      Returns:
          Dict: 包含搜索结果的字典
      """
      try:
          query_str = str(query)  # 将任何类型转换为字符串
  
          await ctx.session.send_log_message(
              level="info",
              data=f"搜索 Confluence: query='{query_str}', limit={limit}"
          )
  
          results = confluence.search_by_key(query_str, limit)
  
          return {
              "success": True,
              "query": query,
              "total": len(results),
              "results": results
          }
  
      except Exception as e:
          error_msg = f"搜索失败: {str(e)}"
          await ctx.session.send_log_message(
              level="error",
              data=error_msg
          )
          return {
              "success": False,
              "error": error_msg
          }

• utils/confluence_utils.py:35-61 (helper)

  Confluence search helper method - uses CQL (Confluence Query Language) to search both title and content fields, formats results with page id, title, type, url, and excerpt

  def search_by_key(self, key, limit=10):
      """
      搜索 Confluence 页面（标题和内容）
      :param key: 搜索关键字
      :param limit: 返回结果数量限制
      :return: 搜索结果列表，每个结果包含页面基本信息
      """
  
      # 使用 CQL 搜索标题和内容
      cql = f'text ~ "{key}" OR title ~ "{key}"'
      results = self.confluence.cql(cql, limit=limit)
      
      if not results or 'results' not in results:
          return []
          
      # 格式化返回结果
      formatted_results = []
      for result in results['results']:
          formatted_results.append({
              'id': result.get('content', {}).get('id'),
              'title': result.get('content', {}).get('title'),
              'type': result.get('content', {}).get('type'),
              'url': self.page_url.format(page_id=result.get('content', {}).get('id')),
              'excerpt': result.get('excerpt', '')  # 搜索结果中的匹配内容片段
          })
      
      return formatted_results