Brazilian Law Research MCP Server

Instructions

Implementation Reference

• src/brlaw_mcp_server/domain/stj.py:49-85 (handler)

  The overridden classmethod in StjLegalPrecedent that implements the core logic for searching STJ legal precedents: navigates to STJ site, performs advanced search by ementa (summary), paginates to desired page, and extracts raw summaries using Playwright.
  @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 ]
• src/brlaw_mcp_server/presentation/mcp.py:40-193 (schema)

  Pydantic model defining the input parameters for the tool: 'page' (from base) and 'summary' search prompt for STJ ementa, with detailed description 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)

  List defining the tools, including STJ: creates Tool instance from schema class, associates with StjLegalPrecedent domain model for handling.
  _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-414 (handler)

  Generic MCP tool handler that parses arguments into request model, creates browser page, calls the domain model's research method, and formats results as TextContent.
  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")] )