Metadata-Version: 2.4
Name: mcp-tw-ly
Version: 0.1.0
Summary: MCP Server for Legislative Yuan information in Taiwan — AI-callable tools via Model Context Protocol
Project-URL: Homepage, https://github.com/asgard-ai-platform/mcp-tw-ly
Project-URL: Repository, https://github.com/asgard-ai-platform/mcp-tw-ly
Project-URL: Issues, https://github.com/asgard-ai-platform/mcp-tw-ly/issues
Author-email: Asgard AI Platform <dev@asgard.ai>
License: MIT
License-File: LICENSE
Keywords: ai-tools,legislative-yuan,mcp,mcp-server,open-data,taiwan
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# mcp-tw-ly

[![PyPI version](https://img.shields.io/pypi/v/mcp-tw-ly)](https://pypi.org/project/mcp-tw-ly/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-tw-ly)](https://pypi.org/project/mcp-tw-ly/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)
[![GitHub stars](https://img.shields.io/github/stars/asgard-ai-platform/mcp-tw-ly)](https://github.com/asgard-ai-platform/mcp-tw-ly/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/asgard-ai-platform/mcp-tw-ly)](https://github.com/asgard-ai-platform/mcp-tw-ly/issues)
[![GitHub last commit](https://img.shields.io/github/last-commit/asgard-ai-platform/mcp-tw-ly)](https://github.com/asgard-ai-platform/mcp-tw-ly/commits/main)

MCP server for querying Taiwan's Legislative Yuan (立法院) public data via the [Legislative Yuan API v2](https://v2.ly.govapi.tw). Built on [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) over stdio JSON-RPC 2.0.

[繁體中文](README.zh-TW.md)

## Features

- **No authentication required** — public API, no API keys needed
- **`@mcp.tool()` decorator** — Pydantic-typed tool registration
- **Claude Code integration** — `.mcp.json` auto-discovery + `CLAUDE.md`

## Available Tools

| Tool | Description |
|------|-------------|
| `list_legislators` | List legislators with optional filters (term, party, constituency, name) |
| `get_legislator` | Get a single legislator by term and name |
| `get_legislator_meets` | Get meetings attended by a legislator |
| `get_legislator_propose_bills` | Get bills proposed by a legislator |
| `get_legislator_cosign_bills` | Get bills co-signed by a legislator |
| `get_legislator_interpellations` | Get interpellations where the legislator is the interpellator |
| `list_bills` | List bills with optional bill filters |
| `get_bill` | Get a single bill by bill number |
| `get_bill_related_bills` | Get bills related to a bill |
| `get_bill_doc_html` | Get HTML document entries for a bill |
| `get_bill_meets` | Get meetings related to a bill |
| `list_meets` | List meetings with optional filters |
| `get_meet` | Get a single meeting by meeting code |
| `get_meet_ivods` | Get IVOD entries related to a meeting |
| `get_meet_bills` | Get bills related to a meeting |
| `get_meet_interpellations` | Get interpellations related to a meeting |
| `list_interpellations` | List interpellations with optional filters |
| `get_interpellation` | Get a single interpellation by ID |

## Usage Examples

### "我想查黃國昌委員的基本資料"

> **You:** 幫我查第 11 屆黃國昌委員的資料

**AI calls:**

```
get_legislator(
  term = 11,
  name = "黃國昌",
)
```

**Result:** `SUCCESS` — 黃國昌，男，台灣民眾黨，全國不分區及僑居國外國民。學歷：臺灣大學法律系學士、美國康乃爾大學法學博士。曾任中央研究院法律學研究所研究員。已於 2026/02/01 辭職離職。

---

### "上禮拜的院會在討論什麼？"

> **You:** 上禮拜院會有開什麼會？討論了哪些事情？

**AI calls:**

```
get_meet(
  meet_id = "院會-11-5-5",
)
```

**Result:** `SUCCESS` — 第 11 屆第 5 會期第 5 次會議，日期：2026-03-27、2026-03-31、2026-04-07。議程包含：台灣民眾黨黨團提案要求行政院核准新興民生計畫預算 718 億元，以及對行政院院長施政方針繼續質詢。出席委員共 113 人。

---

### "查一下這個議案的內容"

> **You:** 幫我查議案編號 202110200590000 的詳細內容

**AI calls:**

```
get_bill(
  bill_no = "202110200590000",
)
```

**Result:** `SUCCESS` — 「衛生福利部組織法第二條、第五條及第八條條文修正草案」，提案委員沈發惠等 18 人。提案日期 2026-03-27，目前狀態：排入院會。案由：因應超高齡社會長照需求、少子女化兒少保護，及全民健保政策權責分工，修正衛福部組織法。

---

### "這個議案有沒有相關的其他議案？"

> **You:** 議案 202110200590000 有什麼相關議案？

**AI calls:**

```
get_bill_related_bills(
  bill_no = "202110200590000",
)
```

**Result:** `SUCCESS` — 找到相關議案：202110189540000「衛生福利部組織法第二條條文修正草案」，由范雲等 18 人提案（2026-01-30），目前狀態：交付審查。內容聚焦於強化婦女福利業務之專責層級。

---

### "羅智強委員有什麼質詢紀錄？"

> **You:** 幫我查羅智強在第 11 屆第 1 會期第 1 次會議的質詢

**AI calls:**

```
get_interpellation(
  interpellation_id = "11-1-1-1",
)
```

**Result:** `SUCCESS` — 質詢委員：羅智強，刊登日期 2024-02-16。事由：就文化部發放文化成年禮金政策屢傳遭濫用亂象，未達政策預期效果，向行政院提出質詢。質詢內容涉及文化幣被用於購買非文化類商品（化妝品、日用品、3C）、網路轉賣等問題。

---

### "蘇巧慧委員是哪個選區的？"

> **You:** 蘇巧慧委員的基本資料，她是哪個黨、哪個選區？

**AI calls:**

```
get_legislator(
  term = 11,
  name = "蘇巧慧",
)
```

**Result:** `SUCCESS` — 蘇巧慧，女，民主進步黨，新北市第 5 選舉區。學歷：美國賓州大學法律碩士、台大法律系司法組。經歷：第九屆、第十屆立法委員，現任第 11 屆第 5 會期內政委員會委員。

---

## Quick Start

```bash
# Run server
uv run python mcp_server.py

# Interactive dev/test (MCP Inspector)
uv run mcp dev mcp_server.py
```

### Claude Code Integration

Add to your Claude Code config via `.mcp.json` (already included in this repo):

```json
{
  "mcpServers": {
    "mcp-tw-ly": {
      "command": "uv",
      "args": ["run", "python", "mcp_server.py"],
      "cwd": "/path/to/mcp-tw-ly"
    }
  }
}
```

## Project Structure

```
mcp-tw-ly/
├── app.py                   # FastMCP singleton
├── mcp_server.py            # Entry point (stdio transport)
├── sources/
│   ├── http_source.py       # Base HTTP client with retry
│   └── lyv2_client.py       # Legislative Yuan API v2 client
├── services/
│   └── container.py         # Dependency injection / client factory
└── tools/
    ├── bill.py              # Bill MCP tools
    ├── interpellation.py    # Interpellation MCP tools
    ├── meet.py              # Meet MCP tools
    └── legislator.py        # Legislator MCP tools
```

## Data Source

All data comes from [https://v2.ly.govapi.tw](https://v2.ly.govapi.tw) — Taiwan Legislative Yuan open data API v2 (govapi.tw). No API key required.

## Testing

```bash
python tests/test_all_tools.py   # Run all tool E2E tests
```

## License

MIT License — see [LICENSE](LICENSE) for details.
