Legislative Yuan API

🏛️ ly-mcp

ly-mcp é um servidor Model Context Protocol (MCP) que integra a API v2 do Legislative Yuan de Taiwan, oferecendo capacidades de consulta de dados como proposições, comissões, diários oficiais, atas de reuniões e documentos relacionados.

✨ Recursos

Este servidor MCP fornece 10 categorias principais, com 42 ferramentas no total:

📊 Estatísticas

• get_stat: Obtém informações estatísticas e de visão geral da API do Legislative Yuan.

📄 Proposições

• list_bills: Lista proposições, com filtros por legislatura, sessão, categoria, proponente, etc.
• get_bill: Obtém informações completas de uma proposição específica, retornando JSON completo.
• get_bill_related_bills: Consulta proposições relacionadas e suas associações.
• get_bill_meets: Obtém os registros de deliberação de uma proposição nas reuniões, com filtros por reunião, parlamentares presentes, comissão e proposições ou leis relacionadas, além de permitir especificar os campos de saída.
• get_bill_doc_html: Obtém o conteúdo HTML do documento de uma proposição específica.

🏢 Comissões

• list_committees: Lista as comissões do Legislative Yuan, com filtros por código de categoria inteiro e código da comissão.
• get_committee: Obtém informações detalhadas de uma comissão específica.
• get_committee_meets: Obtém atas de reuniões e conteúdo de deliberações da comissão.

📰 Diários Oficiais

• list_gazettes: Lista os diários oficiais do Legislative Yuan, com filtros por volume e número do diário.
• get_gazette: Obtém informações detalhadas de um diário oficial específico.
• get_gazette_agendas: Obtém o conteúdo de pauta ou índice de um diário oficial específico, com filtros adicionais por número do diário, volume, edição, fascículo, etc.
• list_gazette_agendas: Lista os índices de diários oficiais, com filtros por volume, edição, fascículo, legislatura e data da reunião.
• get_gazette_agenda: Obtém informações detalhadas de um item específico do índice de um diário oficial.

🎙️ Interpelações

• list_interpellations: Lista dados de interpelações, com filtros por parlamentar, legislatura, sessão e código da reunião.
• get_interpellation: Obtém informações detalhadas de uma interpelação específica.
• get_legislator_interpellations: Obtém as interpelações de um parlamentar específico como interpelante.

🎥 IVOD (TV na Internet)

• list_ivods: Lista vídeos IVOD, com filtros por legislatura, sessão, comissão, parlamentar e tipo de vídeo.
• get_ivod: Obtém informações detalhadas de um vídeo IVOD específico, incluindo URL do vídeo, transcrição e conteúdo do diário oficial.
• get_meet_ivods: Obtém os vídeos IVOD relacionados a uma reunião específica.

⚖️ Leis

• list_laws: Lista leis, com filtros por número da lei, categoria (lei principal ou subordinada), número da lei principal, status e órgão responsável.
• get_law: Obtém informações completas de uma lei específica, incluindo dados básicos, artigos e informações de versão.
• get_law_progress: Obtém a lista de progresso não deliberado de uma lei específica.
• get_law_bills: Obtém as proposições relacionadas a uma lei específica, com filtros opcionais.
• get_law_versions: Obtém o histórico de versões de uma lei específica, incluindo conteúdo das alterações, proponentes e progresso.
• list_law_versions: Lista versões de leis em diferentes leis, com filtros por número da lei, número da versão, data, ação, progresso e status de versão vigente.
• get_law_version: Obtém informações detalhadas de uma versão específica de lei pelo ID da versão.
• get_law_version_contents: Obtém o conteúdo dos artigos incluídos em uma versão específica de lei.
• list_law_contents: Lista conteúdos de artigos, com filtros por número da lei, ID da versão, número do artigo, status de versão vigente e rastreamento de versão.
• get_law_content: Obtém informações detalhadas de um artigo específico pelo ID do conteúdo do artigo.

🗓️ Reuniões

