twmcp
Taiwan utilities + open-data MCP server — open-source, local, no token, no rate limit, no telemetry.
Drop-in alternative to hub.twinkleai.tw.
Why
Twinkle Hub 是閉源 SaaS MCP proxy — 每個 query 經他們 server、sk-... Bearer token 計費、未來 pay-as-you-go。
所有 37 個 tool 的演算法已標 MIT、所有資料是政府公開資料（OGDL Taiwan 1.0）。
沒有理由把資料主權交出去。
| hub.twinkleai.tw | twmcp |
|---|
| Hosting | SaaS proxy | 本地 |
| Auth | sk-... Bearer token | 無 |
| Cost | Pay-as-you-go (planned) | Free, MIT |
| Privacy | Queries 經其 server | 純本地計算 |
| SLA | 99.5% (Pro tier) | 100% (你跑你的) |
| Lock-in | 透過其 .json 設定鎖定 | MCP / CLI / Skill / Plugin 四層任選 |
| Telemetry | 未知 | 零 SDK，承諾不加 |
Twinkle Hub 官方在 pricing 頁寫：
"Twinkle Hub is an MCP endpoint, not an SDK ... MCP is open protocol;
rolling your own or going elsewhere is always an option."
這個 repo 就是「rolling our own」。
Quick start
# 從 git 跑（v0.1，PyPI 未發布前的推薦方式）
git clone https://github.com/iml1s/twmcp && cd twmcp
uvx --from . twmcp serve
# 發布 PyPI 後（v0.2+）
uvx twmcp serve
# 或常駐
pipx install twmcp && twmcp serve
註冊到 MCP client
Claude Code — 在 repo root 直接跑 claude，會自動讀 .mcp.json 啟動 server。或全域註冊：
claude mcp add --transport stdio twmcp -- uvx twmcp serve
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{ "mcpServers": { "twmcp": { "command": "uvx", "args": ["twmcp", "serve"] } } }
Cursor (~/.cursor/mcp.json):
{ "mcpServers": { "twmcp": { "command": "uvx", "args": ["twmcp", "serve"] } } }
Cline / Continue / 其他 MCP client — 同上 stdio command 格式，加進該 client 的 MCP config。
CLI（不用 LLM）
twmcp id A123456789 # 驗證身分證 + 縣市判讀
twmcp tax-id 12345675 --rule pre-2023 # 驗證 8 碼統編 checksum
twmcp addr-normalize "高雄縣鳳山區某路1號" # 全形/異體字/舊縣升格
twmcp roc-to-year 114-05-04 # 民國 → 西元
twmcp num 12345 --upper # → 壹萬貳仟參佰肆拾伍
twmcp gen-id --seed 7 # 產 test fixture (含 is_test=True)
twmcp serve --transport http # HTTP mode，綁 127.0.0.1:8765
twmcp --help # 看全部
範例輸出：
$ twmcp id A123456789
{
"valid": true,
"type": "national",
"sex": "male",
"issued_county_code": "A",
"issued_county_hint": "臺北市"
}
$ twmcp addr-normalize "高雄縣鳳山區某路1號"
{
"valid": true,
"original": "高雄縣鳳山區某路1號",
"normalized": "高雄市鳳山區某路1號",
"upgraded_legacy_county": true,
"legacy_alias_detected": "高雄縣"
}
Tools
v0.1（已實作，11 個純函式 tools，無外部呼叫）：
| Tool | 用途 |
|---|
validate_taiwan_id_number | 身分證/統一證號 checksum + 縣市判讀（含 1995-2020 舊式、2021+ 新式外來人口） |
validate_tax_id_number | 8 碼統編 checksum（post-2023 mod 5 / pre-2023 mod 10 / both） |
generate_test_taiwan_id_tool | 產通過 checksum 的測試身分證（強制 is_test: true） |
generate_test_tax_id_tool | 產通過 checksum 的測試統編 |
normalize_taiwan_address | 全形→半形、異體字（巿/区/号）統一、台→臺、舊縣升格 |
align_legacy_county_tool | 高雄縣→高雄市、台北縣→新北市、桃園縣→桃園市… 含改制年 |
roc_year_to_western_tool | 民國 → 西元，支援 114 / 114-05-04 / 114年5月4日 / 1140504 |
western_year_to_roc_tool | 西元 → 民國 |
simplified_to_traditional_tool | 簡 → 繁（zh-tw 台灣正體 / zh-hk 香港繁體） |
traditional_to_simplified_tool | 繁 → 簡 |
format_chinese_numerals_tool | 阿拉伯↔中文，支援大寫（壹貳參）、繁/簡（公文/合約/支票場景） |
Roadmap — 預計補到 ~37 tools：
| 版本 | 範圍 |
|---|
| v0.2 | 商業日、國定假日、捷運站線、銀行代號、政府機關代碼、24 節氣、農曆↔國曆、生肖 |
| v0.3 | 郵遞區號 (3/5/6 碼)、行政區查詢、車牌、電話、MOEA 統編查公司、地址中英譯 |
| v0.4 | data.gov.tw FTS5 catalog 索引（52,960 datasets） |
| v0.5 | PCC 政府電子採購 daily sync |
| v0.6 | PDF 三件套、URL→markdown、IANA 時區、秒數人類化 |
| v0.7 | Claude Code plugin marketplace 上架 |
| v1.0 | 19 domains 全覆蓋 + 可選 Web UI |
資料來源
公開政府開放資料，遵循 OGDL Taiwan 1.0：
每個資料 tool response 都附 attribution (來源 URL + 機關 + license)。
隱私
- 所有計算在本地；除少數需 daily refresh 的政府資料外，無外部 API 呼叫
- 無 token、無 cookie、無使用追蹤、承諾不加 telemetry SDK
- 身分證/統編測試 fixtures 強制
is_test: true — 避免被誤用為真實 PII
- HTTP transport 預設綁
127.0.0.1（不是 0.0.0.0），不放外網
Development
需 Python ≥ 3.11。CI 跑 3.11 / 3.12 / 3.13 矩陣。
