StjLegalPrecedentsRequest

Instructions

Implementation Reference

• src/brlaw_mcp_server/presentation/mcp.py:40-192 (schema)

  Definition of the StjLegalPrecedentsRequest Pydantic model (input schema for the STJ tool). Inherits from BaseLegalPrecedentsRequest, adds a 'summary' field with extensive documentation of search operators.

  class StjLegalPrecedentsRequest(BaseLegalPrecedentsRequest):
      """Requisição dos precedentes judiciais do Superior Tribunal de Justiça (STJ) que satisfaçam os critérios passados.
  
      O STJ é a instância máxima da justiça brasileira no âmbito infraconstitucional. É a Corte
      responsável por uniformizar a interpretação da lei federal em todo o País.
  
      Produz decisões que influenciam todos os aspectos da vida cotidiana dos cidadãos, a maioria
      envolvendo causas de competência da chamada Justiça Comum.
  
      É de sua responsabilidade a solução definitiva de casos civis e criminais que não envolvam
      matéria constitucional, sob reserva do Supremo Tribunal Federal (STF), nem questões afetas ao
      âmbito específico da Justiça do Trabalho, da Justiça Eleitoral ou da Justiça Militar.
  
      Cabe também ao STJ a apreciação de decisões judiciais emitidas no exterior, entre as quais
      cartas rogatórias, pedidos de homologação de decisões estrangeiras e ações em que há contestação
      de sentença proferida fora do país."""
  
      summary: str = Field(
          title="Ementa",
          description=textwrap.dedent("""
          Critérios que serão buscados na ementa das decisões desejadas.
  
          É possível utilizar operadores textuais para aumentar a assertividade da busca. Na ausência 
          de qualquer operador explícito entre duas palavras, o sistema presumirá o operador `e`.
          Ou seja, `supermercado furto veículo` é o mesmo que `supermercado e furto e veículo`.
  
          ## Operadores lógicos
          ### `e`
          Localiza termos em qualquer ordem ou campo do documento.
  
          EXEMPLO: supermercado e furto e veículo
  
          RESULTADO: o sistema buscará documentos que contenham as três palavras, em qualquer ordem ou 
          distância.
  
          ATENÇÃO: esse é o operador presumido entre duas palavras, quando não houver outro operador 
          explícito. Assim, não é necessário explicitá-lo nesses casos. Por exemplo, `supermercado e 
          furto` é o mesmo que `supermercado furto`.
  
          ### `ou`
          Localiza um e/ou outro termo. Os termos devem vir sempre entre parênteses.
  
          EXEMPLO: (carro ou automóvel ou veículo)
  
          RESULTADO: o sistema buscará documentos que contenham qualquer uma das três palavras.
  
          ### `não`
          Exclui determinado termo da pesquisa.
  
          EXEMPLO: (seguro não automóvel)
  
          RESULTADO: o sistema buscará apenas os documentos que contenham a palavra “seguro”, mas 
          excluirá do resultado aqueles que tragam a palavra “automóvel”.
  
          ### `mesmo`
          Localiza termos em um mesmo campo do documento.
  
          EXEMPLO: (FGTS mesmo súmula mesmo civil)
  
          RESULTADO: o sistema buscará os documentos que contenham as três palavras indicadas, em 
          qualquer ordem ou distância, dentro de um mesmo campo.
  
          ### `com`
          Localiza termos em um mesmo parágrafo.
          
          EXEMPLO: recurso com STJ com furto com veículo
  
          RESULTADO: o sistema buscará os documentos que contenham as quatro palavras em qualquer 
          ordem ou distância, dentro do mesmo parágrafo.
  
          ## Operadores de proximidade
          ### `PROX(N)`
          Localiza termos PROXimos, em qualquer ordem. (N) limita a distância entre os termos pesquisados. 
          O segundo termo poderá ser até a enésima palavra antes ou depois do primeiro termo.
  
          EXEMPLO: nega prox2 provimento prox5 recursos
  
          RESULTADO: O sistema buscará os documentos que contenham as três palavras em qualquer ordem, 
          até a distância determinada. No exemplo, serão recuperadas as expressões: “recursos a que se 
          nega provimento” “nega-se provimento ao recurso” “recursos especiais a que se nega provimento”
  
          ### `ADJ(N)`
          Localiza termos ADJacentes, na ordem estabelecida na pesquisa. (N) limita a distância entre
          os termos pesquisados. O segundo termo poderá ser até a enésima palavra após o primeiro
          termo. adj = adj1 (busca os termos conjugados sem qualquer outra palavra entre eles).
  
          EXEMPLO: causa adj3 aumento adj2 pena
  
          RESULTADO: O sistema buscará os documentos que contenham as três palavras, na ordem digitada, 
          até a distância delimitada. Serão resgatadas expressões como: “Causa de aumento de pena” 
          “causas especiais de aumento de pena”
  
          ## Símbolos auxiliares
          ### `$`
          Substitui vários caracteres, podendo vir no início, meio ou fim da palavra. É possível 
          limitar o número máximo de caracteres utilizando valores numéricos.
  
          EXEMPLO 1: constitui$
  
          RESULTADO 1: Constitui; Constituir; Constituído; Constituição.
  
          EXEMPLO 2: $classificado
  
          RESULTADO 2: Classificado; Reclassificado; Desclassificado; Não-classificado.
  
          EXEMPLO 3: des$cao
  
          RESULTADO 3: Deserção; Descrição; designação.
  
          EXEMPLO 4: p$3
  
          RESULTADO 4: PG; Para; PAR; Pode; Pena.
  
          ### `?`
          Substitui um único carácter, podendo vir no início, meio ou fim da palavra. Cada 
          interrogação corresponde a um carácter.
  
          EXEMPLO: d?sc?r??
  
          RESULTADO: Deserção; Descrição; designação; descrição.
  
          ### `( )`
          Usado para o operador OU e para agrupar itens da pesquisa. A alteração poderá ser feita 
          manualmente.
  
          EXEMPLO: ((menor ou criança) e infrator) com pena
  
          RESULTADO: o sistema buscará os documentos que contenham as combinações: menor e infrator 
          com pena ou criança e infrator com pena
  
          ### `" "`
          Utilizado para transformar um operador em palavra a ser pesquisada e para localizar expressões 
          exatas.
  
          EXEMPLO: “não” adj previsto “tribunal de origem”
  
          RESULTADO: o sistema buscará documentos que contenham a expressão “não previsto”. O sistema 
          buscará documentos que contenham a expressão “tribunal de origem”."""),
          min_length=1,
          examples=[
              "supermercado e furto e veículo",
              "(carro ou automóvel ou veículo)",
              "(seguro não automóvel)",
              "(FGTS mesmo súmula mesmo civil)",
              "recurso com STJ com furto com veículo",
              "nega prox2 provimento prox5 recursos",
              "causa adj3 aumento adj2 pena",
              "$classificado",
              "d?sc?r??",
              "((menor ou criança) e infrator) com pena",
              "“não” adj previsto “tribunal de origem”",
          ],
      )