• list_meets: Lista reuniões do Legislative Yuan, com filtros por legislatura, sessão, tipo de reunião, parlamentares presentes, data, código da comissão e número da reunião.
• get_meet: Obtém informações detalhadas de uma reunião específica por ID ou código da reunião.
• get_meet_ivods: Obtém os vídeos IVOD relacionados a uma reunião específica, com filtros opcionais.
• get_meet_bills: Obtém as proposições discutidas em uma reunião específica, com filtros por condições de proposição.
• get_meet_interpellations: Obtém os dados de interpelações de uma reunião específica, com filtros opcionais.

👤 Parlamentares

• list_legislators: Lista parlamentares, com filtros por legislatura, filiação partidária, distrito eleitoral, ID do parlamentar e nome.
• get_legislator: Obtém informações detalhadas de um parlamentar específico por legislatura e nome.
• get_legislator_propose_bills: Obtém as proposições de um parlamentar específico como proponente, com filtros por condições de proposição.
• get_legislator_cosign_bills: Obtém as proposições de um parlamentar específico como co-signatário, com filtros por condições de proposição.
• get_legislator_meets: Obtém as reuniões em que um parlamentar específico esteve presente, com filtros por condições de reunião.
• get_legislator_interpellations: Obtém os dados de interpelações de um parlamentar específico, com filtros opcionais.

🗳️ Votações

• list_votes: Lista registros de votação, com filtros por legislatura, reunião, tipo de votação, posição de voto do parlamentar e documento do diário oficial.
• get_vote: Obtém o conteúdo completo de uma votação pelo código da votação.
• get_vote_meets: Obtém as reuniões às quais uma votação específica pertence, com filtros por reunião, comissão e proposições relacionadas.

🔗 Fonte da API

Este servidor MCP usa a API v2 do Legislative Yuan como fonte de dados, fornecendo dados de proposições e procedimentos do Legislative Yuan de Taiwan.

📦 Formato de resposta das ferramentas

Quando uma chamada de ferramenta MCP é bem-sucedida, o payload JSON bruto da API do Legislative Yuan é retornado. Quando a chamada falha, um envelope de erro JSON legível por programa é retornado:

{
  "ok": false,
  "error": {
    "type": "http_status",
    "message": "Upstream API returned HTTP 404 for https://ly.govapi.tw/v2/bills/invalid_bill_number",
    "url": "https://ly.govapi.tw/v2/bills/invalid_bill_number",
    "status_code": 404,
    "response_excerpt": "not found"
  }
}

O erro atual type contém http_status, timeout, network_error, invalid_json e unexpected_error.

🚀 Instalação e uso

⚡ Início rápido

Use uvx para instalar e executar o servidor:

uvx lymcp@latest

🧩 Configuração do cliente MCP

Adicione este servidor à configuração do seu cliente MCP, por exemplo, Claude Desktop.

PyPI

{
  "mcpServers": {
    "lymcp": {
      "command": "uvx",
      "args": ["lymcp@latest"]
    }
  }
}

GitHub

{
  "mcpServers": {
    "lymcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/narumiruna/ly-mcp",
        "lymcp"
      ]
    }
  }
}

Desenvolvimento local

{
  "mcpServers": {
    "lymcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/ly-mcp",
        "lymcp"
      ]
    }
  }
}

Docker

{
  "mcpServers": {
    "lymcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "narumi/ly-mcp:latest"
      ]
    }
  }
}

💻 CLI de terminal

O pacote também fornece o comando ly, permitindo que agents ou workflows de shell consultem a API do Legislative Yuan diretamente do terminal. O CLI gera JSON formatado por padrão e, em caso de falha, gera o mesmo envelope de erro JSON das ferramentas MCP e retorna um código de saída diferente de 0.

Para permitir que um agent use a skill ly do repositório, instale:

npx skills add /narumiruna/ly-mcp

ly --help
ly stat
ly bills list --term 11 --bill-type 法律案 --limit 5
ly bills get 202110213410000
ly bills meets 202110213410000 --meeting-code 院會-11-2-6 --fields 會議代碼,日期
ly gazettes agendas 1137701 --gazette-number 1137701 --issue 77
ly laws versions 09200015 --limit 5
ly meets bills 院會-11-2-3 --term 11 --limit 5
ly legislators propose-bills 11 韓國瑜 --limit 5
ly votes list --term 11 --voting-member 黃國昌 --limit 5
ly votes get 1141921_00002_591
ly votes meets 1141921_00002_591 --term 11

