Metadata-Version: 2.4
Name: lymcp
Version: 0.4.0
Summary: Model Context Protocol server for Taiwan Legislative Yuan API v2
Project-URL: Homepage, https://github.com/narumiruna/ly-mcp
Project-URL: Repository, https://github.com/narumiruna/ly-mcp
Project-URL: Issues, https://github.com/narumiruna/ly-mcp/issues
Author-email: narumi <toucans-cutouts0f@icloud.com>
License: MIT License
        
        Copyright (c) 2022 なるみ
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: api,legislative-yuan,mcp,model-context-protocol,taiwan
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: mcp[cli]>=1.27.1
Requires-Dist: typer>=0.25.1
Description-Content-Type: text/markdown

# 🏛️ ly-mcp

[![PyPI version](https://img.shields.io/pypi/v/lymcp)](https://pypi.org/project/lymcp/)
[![Python](https://img.shields.io/pypi/pyversions/lymcp)](https://pypi.org/project/lymcp/)
[![CI](https://github.com/narumiruna/ly-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/narumiruna/ly-mcp/actions/workflows/ci.yml)
[![Docker](https://github.com/narumiruna/ly-mcp/actions/workflows/docker.yml/badge.svg)](https://github.com/narumiruna/ly-mcp/actions/workflows/docker.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

ly-mcp 是一個串接台灣立法院 API v2 的 Model Context Protocol (MCP) 伺服器，提供議案、委員會、公報、會議紀錄與相關文件等資料查詢能力。

## ✨ 功能

此 MCP 伺服器提供 9 大類、共 39 個工具：

### 📊 統計

- **get_stat**：取得立法院 API 的統計與概覽資訊。

### 📄 議案

- **list_bills**：列出議案，可依屆期、會期、類別、提案人等條件篩選。
- **get_bill**：取得特定議案的完整資訊，回傳完整 JSON。
- **get_bill_related_bills**：查詢相關議案與其關聯。
- **get_bill_meets**：取得議案在各會議中的審議紀錄。
- **get_bill_doc_html**：取得特定議案的 HTML 文件內容。

### 🏢 委員會

- **list_committees**：列出立法院委員會，可搭配篩選條件。
- **get_committee**：取得特定委員會的詳細資訊。
- **get_committee_meets**：取得委員會會議紀錄與議事內容。

### 📰 公報

- **list_gazettes**：列出立法院公報，可依卷期與公報編號篩選。
- **get_gazette**：取得特定公報的詳細資訊。
- **get_gazette_agendas**：取得特定公報中的議程或目錄內容。
- **list_gazette_agendas**：列出公報目錄，可依屆期、會議日期等條件篩選。
- **get_gazette_agenda**：取得特定公報目錄項目的詳細資訊。

### 🎙️ 質詢

- **list_interpellations**：列出質詢資料，可依委員、屆期、會期與會議代碼篩選。
- **get_interpellation**：取得特定質詢的詳細資訊。
- **get_legislator_interpellations**：取得特定立法委員作為質詢委員的質詢資料。

### 🎥 IVOD（網路電視）

- **list_ivods**：列出 IVOD 影片，可依屆期、會期、委員會、委員與影片類型篩選。
- **get_ivod**：取得特定 IVOD 影片的詳細資訊，包含影片網址、逐字稿與公報內容。
- **get_meet_ivods**：取得特定會議相關的 IVOD 影片。

### ⚖️ 法律

- **list_laws**：列出法律，可依法律編號、類別（母法或子法）、母法編號、狀態與主管機關篩選。
- **get_law**：取得特定法律的完整資訊，包含基本資料、法條與版本資訊。
- **get_law_progress**：取得特定法律的未議決進度列表。
- **get_law_bills**：取得特定法律相關的議案，可搭配篩選條件。
- **get_law_versions**：取得特定法律的歷史版本紀錄，包含修正內容、提案人與進度。
- **list_law_versions**：跨法律列出法律版本，可依法律編號、版本編號、日期、動作、進度與現行版本狀態篩選。
- **get_law_version**：依版本 ID 取得特定法律版本的詳細資訊。
- **get_law_version_contents**：取得特定法律版本包含的法條內容。
- **list_law_contents**：列出法條內容，可依法律編號、版本 ID、條號、現行版狀態與版本追蹤篩選。
- **get_law_content**：依法條內容 ID 取得特定法條的詳細資訊。

### 🗓️ 會議

- **list_meets**：列出立法院會議，可依屆期、會期、會議種類、出席委員、日期、委員會代號與會議編號篩選。
- **get_meet**：依會議 ID 或代碼取得特定會議的詳細資訊。
- **get_meet_ivods**：取得特定會議相關的 IVOD 影片，可搭配篩選條件。
- **get_meet_bills**：取得特定會議討論的議案，可依議案條件篩選。
- **get_meet_interpellations**：取得特定會議中的質詢資料，可搭配篩選條件。

### 👤 立法委員

- **list_legislators**：列出立法委員，可依屆期、黨籍、選區、委員 ID 與姓名篩選。
- **get_legislator**：依屆期與姓名取得特定立法委員的詳細資訊。
- **get_legislator_propose_bills**：取得特定立法委員作為提案人的議案，可依議案條件篩選。
- **get_legislator_cosign_bills**：取得特定立法委員作為連署人的議案，可依議案條件篩選。
- **get_legislator_meets**：取得特定立法委員出席的會議，可依會議條件篩選。
- **get_legislator_interpellations**：取得特定立法委員的質詢資料，可搭配篩選條件。

## 🔗 API 來源

此 MCP 伺服器使用 [立法院 API v2](https://ly.govapi.tw/v2) 作為資料來源，提供台灣立法院議案與議事資料。

## 📦 工具回應格式

MCP 工具呼叫成功時，會回傳立法院 API 的原始 JSON payload。呼叫失敗時，會回傳可由程式判讀的 JSON 錯誤封包：

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

目前的錯誤 `type` 包含 `http_status`、`timeout`、`network_error`、`invalid_json` 與 `unexpected_error`。

## 🚀 安裝與使用

### ⚡ 快速開始

使用 `uvx` 安裝並執行伺服器：

```bash
uvx lymcp@latest
```

### 🧩 MCP Client 設定

將此伺服器加入你的 MCP client 設定，例如 Claude Desktop。

#### PyPI

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

#### GitHub

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

#### 本機開發

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

#### Docker

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

### 💻 Terminal CLI

套件也提供 `ly` 指令，讓 agents 或 shell workflow 可以直接從 terminal 查詢立法院 API。CLI 預設輸出 pretty JSON，失敗時會輸出和 MCP tools 相同的 JSON error envelope 並回傳非 0 exit code。

```bash
ly --help
ly stat
ly bills list --term 11 --bill-type 法律案 --limit 5
ly bills get 202110213410000
ly laws versions 09200015 --limit 5
ly meets bills 院會-11-2-3 --term 11 --limit 5
ly legislators propose-bills 11 韓國瑜 --limit 5
```

給 agents 使用時，建議用資料領域選 command group：

- `ly bills ...` 查議案、關聯議案、審議會議與議案本文 HTML。
- `ly laws ...`、`ly law-versions ...`、`ly law-contents ...` 查法律、修法版本與法條內容。
- `ly meets ...` 查會議、會議中的議案、質詢與 IVOD。
- `ly legislators ...` 查立法委員、提案、連署、出席會議與質詢。
- `ly gazettes ...`、`ly gazette-agendas ...` 查公報與公報目錄。
- `ly committees ...`、`ly interpellations ...`、`ly ivods ...` 查委員會、質詢與網路電視資料。

常用輸出選項：

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

## 💬 範例提示

連上 MCP 伺服器後，可以向 LLM 提出這類問題：

- 「列出第11屆的所有法律提案」
- 「查詢立法委員王美花的提案紀錄」
- 「以今天的台北日期為準，最近已發生的院會討論了哪些議案？」
- 「下一場已排程的院會是什麼時候？」
- 「查詢勞動基準法的修法歷程」
- 「第11屆第1會期有哪些委員會會議？」

處理和日期有關的問題時，請區分：

- `latest known`：使用上游預設排序，包含未來已排程的紀錄。
- `latest occurred`：只考慮相關日期在參考日期當天或之前的紀錄。
- `next scheduled`：只考慮相關日期晚於參考日期的紀錄。

伺服器也提供常見工作流程用的 MCP prompts：
`latest_plenary_meeting_bills`、`law_amendment_history`、
`legislator_proposal_record`、`legislator_interpellations` 與
`committee_meeting_lookup`。可閱讀 `lymcp://query-semantics` 與
`lymcp://workflow-reference`，取得日期語意、篩選條件、ID 欄位與工作流程步驟的精簡指引。

## 🛠️ 開發

### ✅ 需求

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) 套件管理器
- [just](https://github.com/casey/just) 命令執行器

### ⚙️ 設定

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

### 🤖 使用 Codex CLI

此 repository 已包含供本機 Codex CLI 開發使用的 `.codex/config.toml`。從 repository root 啟動 Codex CLI 時，可透過 `uv run lymcp` 使用已設定的 `lymcp` MCP server。

### 🔍 執行 MCP Inspector

```bash
just dev
```

### 🧪 執行測試

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

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

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

預設 pytest 設定會排除標記為 `live` 的測試，因此 CI 與一般本機執行會使用 `tests/data` 中的 fixture-backed samples。只有在上游 API 回應形狀改變時，才應有意識地更新這些 JSON samples。

### 🧹 程式碼品質

```bash
# 執行 linter
just lint

# 執行 type checker
just type
```

## 📜 授權

MIT
