get_collection_structure
Retrieve the hierarchical structure of a collection to understand document organization, identify IDs, and view parent-child relationships for better content overview.
Instructions
Retrieves the hierarchical document structure of a collection.
Use this tool when you need to:
- Understand how documents are organized in a collection
- Find document IDs within a specific collection
- See the parent-child relationships between documents
- Get an overview of a collection's content structure
Args:
collection_id: The collection ID to examine
Returns:
Formatted string showing the hierarchical structure of documents
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection_id | Yes |
Implementation Reference
- Handler function for the 'get_collection_structure' tool. Decorated with @mcp.tool() for registration. Fetches hierarchical documents from the Outline client and formats them using _format_collection_documents.
@mcp.tool( annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True) ) async def get_collection_structure(collection_id: str) -> str: """ Retrieves the hierarchical document structure of a collection. Use this tool when you need to: - Understand how documents are organized in a collection - Find document IDs within a specific collection - See the parent-child relationships between documents - Get an overview of a collection's content structure Args: collection_id: The collection ID to examine Returns: Formatted string showing the hierarchical structure of documents """ try: client = await get_outline_client() docs = await client.get_collection_documents(collection_id) return _format_collection_documents(docs) except OutlineClientError as e: return f"Error getting collection structure: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}" - Supporting helper function that recursively formats the hierarchical document structure (with children) into a markdown tree view.
def _format_collection_documents(doc_nodes: List[Dict[str, Any]]) -> str: """Format collection document structure into readable text.""" if not doc_nodes: return "No documents found in this collection." def format_node(node, depth=0): # Extract node details title = node.get("title", "Untitled") node_id = node.get("id", "") children = node.get("children", []) # Format this node indent = " " * depth text = f"{indent}- {title} (ID: {node_id})\n" # Recursively format children for child in children: text += format_node(child, depth + 1) return text output = "# Collection Structure\n\n" for node in doc_nodes: output += format_node(node) return output - The register_tools function defines and registers all document search tools, including get_collection_structure, using @mcp.tool decorators.
def register_tools(mcp) -> None: """ Register document search tools with the MCP server. Args: mcp: The FastMCP server instance """ @mcp.tool( annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True) ) async def search_documents( query: str, collection_id: Optional[str] = None, limit: int = 25, offset: int = 0, ) -> str: """ Searches for documents using keywords or phrases across your knowledge base. IMPORTANT: The search performs full-text search across all document content and titles. Results are ranked by relevance, with exact matches and title matches typically ranked higher. The search will return snippets of content (context) where the search terms appear in the document. You can limit the search to a specific collection by providing the collection_id. PAGINATION: By default, returns up to 25 results at a time. If more results exist, use the 'offset' parameter to fetch additional pages. For example, use offset=25 to get results 26-50, offset=50 for 51-75, etc. Use this tool when you need to: - Find documents containing specific terms or topics - Locate information across multiple documents - Search within a specific collection using collection_id - Discover content based on keywords - Browse through large result sets using limit and offset Args: query: Search terms (e.g., "vacation policy" or "project plan") collection_id: Optional collection to limit the search to limit: Maximum results to return (default: 25, max: 100) offset: Number of results to skip for pagination (default: 0) Returns: Formatted string containing search results with document titles, contexts, and pagination information """ try: client = await get_outline_client() response = await client.search_documents( query, collection_id, limit, offset ) # Extract results and pagination metadata results = response.get("data", []) pagination = response.get("pagination", {}) return _format_search_results(results, pagination) except OutlineClientError as e: return f"Error searching documents: {str(e)}" except Exception as e: return f"Unexpected error during search: {str(e)}" @mcp.tool( annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True) ) async def list_collections() -> str: """ Retrieves and displays all available collections in the workspace. Use this tool when you need to: - See what collections exist in the workspace - Get collection IDs for other operations - Explore the organization of the knowledge base - Find a specific collection by name Returns: Formatted string containing collection names, IDs, and descriptions """ try: client = await get_outline_client() collections = await client.list_collections() return _format_collections(collections) except OutlineClientError as e: return f"Error listing collections: {str(e)}" except Exception as e: return f"Unexpected error listing collections: {str(e)}" @mcp.tool( annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True) ) async def get_collection_structure(collection_id: str) -> str: """ Retrieves the hierarchical document structure of a collection. Use this tool when you need to: - Understand how documents are organized in a collection - Find document IDs within a specific collection - See the parent-child relationships between documents - Get an overview of a collection's content structure Args: collection_id: The collection ID to examine Returns: Formatted string showing the hierarchical structure of documents """ try: client = await get_outline_client() docs = await client.get_collection_documents(collection_id) return _format_collection_documents(docs) except OutlineClientError as e: return f"Error getting collection structure: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}" @mcp.tool( annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True) ) async def get_document_id_from_title( query: str, collection_id: Optional[str] = None ) -> str: """ Locates a document ID by searching for its title. IMPORTANT: This tool first checks for exact title matches (case-insensitive). If none are found, it returns the best partial match instead. This is useful when you're not sure of the exact title but need to reference a document in other operations. Results are more accurate when you provide more of the actual title in your query. Use this tool when you need to: - Find a document's ID when you only know its title - Get the document ID for use in other operations - Verify if a document with a specific title exists - Find the best matching document if exact title is unknown Args: query: Title to search for (can be exact or partial) collection_id: Optional collection to limit the search to Returns: Document ID if found, or best match information """ try: client = await get_outline_client() response = await client.search_documents(query, collection_id) # Extract results from response results = response.get("data", []) if not results: return f"No documents found matching '{query}'" # Check if we have an exact title match exact_matches = [ r for r in results if ( r.get("document", {}).get("title", "").lower() == query.lower() ) ] if exact_matches: doc = exact_matches[0].get("document", {}) doc_id = doc.get("id", "unknown") title = doc.get("title", "Untitled") return f"Document ID: {doc_id} (Title: {title})" # Otherwise return the top match doc = results[0].get("document", {}) doc_id = doc.get("id", "unknown") title = doc.get("title", "Untitled") return f"Best match - Document ID: {doc_id} (Title: {title})" except OutlineClientError as e: return f"Error searching for document: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}"