Ao usar com agents, recomenda-se selecionar o grupo de comandos por domínio de dados:

• ly bills ... para consultar proposições, proposições relacionadas, reuniões de deliberação e HTML do texto das proposições.
• ly laws ..., ly law-versions ..., ly law-contents ... para consultar leis, versões de alteração e conteúdo de artigos.
• ly meets ... para consultar reuniões, proposições em reuniões, interpelações e IVOD.
• ly legislators ... para consultar parlamentares, proposições, coassinaturas, reuniões comparecidas e interpelações.
• ly gazettes ..., ly gazette-agendas ... para consultar diários oficiais e índices de diários oficiais.
• ly committees ..., ly interpellations ..., ly ivods ... para consultar comissões, interpelações e dados de TV na internet.
• ly votes ... para consultar listas de votações, detalhes de votações e reuniões correspondentes.

Opções de saída comuns:

# 單行 JSON，方便 pipe 給其他工具
ly --compact bills list --term 11 --limit 1

# 將成功結果寫入檔案
ly --output bills.json bills list --term 11 --limit 20

# 傳遞上游 output_fields
ly bills list --term 11 --fields 議案編號,案由,提案日期

💬 Exemplos de prompts

Após conectar-se ao servidor MCP, você pode fazer perguntas como estas ao LLM:

• "Liste todas as proposições legislativas da 11ª legislatura"
• "Consulte o histórico de proposições da parlamentar Wang Mei-hua"
• "Com base na data de hoje em Taipei, quais proposições foram discutidas nas sessões plenárias mais recentes já ocorridas?"
• "Quando será a próxima sessão plenária agendada?"
• "Consulte o histórico de alterações da Lei de Normas Trabalhistas"
• "Quais reuniões de comissão ocorreram na 1ª sessão da 11ª legislatura?"
• "Em quais votações Huang Kuo-chang participou na 11ª legislatura e qual foi sua posição em cada uma?"

Ao lidar com perguntas relacionadas a datas, distinga:

• latest known: usa a ordenação padrão upstream, incluindo registros futuros agendados.
• latest occurred: considera apenas registros cujas datas relevantes sejam iguais ou anteriores à data de referência.
• next scheduled: considera apenas registros cujas datas relevantes sejam posteriores à data de referência.

O servidor também fornece prompts MCP para fluxos de trabalho comuns: latest_plenary_meeting_bills, law_amendment_history, legislator_proposal_record, legislator_interpellations, committee_meeting_lookup e legislator_vote_record. Consulte lymcp://query-semantics e lymcp://workflow-reference para obter orientações concisas sobre semântica de datas, filtros, campos de ID e etapas de fluxo de trabalho.

🛠️ Desenvolvimento

✅ Requisitos

• Python 3.12+
• Gerenciador de pacotes uv
• Executor de comandos just

⚙️ Configuração

git clone https://github.com/narumiruna/ly-mcp
cd ly-mcp
uv sync

🤖 Usando o Codex CLI

Este repositório já inclui .codex/config.toml para desenvolvimento com o Codex CLI local. Ao iniciar o Codex CLI a partir da raiz do repositório, você pode usar o servidor MCP lymcp configurado por meio de uv run lymcp.

🔍 Executando o MCP Inspector

just dev

🧪 Executando testes

# 執行預設離線測試套件並產生 coverage
just test

# 直接執行預設離線測試套件
uv run pytest -v -s

# 手動執行會呼叫立法院 API 的 live tests
just test-live

A configuração padrão do pytest exclui testes marcados como live, portanto, CI e execuções locais normais usam amostras baseadas em fixtures em tests/data. Essas amostras JSON só devem ser atualizadas deliberadamente quando a forma das respostas da API upstream mudar.

🧹 Qualidade do código

# 執行 linter
just lint

# 執行 type checker
just type

📜 Licença

MIT