RSpace MCP Server

Instructions

Implementation Reference

• main.py:172-272 (handler)

  The handler function for the 'search_documents' MCP tool. Decorated with @mcp.tool for automatic registration. Handles both simple and advanced searches across RSpace ELN documents using the eln_cli client, supporting various query types, operators, pagination, sorting, and optional full content retrieval.

  @mcp.tool(tags={"rspace", "search"})
  def search_documents(
      query: str,
      search_type: Literal["simple", "advanced"] = "simple",
      query_types: List[Literal["global", "fullText", "tag", "name", "created", "lastModified", "form", "attachment"]] = None,
      operator: Literal["and", "or"] = "and",
      order_by: str = "lastModified desc",
      page_number: int = 0,
      page_size: int = 20,
      include_content: bool = False
  ) -> dict:
      """
      Generic search tool for RSpace documents with flexible search options
      
      Usage: Search across all your RSpace documents using various criteria
      
      Parameters:
      - query: The search term(s) to look for
      - search_type: "simple" for basic search, "advanced" for multi-criteria search
      - query_types: List of search types to use (for advanced search):
          - "global": Search across all document content and metadata
          - "fullText": Search within document text content
          - "tag": Search by document tags
          - "name": Search by document names/titles
          - "created": Search by creation date (use ISO format like "2024-01-01")
          - "lastModified": Search by modification date
          - "form": Search by form type
          - "attachment": Search by attachments
      - operator: "and" (all criteria must match) or "or" (any criteria can match)
      - order_by: Sort results by field (e.g., "lastModified desc", "name asc")
      - page_number: Page number for pagination (0-based)
      - page_size: Number of results per page (max 200)
      - include_content: Whether to fetch full document content (slower but more complete)
      
      Returns: Dictionary with search results and metadata
      
      Examples:
      - Simple text search: search_documents("PCR protocol")
      - Search by tags: search_documents("experiment", search_type="advanced", query_types=["tag"])
      - Multi-criteria search: search_documents("DNA", search_type="advanced", 
                                              query_types=["fullText", "tag"], operator="or")
      """
      if page_size > 200:
          raise ValueError("page_size must be 200 or less")
      
      if search_type == "simple":
          # Use simple search - works like RSpace's "All" search
          results = eln_cli.get_documents(
              query=query,
              order_by=order_by,
              page_number=page_number,
              page_size=page_size
          )
      else:
          # Use advanced search with AdvancedQueryBuilder
          if query_types is None:
              query_types = ["global"]  # Default to global search
          
          builder = AdvancedQueryBuilder(operator=operator)
          
          # Add search terms for each specified query type
          for query_type in query_types:
              if query_type == "global":
                  builder.add_term(query, AdvancedQueryBuilder.QueryType.GLOBAL)
              elif query_type == "fullText":
                  builder.add_term(query, AdvancedQueryBuilder.QueryType.FULL_TEXT)
              elif query_type == "tag":
                  builder.add_term(query, AdvancedQueryBuilder.QueryType.TAG)
              elif query_type == "name":
                  builder.add_term(query, AdvancedQueryBuilder.QueryType.NAME)
              elif query_type == "created":
                  builder.add_term(query, AdvancedQueryBuilder.QueryType.CREATED)
              elif query_type == "lastModified":
                  builder.add_term(query, AdvancedQueryBuilder.QueryType.LAST_MODIFIED)
              elif query_type == "form":
                  builder.add_term(query, AdvancedQueryBuilder.QueryType.FORM)
              elif query_type == "attachment":
                  builder.add_term(query, AdvancedQueryBuilder.QueryType.ATTACHMENT)
          
          advanced_query = builder.get_advanced_query()
          results = eln_cli.get_documents_advanced_query(
              advanced_query=advanced_query,
              order_by=order_by,
              page_number=page_number,
              page_size=page_size
          )
      
      # Optionally fetch full content for each document
      if include_content and 'documents' in results:
          for doc in results['documents']:
              try:
                  full_doc = eln_cli.get_document(doc['globalId'])
                  # Add concatenated content to the document
                  content = ''
                  for field in full_doc.get('fields', []):
                      content += field.get('content', '')
                  doc['fullContent'] = content
              except Exception as e:
                  doc['fullContent'] = f"Error fetching content: {str(e)}"
      
      return results