@striderlabs/mcp-spothero 1.0.0

package/esbuild.config.js

@@ -0,0 +1,23 @@
+import { build } from "esbuild";
+
+const isWatch = process.argv.includes("--watch");
+
+const ctx = await build({
+  entryPoints: ["src/index.ts"],
+  bundle: true,
+  platform: "node",
+  target: "node18",
+  format: "esm",
+  outfile: "dist/index.js",
+  sourcemap: true,
+  minify: false,
+  banner: {
+    js: "#!/usr/bin/env node",
+  },
+  external: [],
+  logLevel: "info",
+});
+
+if (!isWatch) {
+  process.exit(0);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@striderlabs/mcp-spothero",
+  "version": "1.0.0",
+  "description": "MCP server for SpotHero parking reservations",
+  "author": "Strider Labs <hello@striderlabs.ai>",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "bin": {
+    "striderlabs-mcp-spothero": "dist/index.js"
+  },
+  "scripts": {
+    "build": "node esbuild.config.js",
+    "dev": "node esbuild.config.js --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.6.0"
+  },
+  "mcpName": "io.github.striderlabs/spothero"
+}

package/src/index.ts

@@ -0,0 +1,573 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// --- Types ---
+
+interface SpotHeroConfig {
+  apiKey: string;
+  authToken?: string;
+  baseUrl: string;
+}
+
+interface SearchParkingArgs {
+  location: string;
+  starts: string;
+  ends: string;
+  radius_miles?: number;
+  vehicle_type?: "car" | "motorcycle" | "suv";
+}
+
+interface GetSpotDetailsArgs {
+  facility_id: string;
+}
+
+interface GetAvailabilityArgs {
+  facility_id: string;
+  starts: string;
+  ends: string;
+}
+
+interface ReserveSpotArgs {
+  rate_id: string;
+  facility_id: string;
+  starts: string;
+  ends: string;
+  vehicle?: {
+    make?: string;
+    model?: string;
+    color?: string;
+    license_plate?: string;
+    state?: string;
+  };
+  payment_method_id?: string;
+}
+
+interface CancelReservationArgs {
+  reservation_id: string;
+  reason?: string;
+}
+
+interface GetReservationsArgs {
+  status?: "upcoming" | "past" | "cancelled" | "all";
+  limit?: number;
+  offset?: number;
+}
+
+interface GetNearbySpotsArgs {
+  lat: number;
+  lng: number;
+  radius_miles?: number;
+  starts?: string;
+  ends?: string;
+  limit?: number;
+}
+
+interface GetMonthlyParkingArgs {
+  location: string;
+  radius_miles?: number;
+  vehicle_type?: "car" | "motorcycle" | "suv";
+}
+
+interface GetEventParkingArgs {
+  event_id?: string;
+  venue_name?: string;
+  event_date?: string;
+  radius_miles?: number;
+}
+
+// --- SpotHero API Client ---
+
+const BASE_URL = "https://api.spothero.com/v2";
+
+function getConfig(): SpotHeroConfig {
+  const apiKey = process.env.SPOTHERO_API_KEY ?? "";
+  const authToken = process.env.SPOTHERO_AUTH_TOKEN;
+  return {
+    apiKey,
+    authToken,
+    baseUrl: process.env.SPOTHERO_BASE_URL ?? BASE_URL,
+  };
+}
+
+function buildHeaders(config: SpotHeroConfig): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "X-SpotHero-Api-Key": config.apiKey,
+    "User-Agent": "SpotHero-MCP/1.0",
+  };
+  if (config.authToken) {
+    headers["Authorization"] = `Bearer ${config.authToken}`;
+  }
+  return headers;
+}
+
+async function apiGet(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<unknown> {
+  const config = getConfig();
+  const url = new URL(`${config.baseUrl}${path}`);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers: buildHeaders(config),
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`SpotHero API error ${response.status}: ${errorText}`);
+  }
+  return response.json();
+}
+
+async function apiPost(path: string, body: unknown): Promise<unknown> {
+  const config = getConfig();
+  const response = await fetch(`${config.baseUrl}${path}`, {
+    method: "POST",
+    headers: buildHeaders(config),
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`SpotHero API error ${response.status}: ${errorText}`);
+  }
+  return response.json();
+}
+
+async function apiDelete(path: string, body?: unknown): Promise<unknown> {
+  const config = getConfig();
+  const response = await fetch(`${config.baseUrl}${path}`, {
+    method: "DELETE",
+    headers: buildHeaders(config),
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`SpotHero API error ${response.status}: ${errorText}`);
+  }
+  if (response.status === 204) return { success: true };
+  return response.json();
+}
+
+// --- Tool Handlers ---
+
+async function searchParking(args: SearchParkingArgs): Promise<unknown> {
+  return apiGet("/search/transient", {
+    location: args.location,
+    starts: args.starts,
+    ends: args.ends,
+    radius: args.radius_miles ?? 1.0,
+    vehicle_type: args.vehicle_type ?? "car",
+  });
+}
+
+async function getSpotDetails(args: GetSpotDetailsArgs): Promise<unknown> {
+  return apiGet(`/facilities/${args.facility_id}`);
+}
+
+async function getAvailability(args: GetAvailabilityArgs): Promise<unknown> {
+  return apiGet(`/facilities/${args.facility_id}/availability`, {
+    starts: args.starts,
+    ends: args.ends,
+  });
+}
+
+async function reserveSpot(args: ReserveSpotArgs): Promise<unknown> {
+  return apiPost("/reservations", {
+    rate_id: args.rate_id,
+    facility_id: args.facility_id,
+    starts: args.starts,
+    ends: args.ends,
+    vehicle: args.vehicle ?? {},
+    payment_method_id: args.payment_method_id,
+  });
+}
+
+async function cancelReservation(args: CancelReservationArgs): Promise<unknown> {
+  return apiDelete(`/reservations/${args.reservation_id}`, {
+    reason: args.reason ?? "user_requested",
+  });
+}
+
+async function getReservations(args: GetReservationsArgs): Promise<unknown> {
+  return apiGet("/reservations", {
+    status: args.status ?? "all",
+    limit: args.limit ?? 20,
+    offset: args.offset ?? 0,
+  });
+}
+
+async function getNearbySpots(args: GetNearbySpotsArgs): Promise<unknown> {
+  return apiGet("/search/nearby", {
+    lat: args.lat,
+    lng: args.lng,
+    radius: args.radius_miles ?? 0.5,
+    starts: args.starts,
+    ends: args.ends,
+    limit: args.limit ?? 20,
+  });
+}
+
+async function getMonthlyParking(args: GetMonthlyParkingArgs): Promise<unknown> {
+  return apiGet("/search/monthly", {
+    location: args.location,
+    radius: args.radius_miles ?? 1.0,
+    vehicle_type: args.vehicle_type ?? "car",
+  });
+}
+
+async function getEventParking(args: GetEventParkingArgs): Promise<unknown> {
+  if (args.event_id) {
+    return apiGet(`/events/${args.event_id}/parking`);
+  }
+  return apiGet("/search/events", {
+    venue: args.venue_name,
+    event_date: args.event_date,
+    radius: args.radius_miles ?? 0.5,
+  });
+}
+
+// --- Tool Definitions ---
+
+const TOOLS: Tool[] = [
+  {
+    name: "search_parking",
+    description:
+      "Search for parking spots near a location or address. Returns available facilities with rates and details.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        location: {
+          type: "string",
+          description: "Address, city, or landmark to search near (e.g. '200 W Madison St, Chicago, IL')",
+        },
+        starts: {
+          type: "string",
+          description: "Parking start time in ISO 8601 format (e.g. '2026-03-14T09:00:00')",
+        },
+        ends: {
+          type: "string",
+          description: "Parking end time in ISO 8601 format (e.g. '2026-03-14T17:00:00')",
+        },
+        radius_miles: {
+          type: "number",
+          description: "Search radius in miles (default: 1.0)",
+        },
+        vehicle_type: {
+          type: "string",
+          enum: ["car", "motorcycle", "suv"],
+          description: "Type of vehicle (default: car)",
+        },
+      },
+      required: ["location", "starts", "ends"],
+    },
+  },
+  {
+    name: "get_spot_details",
+    description:
+      "Get detailed information about a specific parking facility including amenities, hours, entry/exit instructions, and contact info.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        facility_id: {
+          type: "string",
+          description: "The SpotHero facility ID",
+        },
+      },
+      required: ["facility_id"],
+    },
+  },
+  {
+    name: "get_availability",
+    description:
+      "Check real-time availability and pricing for a parking facility for specific dates and times.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        facility_id: {
+          type: "string",
+          description: "The SpotHero facility ID",
+        },
+        starts: {
+          type: "string",
+          description: "Desired start time in ISO 8601 format",
+        },
+        ends: {
+          type: "string",
+          description: "Desired end time in ISO 8601 format",
+        },
+      },
+      required: ["facility_id", "starts", "ends"],
+    },
+  },
+  {
+    name: "reserve_spot",
+    description:
+      "Make a parking reservation at a SpotHero facility. Requires authentication and a valid payment method on file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        rate_id: {
+          type: "string",
+          description: "The rate ID from availability results",
+        },
+        facility_id: {
+          type: "string",
+          description: "The SpotHero facility ID",
+        },
+        starts: {
+          type: "string",
+          description: "Parking start time in ISO 8601 format",
+        },
+        ends: {
+          type: "string",
+          description: "Parking end time in ISO 8601 format",
+        },
+        vehicle: {
+          type: "object",
+          description: "Vehicle information",
+          properties: {
+            make: { type: "string" },
+            model: { type: "string" },
+            color: { type: "string" },
+            license_plate: { type: "string" },
+            state: { type: "string", description: "State abbreviation (e.g. 'IL')" },
+          },
+        },
+        payment_method_id: {
+          type: "string",
+          description: "Payment method ID from user's account (uses default if omitted)",
+        },
+      },
+      required: ["rate_id", "facility_id", "starts", "ends"],
+    },
+  },
+  {
+    name: "cancel_reservation",
+    description:
+      "Cancel an existing parking reservation. Refund eligibility depends on the cancellation policy.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reservation_id: {
+          type: "string",
+          description: "The reservation ID to cancel",
+        },
+        reason: {
+          type: "string",
+          description: "Optional cancellation reason",
+        },
+      },
+      required: ["reservation_id"],
+    },
+  },
+  {
+    name: "get_reservations",
+    description:
+      "List the user's parking reservations. Requires authentication. Can filter by status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["upcoming", "past", "cancelled", "all"],
+          description: "Filter by reservation status (default: all)",
+        },
+        limit: {
+          type: "number",
+          description: "Number of results to return (default: 20, max: 100)",
+        },
+        offset: {
+          type: "number",
+          description: "Pagination offset (default: 0)",
+        },
+      },
+    },
+  },
+  {
+    name: "get_nearby_spots",
+    description:
+      "Find parking spots near specific GPS coordinates. Useful when you have lat/lng rather than an address.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lat: {
+          type: "number",
+          description: "Latitude coordinate",
+        },
+        lng: {
+          type: "number",
+          description: "Longitude coordinate",
+        },
+        radius_miles: {
+          type: "number",
+          description: "Search radius in miles (default: 0.5)",
+        },
+        starts: {
+          type: "string",
+          description: "Optional start time filter in ISO 8601 format",
+        },
+        ends: {
+          type: "string",
+          description: "Optional end time filter in ISO 8601 format",
+        },
+        limit: {
+          type: "number",
+          description: "Max results to return (default: 20)",
+        },
+      },
+      required: ["lat", "lng"],
+    },
+  },
+  {
+    name: "get_monthly_parking",
+    description:
+      "Search for monthly parking passes near a location. Returns facilities offering monthly contracts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        location: {
+          type: "string",
+          description: "Address or area to search (e.g. 'downtown Chicago')",
+        },
+        radius_miles: {
+          type: "number",
+          description: "Search radius in miles (default: 1.0)",
+        },
+        vehicle_type: {
+          type: "string",
+          enum: ["car", "motorcycle", "suv"],
+          description: "Type of vehicle (default: car)",
+        },
+      },
+      required: ["location"],
+    },
+  },
+  {
+    name: "get_event_parking",
+    description:
+      "Find parking for a specific event or venue. Can search by SpotHero event ID or venue name and date.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        event_id: {
+          type: "string",
+          description: "SpotHero event ID (if known)",
+        },
+        venue_name: {
+          type: "string",
+          description: "Venue or stadium name (e.g. 'Wrigley Field', 'United Center')",
+        },
+        event_date: {
+          type: "string",
+          description: "Date of the event in ISO 8601 format (e.g. '2026-04-01')",
+        },
+        radius_miles: {
+          type: "number",
+          description: "Search radius in miles (default: 0.5)",
+        },
+      },
+    },
+  },
+];
+
+// --- MCP Server Setup ---
+
+const server = new Server(
+  {
+    name: "spothero",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    let result: unknown;
+
+    switch (name) {
+      case "search_parking":
+        result = await searchParking(args as SearchParkingArgs);
+        break;
+      case "get_spot_details":
+        result = await getSpotDetails(args as GetSpotDetailsArgs);
+        break;
+      case "get_availability":
+        result = await getAvailability(args as GetAvailabilityArgs);
+        break;
+      case "reserve_spot":
+        result = await reserveSpot(args as ReserveSpotArgs);
+        break;
+      case "cancel_reservation":
+        result = await cancelReservation(args as CancelReservationArgs);
+        break;
+      case "get_reservations":
+        result = await getReservations(args as GetReservationsArgs);
+        break;
+      case "get_nearby_spots":
+        result = await getNearbySpots(args as GetNearbySpotsArgs);
+        break;
+      case "get_monthly_parking":
+        result = await getMonthlyParking(args as GetMonthlyParkingArgs);
+        break;
+      case "get_event_parking":
+        result = await getEventParking(args as GetEventParkingArgs);
+        break;
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// --- Start ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("SpotHero MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}