MCP Outline Server

Instructions

    Retrieves comments on a specific document with pagination support.
    
    IMPORTANT: By default, this returns up to 25 comments at a time. If 
    there are more than 25 comments on the document, you'll need to make 
    multiple calls with different offset values to get all comments. The 
    response will indicate if there 
    are more comments available.
    
    Use this tool when you need to:
    - Review feedback and discussions on a document
    - See all comments from different users
    - Find specific comments or questions
    - Track collaboration and input on documents
    
    Args:
        document_id: The document ID to get comments from
        include_anchor_text: Whether to include the document text that 
            comments refer to
        limit: Maximum number of comments to return (default: 25)
        offset: Number of comments to skip for pagination (default: 0)
        
    Returns:
        Formatted string containing comments with author, date, and 
        optional anchor text
    

Implementation Reference

• src/mcp_outline/features/documents/document_collaboration.py:84-135 (handler)

  The main execution logic for the list_document_comments tool. Fetches comments via Outline API, handles pagination, and formats output using _format_comments.

  async def list_document_comments(
      document_id: str,
      include_anchor_text: bool = False,
      limit: int = 25,
      offset: int = 0,
  ) -> str:
      """
      Retrieves comments on a specific document with pagination support.
  
      IMPORTANT: By default, this returns up to 25 comments at a time. If
      there are more than 25 comments on the document, you'll need to make
      multiple calls with different offset values to get all comments. The
      response will indicate if there
      are more comments available.
  
      Use this tool when you need to:
      - Review feedback and discussions on a document
      - See all comments from different users
      - Find specific comments or questions
      - Track collaboration and input on documents
  
      Args:
          document_id: The document ID to get comments from
          include_anchor_text: Whether to include the document text that
              comments refer to
          limit: Maximum number of comments to return (default: 25)
          offset: Number of comments to skip for pagination (default: 0)
  
      Returns:
          Formatted string containing comments with author, date, and
          optional anchor text
      """
      try:
          client = await get_outline_client()
          data = {
              "documentId": document_id,
              "includeAnchorText": include_anchor_text,
              "limit": limit,
              "offset": offset,
          }
  
          response = await client.post("comments.list", data)
          comments = response.get("data", [])
          pagination = response.get("pagination", {})
  
          total_count = pagination.get("total", len(comments))
          return _format_comments(comments, total_count, limit, offset)
      except OutlineClientError as e:
          return f"Error listing comments: {str(e)}"
      except Exception as e:
          return f"Unexpected error: {str(e)}"

• src/mcp_outline/features/documents/document_collaboration.py:81-83 (registration)

  Registers the list_document_comments tool with the MCP server using the @mcp.tool decorator inside register_tools.

  @mcp.tool(
      annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True)
  )

• src/mcp_outline/features/documents/document_collaboration.py:18-70 (helper)

  Supporting function that formats the raw comments data into a human-readable markdown string with pagination and metadata.

  def _format_comments(
      comments: List[Dict[str, Any]],
      total_count: int = 0,
      limit: int = 25,
      offset: int = 0,
  ) -> str:
      """Format document comments into readable text."""
      if not comments:
          return "No comments found for this document."
  
      output = "# Document Comments\n\n"
  
      # Add pagination info if provided
      if total_count:
          shown_range = (
              f"{offset + 1}-{min(offset + len(comments), total_count)}"
          )
          output += f"Showing comments {shown_range} of {total_count} total\n\n"
  
          # Add warning if there might be more comments than shown
          if len(comments) == limit:
              output += "Note: Only showing the first batch of comments. "
              output += f"Use offset={offset + limit} to see more comments.\n\n"
  
      for i, comment in enumerate(comments, offset + 1):
          user = comment.get("createdBy", {}).get("name", "Unknown User")
          created_at = comment.get("createdAt", "")
          comment_id = comment.get("id", "")
          anchor_text = comment.get("anchorText", "")
  
          # Extract data object containing the comment content
          data = comment.get("data", {})
  
          # Convert data to JSON string for display
          try:
              import json
  
              text = json.dumps(data, indent=2)
          except Exception:
              text = str(data)
  
          output += f"## {i}. Comment by {user}\n"
          output += f"ID: {comment_id}\n"
          if created_at:
              output += f"Date: {created_at}\n"
          if anchor_text:
              output += f'\nReferencing text: "{anchor_text}"\n'
          if data:
              output += f"\nComment content:\n```json\n{text}\n```\n\n"
          else:
              output += "\n(No comment content found)\n\n"
  
      return output

• src/mcp_outline/features/documents/__init__.py:32-32 (registration)

  Higher-level registration that invokes register_tools from document_collaboration module, making list_document_comments available.

  document_collaboration.register_tools(mcp)

• src/mcp_outline/features/documents/document_collaboration.py:84-89 (schema)

  Function signature with type hints and defaults defining the input schema (parameters) and output type (str). Docstring provides detailed description.

  async def list_document_comments(
      document_id: str,
      include_anchor_text: bool = False,
      limit: int = 25,
      offset: int = 0,
  ) -> str: