twmcp

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：

• data.gov.tw — 52,960 datasets
• 中華郵政 TOWN_MOI.kml — 郵遞區號 + 行政區
• 行政院人事行政總處辦公日曆（2024-2025 含補班；2026+ 取消補假）
• FISC 銀行代號（含純網銀+郵政）
• FSC 金融機構
• MOEA 商工資料
• TDX 運輸資料
• PCC 政府電子採購網

每個資料 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 矩陣。