• src/brlaw_mcp_server/presentation/mcp.py:341-366 (registration)

  Registration of StjLegalPrecedentsRequest in the _TOOLS_AND_MODELS list, pairing it with StjLegalPrecedent domain model and creating a Tool entry with name=StjLegalPrecedentsRequest.__name__.

  _TOOLS_AND_MODELS: Final[
      list[
          tuple[
              Tool,
              type[BaseLegalPrecedent],
              type[StjLegalPrecedentsRequest]
              | type[TstLegalPrecedentsRequest]
              | type[StfLegalPrecedentsRequest],
          ]
      ]
  ] = [
      (
          Tool(
              name=request_model.__name__,
              description=request_model.__doc__,
              inputSchema=request_model.model_json_schema(),
          ),
          domain_model,
          request_model,
      )
      for request_model, domain_model in [
          (StjLegalPrecedentsRequest, StjLegalPrecedent),
          (TstLegalPrecedentsRequest, TstLegalPrecedent),
          (StfLegalPrecedentsRequest, StfLegalPrecedent),
      ]
  ]

• src/brlaw_mcp_server/presentation/mcp.py:374-413 (handler)

  The call_tool handler function that receives a tool call, looks up StjLegalPrecedentsRequest in _TOOLS_AND_MODELS, instantiates it from arguments, and calls StjLegalPrecedent.research() to execute the tool logic.

  async def call_tool(
      name: str,
      arguments: dict[str, "Any"],  # pyright: ignore[reportExplicitAny]
  ) -> list[TextContent]:
      """Handles a tool call from a MCP client."""
      _LOGGER.info(
          "Received tool call",
          extra={"arguments": arguments, "tool_name": name},
      )
  
      for tool, domain_model, request_model in _TOOLS_AND_MODELS:
          if tool.name == name:
              request = request_model(**arguments)  # pyright: ignore[reportAny]
              method = domain_model.research
              break
      else:
          raise ValueError(f"Tool {name} not found")
  
      async with (
          browser_factory(headless=True) as browser,
          await browser.new_page() as page,
      ):
          try:
              precedents = await method(
                  page,
                  summary_search_prompt=request.summary,
                  desired_page=request.page,
              )
          except Exception:
              _LOGGER.exception("Error calling tool", extra={"tool_name": name})
              raise
  
      return (
          [
              TextContent(type="text", text=precedent.model_dump_json())
              for precedent in precedents
          ]
          if precedents
          else [TextContent(type="text", text="Nenhum resultado encontrado")]
      )

