MCP Outline Server

Instructions

    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
    

Implementation Reference

• src/mcp_outline/features/documents/document_search.py:255-319 (handler)

  The core handler function for the 'get_document_id_from_title' tool. It searches for documents by title (exact or best match), extracts the document ID, and formats the response. Includes type annotations, docstring schema, and ToolAnnotations for MCP registration.

  @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)}"

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

  The specific call to register_tools from document_search module, which defines and registers the get_document_id_from_title tool among others with the MCP server.

  document_search.register_tools(mcp)