Sefaria Jewish Library MCP Server

Instructions

Implementation Reference

• src/sefaria_jewish_library/sefaria_handler.py:231-329 (handler)

  Core handler function that executes the search_texts tool by making a POST request to Sefaria's /api/search-wrapper endpoint, processing hits, extracting highlights and references, and formatting the results as a string.

  async def search_texts(query: str, slop: int =2, filters=None, size=10):
      """
      Search for texts in the Sefaria library.
      
      Args:
          query (str): The search query
          slop (int, optional): The maximum distance between each query word in the resulting document. 0 means an exact match must be found. defaults to 2
          filters (list, optional): Filters to apply to the text path in English (Examples: "Shulkhan Arukh", "maimonides", "talmud").
          size (int, optional): Number of results to return. defaults to 10.
          
      Returns:
          str: Formatted search results
      """
      # Use the www subdomain as specified in the documentation
      url = "https://www.sefaria.org/api/search-wrapper"
      
      # Build the request payload
      payload = {
          "query": query,
          "type": "text",
          "field":  "naive_lemmatizer",
          "size": size,
    "source_proj": True,
          "sort_fields": [
      "pagesheetrank"
    ],
    "sort_method": "score",
          "slop": slop,
       
      }
      if filters:
          payload["filters"] = filters
  
      
      # Make the POST request
      try:
          response = requests.post(url, json=payload)
          response.raise_for_status()
          
          logging.debug(f"Sefaria's Search API response: {response.text}")
          
          # Parse JSON response
          data = response.json()
          
          print(data)
          
          # Format the results
          results = []
          
          # Check if we have hits in the response
          if "hits" in data and "hits" in data["hits"]:
              # Get the actual total hits count
              total_hits = data["hits"].get("total", 0)
              # Handle different response formats
              if isinstance(total_hits, dict) and "value" in total_hits:
                  total_hits = total_hits["value"]
           
              # Process each hit
              for hit in data["hits"]["hits"]:
                  source = hit["_source"]
                  ref = source["ref"]
                  heRef = source["heRef"]
                  
                  # Get the content snippet
                  text_snippet = ""
                  
                  # Get highlighted text if available (this contains the search term highlighted)
                  if "highlight" in hit:
                      for field_name, highlights in hit["highlight"].items():
                          if highlights and len(highlights) > 0:
                              # Join multiple highlights with ellipses
                              text_snippet = " [...] ".join(highlights)
                              break
                  
                  # If no highlight, use content from the source
                  if not text_snippet:
                      # Try different fields that might contain content
                      for field_name in ["naive_lemmatizer", "exact"]:
                          if field_name in source and source[field_name]:
                              content = source[field_name]
                              if isinstance(content, str):
                                  # Limit to a reasonable snippet length
                                  text_snippet = content[:300] + ("..." if len(content) > 300 else "")
                                  break
               
                  # Add the formatted result
                  results.append(f"Reference: {ref}\n Hebrew Reference: {heRef}\n Highlight: {text_snippet}\n")
          
          # Return a message if no results were found
          if len(results) <= 1:
              return f"No results found for '{query}'."
          logging.debug(f"formated results: {results}")
          return "\n".join(results)
      
      except json.JSONDecodeError as e:
          return f"Error: Failed to parse JSON response: {str(e)}"
      except requests.exceptions.RequestException as e:
          return f"Error during search API request: {str(e)}"

• src/sefaria_jewish_library/server.py:64-94 (registration)

  Tool registration in list_tools(), defining the name, description, and input JSON schema for the search_texts tool.

  types.Tool(
      name="search_texts",
      description="search for jewish texts in the Sefaria library",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "The search query",
              },
              "slop":{
                  "type": "integer",
                  "description": "The maximum distance between each query word in the resulting document. 0 means an exact match must be found.",
                  "default": 2
              },
           
              "filters":{
                  "type": "list",
                  "description": 'Filters to apply to the text path in English (Examples: "Shulkhan Arukh", "maimonides", "talmud").',
                  "default" : "[]"
  
              },                        
              "size": {
                  "type": "integer",
                  "description": "Number of results to return.",
                  "default": 10
              }
          },
          "required": ["query"],
      },
  ),

• src/sefaria_jewish_library/server.py:189-217 (handler)

  MCP tool dispatcher logic in handle_call_tool() that validates input arguments, calls the core search_texts handler, and returns TextContent or error.

  elif name == "search_texts":
      try:
          query = arguments.get("query")
          if not query:
              raise ValueError("Missing query parameter")
              
          slop = arguments.get("slop")
          if not slop : # Use 'is None' to distinguish between explicitly provided null and missing key
              slop = 2
          filters = arguments.get("filters")
          if not filters:
              filters = None
          size = arguments.get("size")
          if not size:
              size = 10
          
          logger.debug(f"handle_search_texts: {query}")
          results = await search_texts(query, slop, filters, size)
          
          return [types.TextContent(
              type="text",
              text=results
          )]
      except Exception as err:
          logger.error(f"search texts error: {err}", exc_info=True)
          return [types.TextContent(
              type="text",
              text=f"Error: {str(err)}"
          )]