Legislative Yuan API

Busca proyectos de ley, documentos y actas de reuniones de la API del Yuan Legislativo de Taiwán.

Documentación

🏛️ ly-mcp

ly-mcp es un servidor de Model Context Protocol (MCP) que se conecta a la API v2 del Yuan Legislativo de Taiwán, y ofrece capacidades de consulta de datos como propuestas, comités, gacetas, actas de reuniones y documentos relacionados.

✨ Funciones

Este servidor MCP ofrece 10 categorías principales, con un total de 42 herramientas:

📊 Estadísticas

get_stat: Obtiene información estadística y de resumen de la API del Yuan Legislativo.

📄 Propuestas

list_bills: Lista propuestas, con filtros por período legislativo, sesión, categoría, proponente, etc.
get_bill: Obtiene la información completa de una propuesta específica, devolviendo el JSON completo.
get_bill_related_bills: Consulta propuestas relacionadas y sus vínculos.
get_bill_meets: Obtiene los registros de deliberación de una propuesta en cada reunión, con filtros por reunión, legisladores presentes, comité y propuestas o leyes relacionadas, y permite especificar los campos de salida.
get_bill_doc_html: Obtiene el contenido HTML del documento de una propuesta específica.

🏢 Comités

list_committees: Lista los comités del Yuan Legislativo, con filtros por código de categoría entero y código de comité.
get_committee: Obtiene la información detallada de un comité específico.
get_committee_meets: Obtiene las actas de reuniones del comité y el contenido de las sesiones.

📰 Gacetas

list_gazettes: Lista las gacetas del Yuan Legislativo, con filtros por volumen y número de gaceta.
get_gazette: Obtiene la información detallada de una gaceta específica.
get_gazette_agendas: Obtiene el contenido de agenda o índice de una gaceta específica, con filtros adicionales por número de gaceta, volumen, número, tomo, etc.
list_gazette_agendas: Lista los índices de gacetas, con filtros por volumen, número, tomo, período legislativo y fecha de reunión.
get_gazette_agenda: Obtiene la información detallada de un elemento específico del índice de una gaceta.

🎙️ Interpelaciones

list_interpellations: Lista datos de interpelaciones, con filtros por legislador, período legislativo, sesión y código de reunión.
get_interpellation: Obtiene la información detallada de una interpelación específica.
get_legislator_interpellations: Obtiene las interpelaciones de un legislador específico como interpelante.

🎥 IVOD (Televisión por Internet)

list_ivods: Lista videos IVOD, con filtros por período legislativo, sesión, comité, legislador y tipo de video.
get_ivod: Obtiene la información detallada de un video IVOD específico, incluyendo la URL del video, la transcripción y el contenido de la gaceta.
get_meet_ivods: Obtiene los videos IVOD relacionados con una reunión específica.

⚖️ Leyes

list_laws: Lista leyes, con filtros por número de ley, categoría (ley principal o ley derivada), número de ley principal, estado y autoridad competente.
get_law: Obtiene la información completa de una ley específica, incluyendo datos básicos, artículos e información de versiones.
get_law_progress: Obtiene la lista de progreso pendiente de deliberación de una ley específica.
get_law_bills: Obtiene las propuestas relacionadas con una ley específica, con opción de filtros.
get_law_versions: Obtiene el historial de versiones de una ley específica, incluyendo contenido de enmiendas, proponentes y progreso.
list_law_versions: Lista versiones de leyes a través de múltiples leyes, con filtros por número de ley, número de versión, fecha, acción, progreso y estado de versión vigente.
get_law_version: Obtiene la información detallada de una versión específica de una ley por ID de versión.
get_law_version_contents: Obtiene el contenido de los artículos incluidos en una versión específica de una ley.
list_law_contents: Lista contenidos de artículos, con filtros por número de ley, ID de versión, número de artículo, estado de versión vigente y seguimiento de versiones.
get_law_content: Obtiene la información detallada de un artículo específico por ID de contenido de artículo.

🗓️ Reuniones

list_meets: Lista reuniones del Yuan Legislativo, con filtros por período legislativo, sesión, tipo de reunión, legisladores presentes, fecha, código de comité y número de reunión.
get_meet: Obtiene la información detallada de una reunión específica por ID o código de reunión.
get_meet_ivods: Obtiene los videos IVOD relacionados con una reunión específica, con opción de filtros.
get_meet_bills: Obtiene las propuestas discutidas en una reunión específica, con filtros por condiciones de propuesta.
get_meet_interpellations: Obtiene los datos de interpelaciones de una reunión específica, con opción de filtros.

👤 Legisladores

list_legislators: Lista legisladores, con filtros por período legislativo, afiliación partidista, distrito electoral, ID de legislador y nombre.
get_legislator: Obtiene la información detallada de un legislador específico por período legislativo y nombre.
get_legislator_propose_bills: Obtiene las propuestas de un legislador específico como proponente, con filtros por condiciones de propuesta.
get_legislator_cosign_bills: Obtiene las propuestas de un legislador específico como cofirmante, con filtros por condiciones de propuesta.
get_legislator_meets: Obtiene las reuniones a las que asistió un legislador específico, con filtros por condiciones de reunión.
get_legislator_interpellations: Obtiene los datos de interpelaciones de un legislador específico, con opción de filtros.

