MCP Server Template

Um modelo para criar servidores MCP usando Python.

GitHub
6
Experimente este MCPPatrocinado

Documentação

🏛️ ly-mcp

PyPI version Python CI Docker License: MIT

ly-mcp é um servidor Model Context Protocol (MCP) que integra a API v2 do Legislativo de Taiwan (立法院), oferecendo consultas a dados como proposições legislativas, comissões, diários oficiais, atas de reuniões e documentos relacionados.

✨ Funcionalidades

Este servidor MCP oferece 10 categorias, totalizando 42 ferramentas:

📊 Estatísticas

  • get_stat: Obtém estatísticas e informações gerais da API do Legislativo.

📄 Proposições Legislativas

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

🏢 Comissões

  • list_committees: Lista comissões do Legislativo, 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údos de deliberação de comissões.

📰 Diários Oficiais

  • list_gazettes: Lista diários oficiais do Legislativo, 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 agendas ou sumários de um diário oficial específico, com filtros adicionais por número do diário, volume, edição, caderno, entre outros.
  • list_gazette_agendas: Lista sumários de diários oficiais, com filtros por volume, edição, caderno, legislatura e data da reunião.
  • get_gazette_agenda: Obtém informações detalhadas de um item específico do sumário de um diário oficial.

🎙️ Interpelações

  • list_interpellations: Lista 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 interpelações de um parlamentar específico na qualidade de interpelante.

🎥 IVOD (TV Online)

  • list_ivods: Lista vídeos do 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 específico do IVOD, incluindo URL do vídeo, transcrição e conteúdo do diário oficial.
  • get_meet_ivods: Obtém vídeos do 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ões.
  • get_law_progress: Obtém a lista de progresso não deliberado de uma lei específica.
  • get_law_bills: Obtém proposições legislativas relacionadas a uma lei específica, com opção de filtros adicionais.
  • 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 Legislativo, 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 pelo ID ou código da reunião.
  • get_meet_ivods: Obtém vídeos do IVOD relacionados a uma reunião específica, com opção de filtros adicionais.
  • get_meet_bills: Obtém proposições legislativas discutidas em uma reunião específica, com filtros por condições da proposição.
  • get_meet_interpellations: Obtém interpelações de uma reunião específica, com opção de filtros adicionais.

👤 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 proposições legislativas de um parlamentar específico na qualidade de proponente, com filtros por condições da proposição.
  • get_legislator_cosign_bills: Obtém proposições legislativas de um parlamentar específico na qualidade de coautor, com filtros por condições da proposição.
  • get_legislator_meets: Obtém reuniões com a presença de um parlamentar específico, com filtros por condições da reunião.
  • get_legislator_interpellations: Obtém interpelações de um parlamentar específico, com opção de filtros adicionais.

🗳️ 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 utiliza a API v2 do Legislativo como fonte de dados, fornecendo proposições legislativas e dados de deliberação do Legislativo de Taiwan.

📦 Formato de Resposta das Ferramentas

Quando uma chamada de ferramenta MCP é bem-sucedida, o payload JSON original da API do Legislativo é 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"
  }
}

Os códigos de erro type atuais incluem 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 agentes ou fluxos de trabalho via shell consultem a API do Legislativo diretamente do terminal. O CLI produz JSON formatado por padrão e, em caso de falha, gera o mesmo envelope de erro JSON das ferramentas MCP, retornando um código de saída diferente de zero.

Para permitir que agentes usem a skill ly dentro 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 agentes, recomenda-se selecionar grupos 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údos de artigos.
  • ly meets ... para consultar reuniões, proposições em reuniões, interpelações e IVOD.
  • ly legislators ... para consultar parlamentares, proposições, coautorias, presença em reuniões e interpelações.
  • ly gazettes ..., ly gazette-agendas ... para consultar diários oficiais e sumários de diários.
  • ly committees ..., ly interpellations ..., ly ivods ... para consultar comissões, interpelações e dados de TV online.
  • ly votes ... para consultar listas de votações, detalhes de votações e reuniões associadas.

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 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 na reunião plenária mais recente?"
  • "Quando será a próxima reunião plenária agendada?"
  • "Consulte o histórico de alterações da Lei de Normas do Trabalho"
  • "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 questões relacionadas a datas, distinga:

  • latest known: usa a ordenação padrão da fonte, 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 Codex CLI

Este repositório já inclui .codex/config.toml para desenvolvimento local com Codex CLI. Ao iniciar o Codex CLI a partir da raiz do repositório, você pode usar o servidor MCP lymcp configurado via 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, execuções de CI e locais regulares usam amostras baseadas em fixtures de tests/data. Essas amostras JSON só devem ser atualizadas conscientemente quando a forma das respostas da API upstream mudar.

🧹 Qualidade do Código

# 執行 linter
just lint

# 執行 type checker
just type

📜 Licença

MIT