MCP Outline Server

Instructions

    Exports a document as plain markdown text.
    
    Use this tool when you need to:
    - Get clean markdown content without formatting
    - Extract document content for external use
    - Process document content in another application
    - Share document content outside Outline
    
    Args:
        document_id: The document ID to export
        
    Returns:
        Document content in markdown format without additional formatting
    

Implementation Reference

• src/mcp_outline/features/documents/document_reading.py:67-92 (handler)

  Core implementation of the export_document MCP tool. Retrieves markdown export of a document via the Outline API.

  async def export_document(document_id: str) -> str:
      """
      Exports a document as plain markdown text.
  
      Use this tool when you need to:
      - Get clean markdown content without formatting
      - Extract document content for external use
      - Process document content in another application
      - Share document content outside Outline
  
      Args:
          document_id: The document ID to export
  
      Returns:
          Document content in markdown format without additional formatting
      """
      try:
          client = await get_outline_client()
          response = await client.post(
              "documents.export", {"id": document_id}
          )
          return response.get("data", "No content available")
      except OutlineClientError as e:
          return f"Error exporting document: {str(e)}"
      except Exception as e:
          return f"Unexpected error: {str(e)}"

• src/mcp_outline/features/documents/document_reading.py:64-66 (registration)

  MCP tool registration decorator for export_document, specifying read-only and idempotent hints.

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

• src/mcp_outline/features/documents/document_reading.py:65-65 (schema)

  Tool annotations defining behavioral hints (read-only, idempotent) used by MCP clients.

  annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True)

• src/mcp_outline/features/documents/common.py:18-44 (helper)

  Helper function to create and authenticate the OutlineClient instance used by the export_document handler.

  async def get_outline_client() -> OutlineClient:
      """
      Get the document outline client (async).
  
      Returns:
          OutlineClient instance
  
      Raises:
          OutlineClientError: If client creation fails
      """
      try:
          # Get API credentials from environment variables
          api_key = os.getenv("OUTLINE_API_KEY")
          api_url = os.getenv("OUTLINE_API_URL")
  
          # Create an instance of the outline client
          client = OutlineClient(api_key=api_key, api_url=api_url)
  
          # Test the connection by attempting to get auth info
          _ = await client.auth_info()
  
          return client
      except OutlineError as e:
          raise OutlineClientError(f"Outline client error: {str(e)}")
      except Exception as e:
          raise OutlineClientError(f"Unexpected error: {str(e)}")

• src/mcp_outline/features/documents/document_reading.py:28-93 (registration)

  Function that registers both read_document and export_document tools on the MCP server instance.

  def register_tools(mcp) -> None:
      """
      Register document reading tools with the MCP server.
  
      Args:
          mcp: The FastMCP server instance
      """
  
      @mcp.tool(
          annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True)
      )
      async def read_document(document_id: str) -> str:
          """
          Retrieves and displays the full content of a document.
  
          Use this tool when you need to:
          - Access the complete content of a specific document
          - Review document information in detail
          - Quote or reference document content
          - Analyze document contents
  
          Args:
              document_id: The document ID to retrieve
  
          Returns:
              Formatted string containing the document title and content
          """
          try:
              client = await get_outline_client()
              document = await client.get_document(document_id)
              return _format_document_content(document)
          except OutlineClientError as e:
              return f"Error reading document: {str(e)}"
          except Exception as e:
              return f"Unexpected error: {str(e)}"
  
      @mcp.tool(
          annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True)
      )
      async def export_document(document_id: str) -> str:
          """
          Exports a document as plain markdown text.
  
          Use this tool when you need to:
          - Get clean markdown content without formatting
          - Extract document content for external use
          - Process document content in another application
          - Share document content outside Outline
  
          Args:
              document_id: The document ID to export
  
          Returns:
              Document content in markdown format without additional formatting
          """
          try:
              client = await get_outline_client()
              response = await client.post(
                  "documents.export", {"id": document_id}
              )
              return response.get("data", "No content available")
          except OutlineClientError as e:
              return f"Error exporting document: {str(e)}"
          except Exception as e:
              return f"Unexpected error: {str(e)}"