@tcliplab/transit-mcp 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# Transit API Server
+
+An MCP server for Transit API, a Japanese public transit API built on `https://api.transit.ls8h.com/`.
+
+This server wraps the REST API and is still unofficial.
+
+I made this to search Japanese transit information seamlessly from LLM chat.
+
+## LICENSE
+
+No license is granted at this time. OSS release is planned after permission and scope are clarified.

package/build/index.js

@@ -0,0 +1,298 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+const API_BASE = "https://api.transit.ls8h.com";
+function toSearchParams(params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined) {
+            continue;
+        }
+        searchParams.set(key, String(value));
+    }
+    return searchParams;
+}
+async function fetchTransit(path, params = {}) {
+    const url = new URL(path, API_BASE);
+    const searchParams = toSearchParams(params);
+    searchParams.forEach((value, key) => {
+        url.searchParams.set(key, value);
+    });
+    const response = await fetch(url, {
+        headers: {
+            accept: "application/json",
+        },
+    });
+    const rawText = await response.text();
+    let data = rawText;
+    try {
+        data = JSON.parse(rawText);
+    }
+    catch {
+        // Keep raw text when the endpoint does not return JSON.
+    }
+    if (!response.ok) {
+        const detail = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+        throw new Error(`Transit API ${response.status} ${response.statusText}: ${detail}`);
+    }
+    return data;
+}
+function formatServiceSeconds(seconds) {
+    const day = 86_400;
+    const dayOffset = Math.floor(seconds / day);
+    const normalized = ((seconds % day) + day) % day;
+    const hours = Math.floor(normalized / 3600);
+    const minutes = Math.floor((normalized % 3600) / 60);
+    const clock = `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
+    if (dayOffset === 0) {
+        return clock;
+    }
+    return `${clock} (${dayOffset > 0 ? `+${dayOffset}d` : `${dayOffset}d`})`;
+}
+function secondsToDuration(seconds) {
+    const total = Math.max(0, Math.round(seconds));
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const secs = total % 60;
+    if (hours > 0) {
+        return `${hours}h ${String(minutes).padStart(2, "0")}m`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m ${String(secs).padStart(2, "0")}s`;
+    }
+    return `${secs}s`;
+}
+function asRecord(value) {
+    if (typeof value === "object" && value !== null) {
+        return value;
+    }
+    return {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function textResult(summary, data) {
+    const structuredContent = typeof data === "object" && data !== null
+        ? data
+        : { value: data };
+    return {
+        content: [
+            {
+                type: "text",
+                text: summary,
+            },
+        ],
+        structuredContent,
+    };
+}
+function summarizeJourneys(data) {
+    const record = asRecord(data);
+    const journeys = asArray(record.journeys);
+    const lines = journeys.slice(0, 3).map((journey, index) => {
+        const item = asRecord(journey);
+        const departureSecs = typeof item.departureSecs === "number" ? item.departureSecs : undefined;
+        const arrivalSecs = typeof item.arrivalSecs === "number" ? item.arrivalSecs : undefined;
+        const durationSecs = typeof item.durationSecs === "number" ? item.durationSecs : undefined;
+        const transferCount = typeof item.transferCount === "number" ? item.transferCount : undefined;
+        const legs = asArray(item.legs);
+        const firstLeg = asRecord(legs[0]);
+        const routeName = typeof firstLeg.routeName === "string" ? firstLeg.routeName : undefined;
+        const headsign = typeof firstLeg.headsign === "string" ? firstLeg.headsign : undefined;
+        const parts = [
+            `${index + 1}.`,
+            departureSecs !== undefined && arrivalSecs !== undefined
+                ? `${formatServiceSeconds(departureSecs)} -> ${formatServiceSeconds(arrivalSecs)}`
+                : null,
+            durationSecs !== undefined ? secondsToDuration(durationSecs) : null,
+            transferCount !== undefined ? `${transferCount} transfers` : null,
+            routeName ?? null,
+            headsign ?? null,
+        ].filter(Boolean);
+        return parts.join(", ");
+    });
+    const headerParts = [
+        "Transit plan",
+        typeof record.from === "object" && record.from !== null && "name" in record.from
+            ? `from ${record.from.name ?? ""}`
+            : null,
+        typeof record.to === "object" && record.to !== null && "name" in record.to
+            ? `to ${record.to.name ?? ""}`
+            : null,
+        typeof record.date === "string" ? record.date : null,
+        typeof record.timezone === "string" ? record.timezone : null,
+    ].filter(Boolean);
+    return [headerParts.join(" | "), ...lines].join("\n");
+}
+function summarizePlaces(data) {
+    const record = asRecord(data);
+    const places = asArray(record.places);
+    const lines = places.slice(0, 5).map((place, index) => {
+        const item = asRecord(place);
+        const name = typeof item.name === "string" ? item.name : "unknown";
+        const kind = typeof item.kind === "string" ? item.kind : "place";
+        const endpoint = typeof item.endpoint === "string" ? item.endpoint : "";
+        const source = typeof item.source === "string" ? item.source : "";
+        return `${index + 1}. ${name} (${kind}${source ? `, ${source}` : ""}) ${endpoint ? `-> ${endpoint}` : ""}`.trim();
+    });
+    return ["Place suggestions", ...lines].join("\n");
+}
+function summarizeDepartures(data) {
+    const record = asRecord(data);
+    const departures = asArray(record.departures);
+    const lines = departures.slice(0, 5).map((departure, index) => {
+        const item = asRecord(departure);
+        const routeName = typeof item.routeName === "string" ? item.routeName : "unknown route";
+        const headsign = typeof item.headsign === "string" ? item.headsign : null;
+        const departureSecs = typeof item.departureSecs === "number" ? item.departureSecs : undefined;
+        return [
+            `${index + 1}.`,
+            departureSecs !== undefined ? formatServiceSeconds(departureSecs) : null,
+            routeName,
+            headsign,
+        ]
+            .filter(Boolean)
+            .join(", ");
+    });
+    return [
+        `Departures for ${typeof record.id === "string" ? record.id : "station"}`,
+        ...lines,
+    ].join("\n");
+}
+function summarizeSimpleList(title, items, getLabel) {
+    const lines = items.slice(0, 5).map((item, index) => {
+        const record = asRecord(item);
+        return `${index + 1}. ${getLabel(record)}`;
+    });
+    return [title, ...lines].join("\n");
+}
+const planInput = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    date: z.string().regex(/^\d{8}$/).optional(),
+    time: z.string().regex(/^\d{1,2}:\d{2}(:\d{2})?$/).optional(),
+    type: z.enum(["departure", "arrival", "first", "last"]).optional(),
+    maxTransfers: z.number().int().min(0).max(8).optional(),
+    numItineraries: z.number().int().min(1).max(6).optional(),
+    avoidWalk: z.enum(["true", "false"]).optional(),
+});
+const guidanceInput = planInput.extend({
+    strategy: z.enum(["balanced", "fastest", "fewestTransfers", "lowestFare", "shortestWalk"]).optional(),
+    live: z.enum(["true", "false"]).optional(),
+    tracking: z.enum(["none", "origin", "destination", "both"]).optional(),
+});
+const suggestInput = z.object({
+    q: z.string().min(1),
+    limit: z.number().int().min(1).max(30).optional(),
+});
+const departuresInput = z.object({
+    id: z.string().min(1),
+    date: z.string().regex(/^\d{8}$/).optional(),
+    time: z.string().regex(/^\d{1,2}:\d{2}(:\d{2})?$/).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+});
+const stationInput = z.object({
+    id: z.string().min(1),
+});
+const server = new McpServer({
+    name: "transit-mcp",
+    version: "1.0.0",
+});
+server.registerTool("plan_journey", {
+    title: "Plan journey",
+    description: "Find route options between two stations or geo: points.",
+    inputSchema: planInput,
+}, async (input) => {
+    const data = await fetchTransit("/api/v1/plan", input);
+    return textResult(summarizeJourneys(data), data);
+});
+server.registerTool("guidance_plan", {
+    title: "Guidance plan",
+    description: "Ranked journey options with comparison-friendly guidance data.",
+    inputSchema: guidanceInput,
+}, async (input) => {
+    const data = await fetchTransit("/api/v1/guidance/plan", input);
+    return textResult(summarizeJourneys(data), data);
+});
+server.registerTool("suggest_locations", {
+    title: "Suggest locations",
+    description: "Autocomplete stations and parent stations.",
+    inputSchema: suggestInput,
+}, async (input) => {
+    const data = await fetchTransit("/api/v1/locations/suggest", input);
+    return textResult(summarizePlaces(data), data);
+});
+server.registerTool("suggest_places", {
+    title: "Suggest places",
+    description: "Autocomplete stations, stops, facilities, and addresses.",
+    inputSchema: suggestInput,
+}, async (input) => {
+    const data = await fetchTransit("/api/v1/places/suggest", input);
+    return textResult(summarizePlaces(data), data);
+});
+server.registerTool("get_station", {
+    title: "Get station",
+    description: "Fetch station detail, platforms, and serving routes.",
+    inputSchema: stationInput,
+}, async (input) => {
+    const data = await fetchTransit(`/api/v1/stations/${encodeURIComponent(input.id)}`);
+    const record = asRecord(data);
+    const stationName = typeof record.name === "string" ? record.name : input.id;
+    const routes = asArray(record.routes);
+    const platforms = asArray(record.platforms);
+    const summary = [
+        `Station ${stationName}`,
+        `platforms: ${platforms.length}`,
+        `routes: ${routes.length}`,
+    ].join(" | ");
+    return textResult(summary, data);
+});
+server.registerTool("get_station_departures", {
+    title: "Get station departures",
+    description: "Fetch upcoming departures for a station.",
+    inputSchema: departuresInput,
+}, async (input) => {
+    const data = await fetchTransit(`/api/v1/stations/${encodeURIComponent(input.id)}/departures`, {
+        date: input.date,
+        time: input.time,
+        limit: input.limit,
+    });
+    return textResult(summarizeDepartures(data), data);
+});
+server.registerTool("list_feeds", {
+    title: "List feeds",
+    description: "List ingested feeds with attribution and license metadata.",
+    inputSchema: z.object({}),
+}, async () => {
+    const data = await fetchTransit("/api/v1/feeds");
+    const record = asRecord(data);
+    const feeds = asArray(record.feeds);
+    return textResult(summarizeSimpleList("Feeds", feeds, (item) => {
+        const name = typeof item.name === "string" ? item.name : "unknown";
+        const feedId = typeof item.feedId === "string" ? item.feedId : "unknown";
+        const license = typeof item.license === "string" ? item.license : "";
+        return `${name} (${feedId})${license ? ` - ${license}` : ""}`;
+    }), data);
+});
+server.registerTool("list_operators", {
+    title: "List operators",
+    description: "List operator branding marks and data licenses.",
+    inputSchema: z.object({}),
+}, async () => {
+    const data = await fetchTransit("/api/v1/operators");
+    const record = asRecord(data);
+    const operators = asArray(record.operators);
+    return textResult(summarizeSimpleList("Operators", operators, (item) => {
+        const name = typeof item.name === "string" ? item.name : "unknown";
+        const operatorId = typeof item.operatorId === "string" ? item.operatorId : "";
+        const license = typeof item.license === "string" ? item.license : "";
+        return `${name}${operatorId ? ` (${operatorId})` : ""}${license ? ` - ${license}` : ""}`;
+    }), data);
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("MCP server failed to start:", error);
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@tcliplab/transit-mcp",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "bin": {
+    "transit-mcp": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node build/index.js",
+    "test:client": "node scripts/test-client.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0-alpha.2",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}