MCP Outline Server

Instructions

Implementation Reference

• src/mcp_outline/features/documents/collection_tools.py:218-272 (handler)

  The MCP tool handler for 'update_collection'. Includes the @mcp.tool decorator with annotations, function signature serving as input schema, documentation, input validation, client retrieval, API call, and response formatting.
  @mcp.tool( annotations=ToolAnnotations( readOnlyHint=False, destructiveHint=True, idempotentHint=False, ) ) async def update_collection( collection_id: str, name: Optional[str] = None, description: Optional[str] = None, color: Optional[str] = None, ) -> str: """ Modifies an existing collection's properties. Use this tool when you need to: - Rename a collection - Update a collection's description - Change a collection's color coding - Refresh collection metadata Args: collection_id: The collection ID to update name: Optional new name for the collection description: Optional new description color: Optional new hex color code (e.g. #FF0000) Returns: Result message confirming update """ try: client = await get_outline_client() # Make sure at least one field is being updated if name is None and description is None and color is None: return ( "Error: You must specify at least one field to update." ) collection = await client.update_collection( collection_id, name, description, color ) if not collection: return "Failed to update collection." collection_name = collection.get("name", "Untitled") return f"Collection updated successfully: {collection_name}" except OutlineClientError as e: return f"Error updating collection: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}"
