tdx-mcp 1.0.0

package/README.md

@@ -0,0 +1,20 @@
+# tdx-mcp
+
+Taiwan TDX transport: TRA and THSR stations, live boards, daily timetables. Needs app keys.
+
+## Setup
+
+```bash
+export TDX_CLIENT_ID=...
+```
+
+Needs free TDX client id + secret (TDX_CLIENT_SECRET) from tdx.transportdata.tw.
+
+## Tools
+
+- `list_tra_stations` — Taiwan Railway stations with ids, names, coordinates for live boards.
+- `get_tra_liveboard` — Live Taiwan Railway departures and arrivals for a station.
+- `list_thsr_stations` — Taiwan High Speed Rail stations with ids and addresses.
+- `get_tra_timetable` — Taiwan Railway daily timetable for a station on a date.
+
+Part of [awesome-mcps](https://github.com/mrfentmen/awesome-mcps).

package/dist/api.d.ts

@@ -0,0 +1,8 @@
+export declare class TdxError extends Error {
+    constructor(message: string);
+}
+export declare function errorMessage(e: unknown): string;
+export declare function listTraStations(): Promise<string>;
+export declare function getTraLiveboard(stationId: string): Promise<string>;
+export declare function listThsrStations(): Promise<string>;
+export declare function getTraTimetable(stationId: string, date: string): Promise<string>;

package/dist/api.js

@@ -0,0 +1,99 @@
+export class TdxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TdxError";
+    }
+}
+export function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+const UA = { "User-Agent": "awesome-mcps/1.0" };
+const BASE = "https://tdx.transportdata.tw";
+function envStrict(name) {
+    const v = process.env[name];
+    if (!v)
+        throw new TdxError(`Set the ${name} environment variable.`);
+    return v;
+}
+let cachedToken = "";
+let tokenExpiresAt = 0;
+async function tdxToken() {
+    const now = Date.now();
+    if (!cachedToken || now >= tokenExpiresAt) {
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: envStrict("TDX_CLIENT_ID"),
+            client_secret: envStrict("TDX_CLIENT_SECRET"),
+        });
+        const res = await fetch("https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token", {
+            method: "POST",
+            headers: { ...UA, "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        });
+        if (!res.ok)
+            throw new TdxError(`TDX login failed: HTTP ${res.status}`);
+        const data = (await res.json());
+        if (!data.access_token)
+            throw new TdxError("TDX login returned no access token");
+        cachedToken = data.access_token;
+        tokenExpiresAt = now + (data.expires_in ?? 86400) * 1000 - 60000;
+    }
+    return cachedToken;
+}
+async function authHeaders() {
+    return { Authorization: "Bearer " + (await tdxToken()) };
+}
+function pretty(data) {
+    const t = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    return t.length > 12000 ? t.slice(0, 12000) + "\n…(truncated)" : t;
+}
+async function req(url, init = {}) {
+    const res = await fetch(url, { headers: { ...UA, ...(await authHeaders()), ...(init.headers ?? {}) }, ...init });
+    const ct = res.headers.get("content-type") ?? "";
+    const data = ct.includes("json") ? await res.json() : await res.text();
+    if (!res.ok) {
+        const detail = typeof data === "string" ? data.slice(0, 300) : JSON.stringify(data).slice(0, 300);
+        throw new TdxError(`HTTP ${res.status}: ${detail}`);
+    }
+    return data;
+}
+export async function listTraStations() {
+    let url = BASE + `/api/basic/v2/Rail/TRA/Station`;
+    const qs = new URLSearchParams();
+    qs.append("$format", "JSON");
+    const qstr = qs.toString();
+    if (qstr)
+        url += (url.includes('?') ? '&' : '?') + qstr;
+    const data = await req(url);
+    return pretty(data);
+}
+export async function getTraLiveboard(stationId) {
+    let url = BASE + `/api/basic/v2/Rail/TRA/LiveBoard/Station/${encodeURIComponent(String(stationId))}`;
+    const qs = new URLSearchParams();
+    qs.append("$format", "JSON");
+    const qstr = qs.toString();
+    if (qstr)
+        url += (url.includes('?') ? '&' : '?') + qstr;
+    const data = await req(url);
+    return pretty(data);
+}
+export async function listThsrStations() {
+    let url = BASE + `/api/basic/v2/Rail/THSR/Station`;
+    const qs = new URLSearchParams();
+    qs.append("$format", "JSON");
+    const qstr = qs.toString();
+    if (qstr)
+        url += (url.includes('?') ? '&' : '?') + qstr;
+    const data = await req(url);
+    return pretty(data);
+}
+export async function getTraTimetable(stationId, date) {
+    let url = BASE + `/api/basic/v2/Rail/TRA/DailyTimetable/Station/${encodeURIComponent(String(stationId))}/${encodeURIComponent(String(date))}`;
+    const qs = new URLSearchParams();
+    qs.append("$format", "JSON");
+    const qstr = qs.toString();
+    if (qstr)
+        url += (url.includes('?') ? '&' : '?') + qstr;
+    const data = await req(url);
+    return pretty(data);
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,70 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { errorMessage, listTraStations, getTraLiveboard, listThsrStations, getTraTimetable, } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "tdx-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("list_tra_stations", {
+        title: "List TRA stations",
+        description: "Taiwan Railway stations with ids, names, coordinates for live boards.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async ({}) => {
+        try {
+            return text(await listTraStations());
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_tra_liveboard", {
+        title: "Get TRA live board",
+        description: "Live Taiwan Railway departures and arrivals for a station.",
+        inputSchema: z.object({
+            stationId: z.string().describe("Station id from list_tra_stations"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ stationId }) => {
+        try {
+            return text(await getTraLiveboard(stationId));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("list_thsr_stations", {
+        title: "List THSR stations",
+        description: "Taiwan High Speed Rail stations with ids and addresses.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async ({}) => {
+        try {
+            return text(await listThsrStations());
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_tra_timetable", {
+        title: "Get TRA timetable",
+        description: "Taiwan Railway daily timetable for a station on a date.",
+        inputSchema: z.object({
+            stationId: z.string().describe("Station id"),
+            date: z.string().describe("Date YYYY-MM-DD"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ stationId, date }) => {
+        try {
+            return text(await getTraTimetable(stationId, date));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "tdx-mcp",
+  "version": "1.0.0",
+  "description": "Taiwan TDX transport: TRA and THSR stations, live boards, daily timetables. Needs app keys.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/tdx-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/awesome-mcps.git"
+  },
+  "bin": {
+    "tdx-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "taiwan",
+    "tdx",
+    "rail",
+    "tra",
+    "thsr",
+    "transit"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}