Sefaria Jewish Library MCP Server

Instructions

Implementation Reference

• src/sefaria_jewish_library/sefaria_handler.py:95-107 (handler)

  The primary handler function that implements the tool logic: fetches related links from Sefaria API for the given reference and filters those of type 'commentary', returning a list of Hebrew commentary references.

  async def get_commentaries(parasha_ref)-> list[str]:
      """
      Retrieves and filters commentaries on the given verse.
      """
      data = get_request_json_data("api/related/", parasha_ref)
  
      commentaries = []
      if data and "links" in data:
          for linked_text in data["links"]:
              if linked_text.get('type') == 'commentary':
                  commentaries.append(linked_text.get('sourceHeRef'))
  
      return commentaries

• src/sefaria_jewish_library/server.py:50-63 (registration)

  Registers the 'get_commentaries' tool with the MCP server in the list_tools handler, specifying its description and input schema.

  types.Tool(
      name="get_commentaries",
      description="get a list of references of commentaries for a jewish text",
      inputSchema={
          "type": "object",
          "properties": {
              "reference": {
                  "type": "string",
                  "description": "the reference of the jewish text, e.g. 'שולחן ערוך אורח חיים סימן א' or 'Genesis 1:1'",
              },
          },
          "required": ["reference"],
      },
  ),

• src/sefaria_jewish_library/server.py:53-62 (schema)

  Defines the JSON schema for the tool's input: requires a 'reference' string parameter.

  inputSchema={
      "type": "object",
      "properties": {
          "reference": {
              "type": "string",
              "description": "the reference of the jewish text, e.g. 'שולחן ערוך אורח חיים סימן א' or 'Genesis 1:1'",
          },
      },
      "required": ["reference"],
  },

• src/sefaria_jewish_library/server.py:169-187 (handler)

  Tool dispatch handler in the call_tool function that extracts the reference argument, calls the get_commentaries function, and formats the result as text content or handles errors.

  elif name == "get_commentaries":
      try:
          reference = arguments.get("reference")
          if not reference:
              raise ValueError("Missing  parameter")
          
          logger.debug(f"handle_get_commentaries: {reference}")
          commentaries = await get_commentaries(reference)
          
          return [types.TextContent(
              type="text",
              text="\n".join(commentaries)
          )]
      except Exception as err:
          logger.error(f"retreive commentaries error: {err}", exc_info=True)
          return [types.TextContent(
              type="text",
              text=f"Error: {str(err)}"
          )]

• src/sefaria_jewish_library/sefaria_handler.py:7-26 (helper)

  Utility helper function used by get_commentaries to perform API requests to Sefaria and retrieve JSON data.

  def get_request_json_data(endpoint, ref=None, param=None):
      """
      Helper function to make GET requests to the Sefaria API and parse the JSON response.
      """
      url = f"{SEFARIA_API_BASE_URL}/{endpoint}"
  
      if ref:
          url += f"{ref}"
  
      if param:
          url += f"?{param}"
  
      try:
          response = requests.get(url)
          response.raise_for_status()  # Raise an exception for bad status codes
          data = response.json()
          return data
      except requests.exceptions.RequestException as e:
          print(f"Error during API request: {e}")
          return None