🗳️ Votaciones

list_votes: Lista registros de votaciones, con filtros por período legislativo, reunión, tipo de votación, postura de voto del legislador y documento de gaceta.
get_vote: Obtiene el contenido completo de una votación por código de votación.
get_vote_meets: Obtiene las reuniones a las que pertenece una votación específica, con filtros por reunión, comité y propuestas relacionadas.

🔗 Fuente de la API

Este servidor MCP utiliza la API v2 del Yuan Legislativo como fuente de datos, proporcionando datos de propuestas y procedimientos del Yuan Legislativo de Taiwán.

📦 Formato de respuesta de las herramientas

Cuando una llamada a una herramienta MCP tiene éxito, se devuelve el payload JSON original de la API del Yuan Legislativo. Cuando falla, se devuelve un paquete de error JSON legible por programas:

{
  "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"
  }
}

Los type de error actuales incluyen http_status, timeout, network_error, invalid_json y unexpected_error.

🚀 Instalación y uso

⚡ Inicio rápido

Instala y ejecuta el servidor usando uvx:

uvx lymcp@latest

🧩 Configuración del cliente MCP

Añade este servidor a la configuración de tu cliente MCP, por ejemplo 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"
      ]
    }
  }
}

Desarrollo 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

El paquete también proporciona el comando ly, que permite a los agents o flujos de trabajo de shell consultar la API del Yuan Legislativo directamente desde la terminal. El CLI genera JSON formateado por defecto, y en caso de error genera el mismo envelope de error JSON que las herramientas MCP y devuelve un código de salida distinto de 0.

Si quieres que un agent utilice la skill ly del repositorio, puedes instalarla:

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

Para uso con agents, se recomienda elegir el grupo de comandos según el dominio de datos:

ly bills ... consulta propuestas, propuestas relacionadas, reuniones de deliberación y el HTML del texto de las propuestas.
ly laws ..., ly law-versions ..., ly law-contents ... consultan leyes, versiones de enmiendas y contenido de artículos.
ly meets ... consulta reuniones, propuestas en reuniones, interpelaciones e IVOD.
ly legislators ... consulta legisladores, propuestas, cofirmas, asistencia a reuniones e interpelaciones.
ly gazettes ..., ly gazette-agendas ... consultan gacetas e índices de gacetas.
ly committees ..., ly interpellations ..., ly ivods ... consultan comités, interpelaciones y datos de televisión por internet.
ly votes ... consulta listas de votaciones, detalles de votaciones y reuniones asociadas.

Opciones de salida comunes:

# 單行 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 議案編號,案由,提案日期

💬 Ejemplos de prompts

Una vez conectado al servidor MCP, puedes plantear al LLM preguntas como estas:

«Enumera todas las propuestas de ley de la 11.ª legislatura»
«Consulta el historial de propuestas de la legisladora Wang Mei-hua»
«Según la fecha de hoy en Taipéi, ¿qué propuestas se discutieron en las sesiones plenarias más recientes?»
«¿Cuándo es la próxima sesión plenaria programada?»
«Consulta el historial de enmiendas de la Ley de Normas Laborales»
«¿Qué reuniones de comité hubo en la 1.ª sesión de la 11.ª legislatura?»
«¿En qué votaciones participó Huang Kuo-chang en la 11.ª legislatura y qué postura tomó en cada una?»

Al manejar preguntas relacionadas con fechas, distingue entre:

latest known: utiliza la ordenación predeterminada del proveedor, incluyendo registros futuros programados.
latest occurred: solo considera registros cuyas fechas relevantes sean el día de la fecha de referencia o anteriores.
next scheduled: solo considera registros cuyas fechas relevantes sean posteriores a la fecha de referencia.

El servidor también proporciona prompts MCP para flujos de trabajo comunes: latest_plenary_meeting_bills, law_amendment_history, legislator_proposal_record, legislator_interpellations, committee_meeting_lookup y legislator_vote_record. Puedes consultar lymcp://query-semantics y lymcp://workflow-reference para obtener una guía concisa sobre la semántica de fechas, condiciones de filtrado, campos de ID y pasos de flujos de trabajo.

🛠️ Desarrollo

✅ Requisitos

Python 3.12+
uv gestor de paquetes
just ejecutor de comandos

⚙️ Configuración

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

🤖 Uso de Codex CLI

Este repositorio ya incluye .codex/config.toml para el desarrollo con Codex CLI local. Al iniciar Codex CLI desde la raíz del repositorio, puedes usar el servidor MCP lymcp configurado a través de uv run lymcp.

🔍 Ejecutar MCP Inspector

just dev

🧪 Ejecutar pruebas

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

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

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

La configuración predeterminada de pytest excluye las pruebas marcadas como live, por lo que la CI y las ejecuciones locales normales utilizan las muestras respaldadas por fixtures en tests/data. Solo debes actualizar estas muestras JSON de forma deliberada cuando cambie la forma de las respuestas de la API del proveedor.

🧹 Calidad del código

# 執行 linter
just lint

# 執行 type checker
just type

📜 Licencia

MIT