• src/mcp_outline/features/documents/collection_tools.py:52-317 (registration)

  The register_tools function in collection_tools.py that defines and registers the update_collection tool (and others) to the MCP server instance using @mcp.tool decorators. Called from documents/__init__.py.
  def register_tools(mcp) -> None: """ Register collection management tools with the MCP server. Args: mcp: The FastMCP server instance """ # Check environment variables for conditional registration read_only = os.getenv("OUTLINE_READ_ONLY", "").lower() in ( "true", "1", "yes", ) disable_delete = os.getenv("OUTLINE_DISABLE_DELETE", "").lower() in ( "true", "1", "yes", ) # Export tools (always registered) @mcp.tool( annotations=ToolAnnotations( readOnlyHint=True, destructiveHint=False, idempotentHint=True, ) ) async def export_collection( collection_id: str, format: str = "outline-markdown" ) -> str: """ Exports all documents in a collection to a downloadable file. IMPORTANT: This tool starts an asynchronous export operation which may take time to complete. The function returns information about the operation, including its status. When the operation is complete, the file can be downloaded or accessed via Outline's UI. The export preserves the document hierarchy and includes all document content and structure in the specified format. Use this tool when you need to: - Create a backup of collection content - Share collection content outside of Outline - Convert collection content to other formats - Archive collection content for offline use Args: collection_id: The collection ID to export format: Export format ("outline-markdown", "json", or "html") Returns: Information about the export operation and how to access the file """ try: client = await get_outline_client() file_operation = await client.export_collection( collection_id, format ) if not file_operation: return "Failed to start export operation." return _format_file_operation(file_operation) except OutlineClientError as e: return f"Error exporting collection: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}" @mcp.tool( annotations=ToolAnnotations( readOnlyHint=True, destructiveHint=False, idempotentHint=True, ) ) async def export_all_collections(format: str = "outline-markdown") -> str: """ Exports the entire workspace content to a downloadable file. IMPORTANT: This tool starts an asynchronous export operation which may take time to complete, especially for large workspaces. The function returns information about the operation, including its status. When the operation is complete, the file can be downloaded or accessed via Outline's UI. The export includes all collections, documents, and their hierarchies in the specified format. Use this tool when you need to: - Create a complete backup of all workspace content - Migrate content to another system - Archive all workspace documents - Get a comprehensive export of knowledge base Args: format: Export format ("outline-markdown", "json", or "html") Returns: Information about the export operation and how to access the file """ try: client = await get_outline_client() file_operation = await client.export_all_collections(format) if not file_operation: return "Failed to start export operation." return _format_file_operation(file_operation) except OutlineClientError as e: return f"Error exporting collections: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}" # Conditional registration for write operations if not read_only: @mcp.tool( annotations=ToolAnnotations( readOnlyHint=False, destructiveHint=False, idempotentHint=False, ) ) async def create_collection( name: str, description: str = "", color: Optional[str] = None ) -> str: """ Creates a new collection for organizing documents. Use this tool when you need to: - Create a new section or category for documents - Set up a workspace for a new project or team - Organize content by department or topic - Establish a separate space for related documents Args: name: Name for the collection description: Optional description of the collection's purpose color: Optional hex color code for visual identification (e.g. #FF0000) Returns: Result message with the new collection ID """ try: client = await get_outline_client() collection = await client.create_collection( name, description, color ) if not collection: return "Failed to create collection." collection_id = collection.get("id", "unknown") collection_name = collection.get("name", "Untitled") return ( f"Collection created successfully: {collection_name} " f"(ID: {collection_id})" ) except OutlineClientError as e: return f"Error creating collection: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}" @mcp.tool( annotations=ToolAnnotations( readOnlyHint=False, destructiveHint=True, idempotentHint=False, ) ) async def update_collection( collection_id: str, name: Optional[str] = None, description: Optional[str] = None, color: Optional[str] = None, ) -> str: """ Modifies an existing collection's properties. Use this tool when you need to: - Rename a collection - Update a collection's description - Change a collection's color coding - Refresh collection metadata Args: collection_id: The collection ID to update name: Optional new name for the collection description: Optional new description color: Optional new hex color code (e.g. #FF0000) Returns: Result message confirming update """ try: client = await get_outline_client() # Make sure at least one field is being updated if name is None and description is None and color is None: return ( "Error: You must specify at least one field to update." ) collection = await client.update_collection( collection_id, name, description, color ) if not collection: return "Failed to update collection." collection_name = collection.get("name", "Untitled") return f"Collection updated successfully: {collection_name}" except OutlineClientError as e: return f"Error updating collection: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}" # Delete collection requires both read_only and disable_delete checks if not read_only and not disable_delete: @mcp.tool( annotations=ToolAnnotations( readOnlyHint=False, destructiveHint=True, idempotentHint=True, ) ) async def delete_collection(collection_id: str) -> str: """ Permanently removes a collection and all its documents. Use this tool when you need to: - Remove an entire section of content - Delete obsolete project collections - Remove collections that are no longer needed - Clean up workspace organization WARNING: This action cannot be undone and will delete all documents within the collection. Args: collection_id: The collection ID to delete Returns: Result message confirming deletion """ try: client = await get_outline_client() success = await client.delete_collection(collection_id) if success: return ( "Collection and all its documents deleted " "successfully." ) else: return "Failed to delete collection." except OutlineClientError as e: return f"Error deleting collection: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}"
• src/mcp_outline/utils/outline_client.py:403-435 (helper)

  Supporting helper in OutlineClient that makes the HTTP POST request to Outline API endpoint 'collections.update' with the provided fields.
  async def update_collection( self, collection_id: str, name: Optional[str] = None, description: Optional[str] = None, color: Optional[str] = None, ) -> Dict[str, Any]: """ Update an existing collection. Args: collection_id: The ID of the collection to update name: Optional new name for the collection description: Optional new description color: Optional new hex color code Returns: The updated collection data """ data: Dict[str, Any] = {"id": collection_id} if name is not None: data["name"] = name if description is not None: data["description"] = description if color is not None: data["color"] = color response = await self.post("collections.update", data) return response.get("data", {})
• src/mcp_outline/features/documents/__init__.py:33-33 (registration)

  Call to register_collection_tools within the documents feature registration, invoked from features/__init__.py register_all.
  collection_tools.register_tools(mcp)
• src/mcp_outline/server.py:32-32 (registration)

  Top-level call to register_all features in the main server.py, starting the registration chain.
  register_all(mcp)