search_texts
Search Jewish texts in Sefaria Library using custom queries, filters, and word proximity settings to retrieve specific results efficiently.
Instructions
search for jewish texts in the Sefaria library
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filters | No | Filters to apply to the text path in English (Examples: "Shulkhan Arukh", "maimonides", "talmud"). | [] |
| query | Yes | The search query | |
| size | No | Number of results to return. | |
| slop | No | The maximum distance between each query word in the resulting document. 0 means an exact match must be found. |
Implementation Reference
- 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"], }, ), - 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)}" )]