• src/brlaw_mcp_server/domain/stj.py:14-85 (helper)

  StjLegalPrecedent domain model with the research() method that scrapes STJ's website (scon.stj.jus.br) — the actual execution logic for the STJ tool.

  class StjLegalPrecedent(BaseLegalPrecedent):
      """Model for a legal precedent from the Superior Tribunal de Justiça (STJ)."""
  
      @staticmethod
      async def _get_raw_summary_locators(browser: "Page") -> "list[Locator]":
          """Get the locators of the raw summaries shown on the current page."""
          raw_summary_locators = await browser.locator(
              "textarea[id^=textSemformatacao]"
          ).all()
  
          _LOGGER.debug(
              "Found %d raw summary locators on the current page",
              len(raw_summary_locators),
          )
  
          if len(raw_summary_locators) == 0:
              try:
                  error_message = await browser.locator("div.erroMensagem").text_content()
              except TimeoutError as e:
                  raise RuntimeError(
                      "Unexpected behavior from the requested service"
                  ) from e
  
              if (
                  error_message is not None
                  and "Nenhum documento encontrado!" in error_message
              ):
                  _LOGGER.info(
                      "No legal precedents found",
                  )
                  return []
  
          return raw_summary_locators
  
      @override
      @classmethod
      async def research(
          cls, browser: "Page", *, summary_search_prompt: str, desired_page: int = 1
      ) -> "list[Self]":
          _LOGGER.info(
              "Starting research for legal precedents authored by the STJ with the summary search prompt %s",
              repr(summary_search_prompt),
          )
  
          await browser.goto("https://scon.stj.jus.br/SCON/")
  
          await browser.locator("#idMostrarPesquisaAvancada").click()
  
          summary_input_locator = browser.locator("#ementa")
          await summary_input_locator.fill(summary_search_prompt)
          await summary_input_locator.press("Enter")
  
          await browser.locator("#corpopaginajurisprudencia").wait_for(state="visible")
  
          raw_summary_locators = await cls._get_raw_summary_locators(browser)
  
          current_page = 1
          while current_page != desired_page:
              next_page_anchor_locators = await browser.locator(
                  "a.iconeProximaPagina"
              ).all()
              await next_page_anchor_locators[0].click()
              await browser.wait_for_event("load")  # pyright: ignore[reportUnknownMemberType]
              raw_summary_locators = await cls._get_raw_summary_locators(browser)
  
              current_page += 1
  
          return [
              cls(summary=text)
              for locator in raw_summary_locators
              if (text := await locator.text_content()) is not None
          ]