taiwan-data-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 taiwan-data-mcp contributors
+
+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.

package/README.md

@@ -0,0 +1,80 @@
+# taiwan-data-mcp
+
+讓 AI 助理（Claude、Cursor、任何支援 MCP 的工具）直接查 **台灣公開資料** 的 MCP server。
+
+一句話：把散落的台灣資料站，變成 AI 可以直接呼叫的工具。資料即時來自來源站，回傳一律附上來源與連結。
+
+## 工具
+
+| 工具 | 功能 | 資料來源 |
+|------|------|----------|
+| `taiwan_scam_check` | 查網址 / 網域是否被 165 通報詐騙 | [fraud.tw](https://fraud.tw)（內政部警政署 165） |
+| `taiwan_company_search` | 用公司名搜尋，拿統一編號與負責人 | [inc.com.tw](https://inc.com.tw)（經濟部公司登記） |
+| `taiwan_company_profile` | 用統編查公司完整登記資料 | inc.com.tw |
+| `taiwan_realprice_search` | 搜尋實價登錄的地址 / 路段 / 行政區 | [housetw.com](https://housetw.com)（內政部實價登錄） |
+| `taiwan_realprice_locate` | 用經緯度反查行政區與行情頁 | housetw.com |
+| `taiwan_realprice_area` | 查某縣市 / 行政區成交行情統計 | housetw.com |
+
+跨工具串接是重點：例如「查這家公司 → 看它登記地址那區的房價 → 查它官網是不是詐騙」，一次問答內 AI 自己串起來。
+
+## 安裝
+
+需要 Node.js 18+。
+
+### Claude Desktop
+
+編輯 `claude_desktop_config.json`（設定 → Developer → Edit Config）：
+
+```json
+{
+  "mcpServers": {
+    "taiwan-data": {
+      "command": "npx",
+      "args": ["-y", "taiwan-data-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add taiwan-data -- npx -y taiwan-data-mcp
+```
+
+### Cursor / 其他
+
+任何支援 MCP 的工具，指向 `npx -y taiwan-data-mcp`（stdio）即可。
+
+## 範例提問
+
+- 「google.com 是詐騙網站嗎？」
+- 「台積電的統編、負責人、資本額是多少？」
+- 「臺北市信義區的房價中位數大概多少？哪幾條路最貴？」
+- 「我在經緯度 25.034, 121.5645，附近房價如何？」
+
+## 開發
+
+```bash
+npm install
+npm run smoke   # 直接打活線 API，驗證 6 個工具回得出資料
+node test/e2e.mjs  # MCP 協定層測試
+```
+
+## 資料來源網站
+
+本工具的資料即時來自以下網站，每筆查詢結果也都會標註來源與連結：
+
+- 實價登錄行情 — **[housetw.com](https://housetw.com)**（實價雷達）
+- 公司登記查核 — **[inc.com.tw](https://inc.com.tw)**（台灣公司登記網）
+- 165 防詐查詢 — **[fraud.tw](https://fraud.tw)**（防詐雷達）
+
+三站皆為聚合台灣政府開放資料的免費查詢服務。
+
+## 資料與免責
+
+資料即時取自上述各站的公開 API，內容以政府開放資料為準，僅供參考，不構成投資、法律或交易建議。詐騙查詢結果為「是否被通報」，未被通報不代表絕對安全。
+
+## License
+
+MIT License

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "taiwan-data-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Taiwan public data — 實價登錄行情、公司登記查核、165 防詐查詢。Lets AI assistants (Claude, Cursor, etc.) query real Taiwan data.",
+  "type": "module",
+  "bin": {
+    "taiwan-data-mcp": "src/server.mjs"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/server.mjs",
+    "smoke": "node test/smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "taiwan",
+    "台灣",
+    "實價登錄",
+    "公司登記",
+    "防詐",
+    "real-estate",
+    "open-data"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kewelin/taiwan-data-mcp.git"
+  },
+  "homepage": "https://github.com/kewelin/taiwan-data-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/kewelin/taiwan-data-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/src/server.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  scamCheck, companySearch, companyProfile,
+  realpriceSearch, realpriceLocate, realpriceArea,
+} from './sources.mjs';
+
+const TOOLS = [
+  {
+    name: 'taiwan_scam_check',
+    description:
+      '查詢某網址 / 網域是否被內政部警政署 165 反詐騙通報為詐騙或涉詐網站。輸入網址或網域（如 example.com 或完整 URL）。回傳風險等級、通報情形與來源連結。資料來源：fraud.tw（165 開放資料）。',
+    inputSchema: {
+      type: 'object',
+      properties: { domain: { type: 'string', description: '要查詢的網址或網域，例如 example.com、https://www.example.com' } },
+      required: ['domain'],
+    },
+    run: (a) => scamCheck(a.domain),
+  },
+  {
+    name: 'taiwan_company_search',
+    description:
+      '用公司名稱（或關鍵字）搜尋台灣公司，回傳符合的公司清單與其統一編號、負責人。要拿到完整資料請接著用 taiwan_company_profile 查統編。資料來源：inc.com.tw（經濟部公司登記）。',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string', description: '公司名稱或關鍵字，例如「台積電」「鴻海精密」' } },
+      required: ['name'],
+    },
+    run: (a) => companySearch(a.name),
+  },
+  {
+    name: 'taiwan_company_profile',
+    description:
+      '用 8 位統一編號查台灣公司完整登記資料：名稱、負責人、資本額、實收資本、設立日期、登記地址、營業項目、狀態、上市櫃與進出口資格等。資料來源：inc.com.tw。',
+    inputSchema: {
+      type: 'object',
+      properties: { unified_business_no: { type: 'string', description: '8 位統一編號，例如 22099131' } },
+      required: ['unified_business_no'],
+    },
+    run: (a) => companyProfile(a.unified_business_no),
+  },
+  {
+    name: 'taiwan_realprice_search',
+    description:
+      '搜尋台灣不動產實價登錄的地址 / 路段 / 行政區，回傳符合項目與成交筆數、連結。用來定位某地址或某區，再看其行情。資料來源：housetw.com（內政部實價登錄）。',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: '地址、路段或行政區關鍵字，例如「信義區」「忠孝東路」' } },
+      required: ['query'],
+    },
+    run: (a) => realpriceSearch(a.query),
+  },
+  {
+    name: 'taiwan_realprice_locate',
+    description:
+      '用經緯度 (lat,lng) 反查所在的台灣縣市與行政區，並回傳該區實價頁連結。適合「我現在在這個座標，附近房價如何」。資料來源：housetw.com。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        lat: { type: 'number', description: '緯度，例如 25.034' },
+        lng: { type: 'number', description: '經度，例如 121.5645' },
+      },
+      required: ['lat', 'lng'],
+    },
+    run: (a) => realpriceLocate(a.lat, a.lng),
+  },
+  {
+    name: 'taiwan_realprice_area',
+    description:
+      '查某縣市 / 行政區的不動產成交行情統計：中位與平均單價（萬/坪）、成交筆數、平均屋齡、價格分位、熱門路段排行。資料來源：housetw.com（內政部實價登錄）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        county: { type: 'string', description: '縣市，例如「臺北市」「新北市」（用「臺」非「台」）' },
+        district: { type: 'string', description: '行政區（可選），例如「信義區」' },
+      },
+      required: ['county'],
+    },
+    run: (a) => realpriceArea(a.county, a.district),
+  },
+];
+
+const server = new Server(
+  { name: 'taiwan-data-mcp', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = TOOLS.find((t) => t.name === req.params.name);
+  if (!tool) return { content: [{ type: 'text', text: `未知工具：${req.params.name}` }], isError: true };
+  try {
+    const result = await tool.run(req.params.arguments || {});
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: !!result?.error };
+  } catch (e) {
+    return { content: [{ type: 'text', text: `工具執行錯誤：${e?.message || e}` }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('taiwan-data-mcp running (stdio) — 6 tools: 防詐 / 公司登記 / 實價登錄');

package/src/sources.mjs

@@ -0,0 +1,97 @@
+// 台灣公開資料來源：薄客戶端，呼叫各站既有 JSON API，資料留在來源站。
+// 每個工具回傳都夾帶 source 與 link（署名 + 導流）。
+
+const UA = 'taiwan-data-mcp/0.1 (+https://github.com/kwlin/taiwan-data-mcp)';
+
+export async function fetchJson(url, { timeout = 12000 } = {}) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeout);
+  try {
+    const r = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' }, signal: ctrl.signal });
+    const text = await r.text();
+    let body = null;
+    try { body = JSON.parse(text); } catch { /* non-JSON (e.g. SSR HTML fallback) */ }
+    return { ok: r.ok, status: r.status, body, raw: text };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// ── 防詐 fraud.tw ───────────────────────────────────────────────
+export function normalizeDomain(input) {
+  let s = String(input || '').trim().toLowerCase();
+  s = s.replace(/^https?:\/\//, '').replace(/^www\./, '');
+  s = s.split('/')[0].split('?')[0].split('#')[0].split(':')[0];
+  return s;
+}
+
+export async function scamCheck(input) {
+  const domain = normalizeDomain(input);
+  if (!domain || !domain.includes('.')) return { error: '請提供有效網址或網域，例如 example.com' };
+  const { ok, body } = await fetchJson(`https://fraud.tw/api/check?d=${encodeURIComponent(domain)}`);
+  if (!ok || !body) return { error: `查詢失敗（fraud.tw）`, domain };
+  return body; // 已自帶 source / detail
+}
+
+// ── 公司登記 inc.com.tw ─────────────────────────────────────────
+export async function companySearch(name) {
+  const q = String(name || '').trim();
+  if (q.length < 2) return { error: '公司名稱至少 2 個字' };
+  const { ok, body } = await fetchJson(`https://inc.com.tw/api/suggest?q=${encodeURIComponent(q)}`);
+  if (!ok || !Array.isArray(body)) return { error: '查詢失敗（inc.com.tw）', query: q };
+  const companies = body
+    .filter((x) => x.t === 'co')
+    .map((x) => ({ unified_business_no: x.id, name: x.n, representative: x.r || null, alias: x.a || null,
+      profile_url: `https://inc.com.tw/c/${x.id}` }));
+  return { query: q, count: companies.length, companies,
+    source: '台灣公司登記網 inc.com.tw' };
+}
+
+export async function companyProfile(id) {
+  const tin = String(id || '').replace(/\D/g, '');
+  if (tin.length !== 8) return { error: '統一編號必須是 8 位數字' };
+  const { ok, status, body } = await fetchJson(`https://inc.com.tw/api/company/${tin}`);
+  if (status === 404) return { error: `查無此統一編號 ${tin}` };
+  if (!ok || !body) return { error: '查詢失敗（inc.com.tw）', unified_business_no: tin };
+  const { source: _drop, ...rest } = body;
+  return { ...rest, profile_url: `https://inc.com.tw/c/${tin}`,
+    source: '台灣公司登記網 inc.com.tw' };
+}
+
+// ── 實價登錄 housetw.com ───────────────────────────────────────
+export async function realpriceSearch(q) {
+  const query = String(q || '').trim();
+  if (query.length < 2) return { error: '搜尋關鍵字至少 2 個字（地址 / 路段 / 行政區）' };
+  const { ok, body } = await fetchJson(`https://housetw.com/api/search.json?q=${encodeURIComponent(query)}`);
+  if (!ok || !body || !Array.isArray(body.items)) return { error: '查詢失敗（housetw.com）', query };
+  return {
+    query,
+    items: body.items.map((it) => ({ ...it, link: it.href ? `https://housetw.com${it.href}` : undefined })),
+    source: '內政部不動產交易實價登錄 · 實價雷達 housetw.com',
+  };
+}
+
+export async function realpriceLocate(lat, lng) {
+  const la = Number(lat), ln = Number(lng);
+  if (!isFinite(la) || !isFinite(ln)) return { error: '請提供有效的 lat / lng 經緯度' };
+  const { ok, body } = await fetchJson(`https://housetw.com/api/near.json?lat=${la}&lng=${ln}`);
+  if (!ok || !body || body.error) return { error: '此座標查無對應行政區（housetw.com）', lat: la, lng: ln };
+  return { lat: la, lng: ln, county: body.county, district: body.district,
+    radar_available: !!body.radar,
+    link: body.url ? `https://housetw.com${body.url}` : undefined,
+    source: '內政部不動產交易實價登錄 · 實價雷達 housetw.com' };
+}
+
+export async function realpriceArea(county, district) {
+  const c = String(county || '').trim();
+  if (!c) return { error: '請提供縣市 county（可加行政區 district）' };
+  const qs = `county=${encodeURIComponent(c)}` + (district ? `&district=${encodeURIComponent(String(district).trim())}` : '');
+  const { ok, body, status } = await fetchJson(`https://housetw.com/api/area.json?${qs}`);
+  // area.json 端點尚未部署時優雅降級為搜尋連結
+  if (status === 404 || !body) {
+    const fallback = await realpriceSearch(`${c}${district || ''}`);
+    return { degraded: true, note: 'area.json 端點尚未上線，改回傳搜尋結果連結', ...fallback };
+  }
+  if (!ok) return { error: '查詢失敗（housetw.com）', county: c };
+  return body;
+}