MCP Server Template

Una plantilla para crear servidores MCP usando Python.

GitHub
6
Prueba este MCPPatrocinado

Documentación

🏛️ ly-mcp

PyPI version Python CI Docker License: MIT

ly-mcp es un servidor de Model Context Protocol (MCP) que se conecta a la API v2 del Yuan Legislativo de Taiwán, y proporciona 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 estadísticas e información general de la API del Yuan Legislativo.

📄 Propuestas

  • list_bills: Lista propuestas, con filtros por período, sesión, categoría, proponente, etc.
  • get_bill: Obtiene 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 entera y código de comité.
  • get_committee: Obtiene información detallada de un comité específico.
  • get_committee_meets: Obtiene las actas de reuniones y el contenido de las deliberaciones de un comité.

📰 Gacetas

  • list_gazettes: Lista las gacetas del Yuan Legislativo, con filtros por volumen y número de gaceta.
  • get_gazette: Obtiene información detallada de una gaceta específica.
  • get_gazette_agendas: Obtiene el contenido de la agenda o el í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 y fecha de reunión, etc.
  • get_gazette_agenda: Obtiene 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, sesión y código de reunión.
  • get_interpellation: Obtiene 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 de IVOD, con filtros por período, sesión, comité, legislador y tipo de video.
  • get_ivod: Obtiene información detallada de un video de IVOD específico, incluyendo la URL del video, la transcripción y el contenido de la gaceta.
  • get_meet_ivods: Obtiene los videos de 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 reglamento), número de ley principal, estado y autoridad supervisora.
  • get_law: Obtiene 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 no resuelto de una ley específica.
  • get_law_bills: Obtiene las propuestas relacionadas con una ley específica, con filtros opcionales.
  • get_law_versions: Obtiene el historial de versiones de una ley específica, incluyendo contenido de modificaciones, proponentes y progreso.
  • list_law_versions: Lista versiones de leyes de forma transversal, 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 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 el contenido 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 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, sesión, tipo de reunión, legisladores presentes, fecha, código de comité y número de reunión.
  • get_meet: Obtiene información detallada de una reunión específica por ID o código de reunión.
  • get_meet_ivods: Obtiene los videos de IVOD relacionados con una reunión específica, con filtros opcionales.
  • 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 en una reunión específica, con filtros opcionales.

👤 Legisladores

  • list_legislators: Lista legisladores, con filtros por período, afiliación partidista, distrito electoral, ID de legislador y nombre.
  • get_legislator: Obtiene información detallada de un legislador específico por período 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 copatrocinador, 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 filtros opcionales.

🗳️ Votaciones

  • list_votes: Lista registros de votaciones, con filtros por período, 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 parlamentarios de Taiwán.

📦 Formato de respuesta de las herramientas

Cuando una herramienta MCP se ejecuta correctamente, devuelve el payload JSON original de la API del Yuan Legislativo. Cuando falla, 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

Usa uvx para instalar y ejecutar el servidor:

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 agentes o flujos de trabajo de shell consultar la API del Yuan Legislativo directamente desde la terminal. El CLI genera JSON legible por defecto, y en caso de error genera el mismo sobre de error JSON que las herramientas MCP y devuelve un código de salida distinto de cero.

Para que un agente use la habilidad ly dentro del repositorio, puedes instalar:

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 agentes, se recomienda elegir el grupo de comandos según el dominio de datos:

  • ly bills ... para consultar propuestas, propuestas relacionadas, reuniones de deliberación y el HTML del texto de la propuesta.
  • ly laws ..., ly law-versions ..., ly law-contents ... para consultar leyes, versiones de modificaciones y contenido de artículos.
  • ly meets ... para consultar reuniones, propuestas en reuniones, interpelaciones e IVOD.
  • ly legislators ... para consultar legisladores, propuestas, copatrocinios, asistencia a reuniones e interpelaciones.
  • ly gazettes ..., ly gazette-agendas ... para consultar gacetas e índices de gacetas.
  • ly committees ..., ly interpellations ..., ly ivods ... para consultar comités, interpelaciones y datos de televisión por internet.
  • ly votes ... para consultar 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 consultas

Después de conectarte al servidor MCP, puedes plantear preguntas como estas al LLM:

  • «Enumera todas las propuestas legislativas 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 recientes?»
  • «¿Cuándo es la próxima sesión plenaria programada?»
  • «Consulta el historial de modificaciones de la Ley de Normas Laborales»
  • «¿Qué reuniones de comités hubo en el 1.er período de la 11.ª legislatura?»
  • «¿En qué votaciones participó Huang Kuo-chang en la 11.ª legislatura y cuál fue su postura en cada una?»

Al manejar preguntas relacionadas con fechas, distingue entre:

  • latest known: usa la ordenación predeterminada de la fuente, incluyendo registros futuros programados.
  • latest occurred: solo considera registros cuya fecha relevante sea igual o anterior a la fecha de referencia.
  • next scheduled: solo considera registros cuya fecha relevante sea posterior 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 guías concisas sobre semántica de fechas, condiciones de filtro, campos de ID y pasos de flujo de trabajo.

🛠️ Desarrollo

✅ Requisitos

  • Python 3.12+
  • Gestor de paquetes uv
  • Ejecutor de comandos just

⚙️ Configuración

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

🤖 Uso con Codex CLI

Este repositorio ya incluye .codex/config.toml para el desarrollo local con Codex CLI. 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 la ejecución local habitual usan muestras respaldadas por fixtures en tests/data. Solo debes actualizar estas muestras JSON de forma consciente cuando cambie la forma de las respuestas de la API de origen.

🧹 Calidad del código

# 執行 linter
just lint

# 執行 type checker
just type

📜 Licencia

MIT