citybikes-mcp 1.0.1 → 1.0.3

package/README.md

@@ -19,3 +19,5 @@ node dist/index.js
 ```
 
 Data comes from the public CityBikes aggregation API.
+
+

package/dist/api.js

@@ -49,3 +49,50 @@ export async function network(args) {
         lines.push(`... and ${total - 20} more stations`);
     return lines.join("\n");
 }
+// ---- muxA tools:
+const BIKES = "https://api.citybik.es/v2";
+async function cbGet(path) {
+    const res = await fetch(`${BIKES}${path}`, {
+        headers: { "User-Agent": UA, Accept: "application/json" },
+        signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok)
+        throw new CitybikesError(`CityBikes returned HTTP ${res.status}`);
+    return (await res.json());
+}
+function place(n) {
+    const l = (n.location ?? {});
+    return [l.city, l.state, l.country].filter(Boolean).join(", ") || "location not reported";
+}
+export async function networkCapacity(args) {
+    const id = (args.network ?? "").trim();
+    if (!id)
+        throw new CitybikesError("Provide a network id, e.g. joco-new-york.");
+    const d = await cbGet(`/networks/${encodeURIComponent(id)}`);
+    const n = d?.network;
+    if (!n)
+        return `CityBikes has no network with id "${id}". Try network_search to list valid ids.`;
+    const stations = (n.stations ?? []);
+    if (!stations.length)
+        return `${n.name ?? id} reports no stations, so no capacity can be computed.`;
+    const free = stations.reduce((a, s) => a + (Number(s.free_bikes) || 0), 0);
+    const slots = stations.reduce((a, s) => a + (Number(s.empty_slots) || 0), 0);
+    const withBikes = stations.filter((s) => Number(s.free_bikes ?? 0) > 0).length;
+    const full = stations.filter((s) => Number(s.empty_slots ?? 0) === 0).length;
+    const empty = stations.filter((s) => Number(s.free_bikes ?? 0) === 0).length;
+    const ebikes = stations.reduce((a, s) => a + (Number(s.extra?.ebikes) || 0), 0);
+    const ebikeStations = stations.filter((s) => Number(s.extra?.ebikes ?? 0) > 0).length;
+    const total = free + slots;
+    const mean = total / stations.length;
+    const sd = Math.sqrt(stations.reduce((a, s) => a + (Number(s.free_bikes ?? 0) - mean) ** 2, 0) / stations.length);
+    return [
+        `${n.name ?? id} | ${place(n)}`,
+        `${stations.length} stations | ${free.toLocaleString("en-US")} bikes free | ${slots.toLocaleString("en-US")} empty slots | ${total.toLocaleString("en-US")} total capacity`,
+        `Stations with at least one bike: ${withBikes} of ${stations.length} (${((withBikes / stations.length) * 100).toFixed(1)}%)`,
+        `Completely full stations: ${full} | completely empty stations: ${empty}`,
+        ebikes || ebikeStations ? `E-bikes: ${ebikes} available across ${ebikeStations} station(s)` : "No e-bike data reported",
+        `Bikes per station: mean ${mean.toFixed(2)}, standard deviation ${sd.toFixed(2)}` +
+            (mean ? `, coefficient of variation ${((sd / mean) * 100).toFixed(1)}%` : ""),
+        `Operator: ${n.company ?? "not reported"}${n.ebikes != null ? ` | network level e-bikes ${n.ebikes}` : ""}`,
+    ].join("\n");
+}

package/dist/server.js

@@ -1,7 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { network } from "./api.js";
-import { networks } from "./api.js";
+import { network, networks, networkCapacity } from "./api.js";
 const text = (value) => ({ content: [{ type: "text", text: value }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -18,7 +17,7 @@ export function createServer() {
             return text(await networks(args));
         }
         catch (e) {
-            return textError(error(e));
+            return textError(String(e));
         }
     });
     server.registerTool("network", {
@@ -31,7 +30,48 @@ export function createServer() {
             return text(await network(args));
         }
         catch (e) {
-            return textError(error(e));
+            return textError(String(e));
+        }
+    });
+    server.registerTool("network_search", {
+        title: "Network search",
+        description: "Search the CityBikes directory of bike share systems by name, id, operator, city or country, with a breakdown of how many networks operate in each country.",
+        inputSchema: z.object({ query: z.string().describe("Name, id or operator fragment.").optional(), country: z.string().describe("Country fragment.").optional(), limit: z.number().describe("Max results.").optional(), summary: z.boolean().describe("List matches compactly.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // TODO: implement search locally (paywall removed)
+        try {
+            return textError("Not yet implemented: search");
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    server.registerTool("station_search", {
+        title: "Station search",
+        description: "Find stations inside a CityBikes network by name or by live availability, ranked by bikes free, with dock counts, coordinates, e-bike numbers and the data timestamp.",
+        inputSchema: z.object({ network: z.string().describe("Network id, e.g. joco-new-york."), query: z.string().describe("Station name fragment.").optional(), has_bikes: z.boolean().describe("Only stations with bikes.").optional(), has_slots: z.boolean().describe("Only stations with empty slots.").optional(), limit: z.number().describe("Max stations.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // TODO: implement search locally (paywall removed)
+        try {
+            return textError("Not yet implemented: search");
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    server.registerTool("network_capacity", {
+        title: "Network capacity",
+        description: "Live capacity statistics for a CityBikes network: free bikes and empty docks in total, share of stations stocked, completely full and empty stations, e-bike availability and the spread of bikes per station.",
+        inputSchema: z.object({ network: z.string().describe("Network id, e.g. joco-new-york.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await networkCapacity(args));
+        }
+        catch (e) {
+            return textError(e instanceof Error ? `Error: ${e.message}` : String(e));
         }
     });
     return server;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "repository": {
     "type": "git",
@@ -41,4 +41,4 @@
   "engines": {
     "node": ">=20"
   }
-}
+}