@striderlabs/mcp-gasbuddy 1.0.0

package/esbuild.config.js

@@ -0,0 +1,31 @@
+const esbuild = require('esbuild');
+
+const watch = process.argv.includes('--watch');
+
+const buildOptions = {
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node18',
+  outfile: 'dist/index.js',
+  format: 'cjs',
+  sourcemap: true,
+  external: [],
+  banner: {
+    js: '#!/usr/bin/env node',
+  },
+  define: {
+    'process.env.NODE_ENV': '"production"',
+  },
+};
+
+if (watch) {
+  esbuild.context(buildOptions).then(ctx => {
+    ctx.watch();
+    console.log('Watching for changes...');
+  });
+} else {
+  esbuild.build(buildOptions).then(() => {
+    console.log('Build complete: dist/index.js');
+  }).catch(() => process.exit(1));
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@striderlabs/mcp-gasbuddy",
+  "version": "1.0.0",
+  "description": "MCP connector for GasBuddy fuel prices and station finder",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-gasbuddy": "dist/index.js"
+  },
+  "scripts": {
+    "build": "node esbuild.config.js",
+    "dev": "node esbuild.config.js --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["mcp", "gasbuddy", "fuel", "gas", "prices", "stations"],
+  "author": "Strider Labs",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.20.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,636 @@
+#!/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 GasBuddyConfig {
+  apiKey: string;
+  baseUrl: string;
+}
+
+interface Station {
+  id: string;
+  name: string;
+  brand: string;
+  address: string;
+  city: string;
+  state: string;
+  zip: string;
+  latitude: number;
+  longitude: number;
+  phone?: string;
+  distance?: number;
+  amenities: string[];
+  prices: FuelPrice[];
+  rating?: number;
+  reviewCount?: number;
+}
+
+interface FuelPrice {
+  grade: string;
+  price: number;
+  currency: string;
+  reportedAt: string;
+  reportedBy?: string;
+  confidence: number;
+}
+
+interface PriceReport {
+  stationId: string;
+  grade: string;
+  price: number;
+  latitude?: number;
+  longitude?: number;
+}
+
+interface PriceTrend {
+  date: string;
+  averagePrice: number;
+  minPrice: number;
+  maxPrice: number;
+  sampleCount: number;
+}
+
+interface Deal {
+  id: string;
+  stationId: string;
+  stationName: string;
+  type: string;
+  description: string;
+  discount: number;
+  discountType: "cents_per_gallon" | "percent" | "fixed";
+  validUntil?: string;
+  requirements?: string;
+}
+
+interface PayWithGasBuddy {
+  enrolled: boolean;
+  savingsPerGallon: number;
+  totalSaved: number;
+  cardNumber?: string;
+  cardStatus?: string;
+  linkedPayment?: string;
+  participatingStations: number;
+}
+
+interface TripCostEstimate {
+  distance: number;
+  distanceUnit: string;
+  fuelEfficiency: number;
+  fuelEfficiencyUnit: string;
+  gallonsNeeded: number;
+  estimatedCost: number;
+  cheapestCost: number;
+  averageCost: number;
+  currency: string;
+  cheapestStation?: Station;
+  routeStations?: Station[];
+}
+
+// ---- API Client ----
+
+class GasBuddyClient {
+  private config: GasBuddyConfig;
+
+  constructor(config: GasBuddyConfig) {
+    this.config = config;
+  }
+
+  private async request<T>(
+    endpoint: string,
+    method: string = "GET",
+    body?: unknown
+  ): Promise<T> {
+    const url = `${this.config.baseUrl}${endpoint}`;
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.config.apiKey,
+      "User-Agent": "mcp-gasbuddy/1.0.0",
+    };
+
+    const options: RequestInit = {
+      method,
+      headers,
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `GasBuddy API error ${response.status}: ${errorText}`
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  async searchStations(params: {
+    latitude?: number;
+    longitude?: number;
+    address?: string;
+    radius?: number;
+    fuel?: string;
+    limit?: number;
+    minRating?: number;
+    amenities?: string[];
+  }): Promise<{ stations: Station[]; total: number }> {
+    const query = new URLSearchParams();
+    if (params.latitude !== undefined) query.set("lat", params.latitude.toString());
+    if (params.longitude !== undefined) query.set("lng", params.longitude.toString());
+    if (params.address) query.set("address", params.address);
+    if (params.radius !== undefined) query.set("radius", params.radius.toString());
+    if (params.fuel) query.set("fuel", params.fuel);
+    if (params.limit !== undefined) query.set("limit", params.limit.toString());
+    if (params.minRating !== undefined) query.set("minRating", params.minRating.toString());
+    if (params.amenities?.length) query.set("amenities", params.amenities.join(","));
+
+    return this.request<{ stations: Station[]; total: number }>(
+      `/v1/stations/search?${query}`
+    );
+  }
+
+  async getStationDetails(stationId: string): Promise<Station> {
+    return this.request<Station>(`/v1/stations/${stationId}`);
+  }
+
+  async getPrices(params: {
+    stationId?: string;
+    latitude?: number;
+    longitude?: number;
+    radius?: number;
+    grade?: string;
+  }): Promise<{ prices: FuelPrice[]; stationId?: string }> {
+    const query = new URLSearchParams();
+    if (params.stationId) query.set("stationId", params.stationId);
+    if (params.latitude !== undefined) query.set("lat", params.latitude.toString());
+    if (params.longitude !== undefined) query.set("lng", params.longitude.toString());
+    if (params.radius !== undefined) query.set("radius", params.radius.toString());
+    if (params.grade) query.set("grade", params.grade);
+
+    return this.request<{ prices: FuelPrice[]; stationId?: string }>(
+      `/v1/prices?${query}`
+    );
+  }
+
+  async reportPrice(report: PriceReport): Promise<{ success: boolean; message: string; reportId: string }> {
+    return this.request<{ success: boolean; message: string; reportId: string }>(
+      "/v1/prices/report",
+      "POST",
+      report
+    );
+  }
+
+  async getPriceTrends(params: {
+    latitude?: number;
+    longitude?: number;
+    stationId?: string;
+    grade?: string;
+    days?: number;
+    region?: string;
+  }): Promise<{ trends: PriceTrend[]; grade: string; region: string }> {
+    const query = new URLSearchParams();
+    if (params.latitude !== undefined) query.set("lat", params.latitude.toString());
+    if (params.longitude !== undefined) query.set("lng", params.longitude.toString());
+    if (params.stationId) query.set("stationId", params.stationId);
+    if (params.grade) query.set("grade", params.grade);
+    if (params.days !== undefined) query.set("days", params.days.toString());
+    if (params.region) query.set("region", params.region);
+
+    return this.request<{ trends: PriceTrend[]; grade: string; region: string }>(
+      `/v1/prices/trends?${query}`
+    );
+  }
+
+  async getDeals(params: {
+    latitude?: number;
+    longitude?: number;
+    radius?: number;
+    type?: string;
+  }): Promise<{ deals: Deal[] }> {
+    const query = new URLSearchParams();
+    if (params.latitude !== undefined) query.set("lat", params.latitude.toString());
+    if (params.longitude !== undefined) query.set("lng", params.longitude.toString());
+    if (params.radius !== undefined) query.set("radius", params.radius.toString());
+    if (params.type) query.set("type", params.type);
+
+    return this.request<{ deals: Deal[] }>(`/v1/deals?${query}`);
+  }
+
+  async getPayWithGasBuddy(userId: string): Promise<PayWithGasBuddy> {
+    return this.request<PayWithGasBuddy>(`/v1/pay-with-gasbuddy/${userId}`);
+  }
+
+  async findCheapest(params: {
+    latitude: number;
+    longitude: number;
+    radius?: number;
+    grade?: string;
+    limit?: number;
+  }): Promise<{ stations: Station[] }> {
+    const query = new URLSearchParams({
+      lat: params.latitude.toString(),
+      lng: params.longitude.toString(),
+      sort: "price_asc",
+    });
+    if (params.radius !== undefined) query.set("radius", params.radius.toString());
+    if (params.grade) query.set("grade", params.grade);
+    if (params.limit !== undefined) query.set("limit", params.limit.toString());
+
+    return this.request<{ stations: Station[] }>(
+      `/v1/stations/search?${query}`
+    );
+  }
+
+  async getFavorites(userId: string): Promise<{ stations: Station[] }> {
+    return this.request<{ stations: Station[] }>(
+      `/v1/users/${userId}/favorites`
+    );
+  }
+
+  async getTripCost(params: {
+    originLatitude: number;
+    originLongitude: number;
+    destLatitude: number;
+    destLongitude: number;
+    fuelEfficiency: number;
+    fuelEfficiencyUnit?: string;
+    grade?: string;
+    tankSize?: number;
+  }): Promise<TripCostEstimate> {
+    return this.request<TripCostEstimate>("/v1/trip/cost", "POST", params);
+  }
+}
+
+// ---- Tool Definitions ----
+
+const TOOLS: Tool[] = [
+  {
+    name: "search_stations",
+    description:
+      "Find gas stations near a location. Supports searching by coordinates or address with optional filters for fuel type, amenities, and rating.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        latitude: { type: "number", description: "Latitude for location-based search" },
+        longitude: { type: "number", description: "Longitude for location-based search" },
+        address: { type: "string", description: "Address or city/state for text-based search" },
+        radius: { type: "number", description: "Search radius in miles (default: 5)" },
+        fuel: {
+          type: "string",
+          enum: ["regular", "midgrade", "premium", "diesel", "e85", "uls"],
+          description: "Filter by fuel type",
+        },
+        limit: { type: "number", description: "Max results to return (default: 20)" },
+        minRating: { type: "number", description: "Minimum station rating (1-5)" },
+        amenities: {
+          type: "array",
+          items: { type: "string" },
+          description: "Required amenities (e.g. car_wash, restrooms, atm, air_pump)",
+        },
+      },
+    },
+  },
+  {
+    name: "get_station_details",
+    description:
+      "Get detailed information about a specific gas station including amenities, current prices, ratings, and contact info.",
+    inputSchema: {
+      type: "object",
+      required: ["station_id"],
+      properties: {
+        station_id: { type: "string", description: "The station's unique identifier" },
+      },
+    },
+  },
+  {
+    name: "get_prices",
+    description:
+      "Get current fuel prices for a station or area. Returns prices by grade with reporting confidence and timestamps.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        station_id: { type: "string", description: "Station ID for station-specific prices" },
+        latitude: { type: "number", description: "Latitude for area prices" },
+        longitude: { type: "number", description: "Longitude for area prices" },
+        radius: { type: "number", description: "Radius in miles for area prices" },
+        grade: {
+          type: "string",
+          enum: ["regular", "midgrade", "premium", "diesel", "e85"],
+          description: "Filter by fuel grade",
+        },
+      },
+    },
+  },
+  {
+    name: "report_price",
+    description:
+      "Report a current fuel price at a gas station. Helps keep the community database accurate.",
+    inputSchema: {
+      type: "object",
+      required: ["station_id", "grade", "price"],
+      properties: {
+        station_id: { type: "string", description: "Station ID where price was observed" },
+        grade: {
+          type: "string",
+          enum: ["regular", "midgrade", "premium", "diesel", "e85"],
+          description: "Fuel grade",
+        },
+        price: { type: "number", description: "Price per gallon in USD" },
+        latitude: { type: "number", description: "Reporter latitude for verification" },
+        longitude: { type: "number", description: "Reporter longitude for verification" },
+      },
+    },
+  },
+  {
+    name: "get_price_trends",
+    description:
+      "Get historical fuel price trends for an area or station. Useful for analyzing price patterns over time.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        station_id: { type: "string", description: "Station ID for station-specific trends" },
+        latitude: { type: "number", description: "Latitude for regional trends" },
+        longitude: { type: "number", description: "Longitude for regional trends" },
+        grade: {
+          type: "string",
+          enum: ["regular", "midgrade", "premium", "diesel", "e85"],
+          description: "Fuel grade (default: regular)",
+        },
+        days: { type: "number", description: "Number of days of history (default: 30, max: 365)" },
+        region: { type: "string", description: "Region code (e.g. CA, TX, US) for national/state trends" },
+      },
+    },
+  },
+  {
+    name: "get_deals",
+    description:
+      "Find current fuel deals and discounts near a location. Includes loyalty discounts, app offers, and credit card deals.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        latitude: { type: "number", description: "Latitude" },
+        longitude: { type: "number", description: "Longitude" },
+        radius: { type: "number", description: "Search radius in miles (default: 10)" },
+        type: {
+          type: "string",
+          enum: ["loyalty", "credit_card", "app_offer", "cashback", "coupon"],
+          description: "Filter by deal type",
+        },
+      },
+    },
+  },
+  {
+    name: "get_pay_with_gasbuddy",
+    description:
+      "Get information about the Pay With GasBuddy savings card, including enrollment status, savings per gallon, and total savings.",
+    inputSchema: {
+      type: "object",
+      required: ["user_id"],
+      properties: {
+        user_id: { type: "string", description: "GasBuddy user ID" },
+      },
+    },
+  },
+  {
+    name: "find_cheapest",
+    description:
+      "Find the cheapest gas stations within a radius, sorted by price. Great for finding the best deal nearby.",
+    inputSchema: {
+      type: "object",
+      required: ["latitude", "longitude"],
+      properties: {
+        latitude: { type: "number", description: "Center point latitude" },
+        longitude: { type: "number", description: "Center point longitude" },
+        radius: { type: "number", description: "Search radius in miles (default: 10)" },
+        grade: {
+          type: "string",
+          enum: ["regular", "midgrade", "premium", "diesel", "e85"],
+          description: "Fuel grade to compare (default: regular)",
+        },
+        limit: { type: "number", description: "Number of results (default: 10)" },
+      },
+    },
+  },
+  {
+    name: "get_favorites",
+    description:
+      "Get a user's saved favorite gas stations with current prices.",
+    inputSchema: {
+      type: "object",
+      required: ["user_id"],
+      properties: {
+        user_id: { type: "string", description: "GasBuddy user ID" },
+      },
+    },
+  },
+  {
+    name: "get_trip_cost",
+    description:
+      "Calculate estimated fuel cost for a road trip based on route distance, vehicle fuel efficiency, and current gas prices along the route.",
+    inputSchema: {
+      type: "object",
+      required: [
+        "origin_latitude",
+        "origin_longitude",
+        "dest_latitude",
+        "dest_longitude",
+        "fuel_efficiency",
+      ],
+      properties: {
+        origin_latitude: { type: "number", description: "Trip start latitude" },
+        origin_longitude: { type: "number", description: "Trip start longitude" },
+        dest_latitude: { type: "number", description: "Trip destination latitude" },
+        dest_longitude: { type: "number", description: "Trip destination longitude" },
+        fuel_efficiency: { type: "number", description: "Vehicle fuel efficiency (MPG or L/100km)" },
+        fuel_efficiency_unit: {
+          type: "string",
+          enum: ["mpg", "l_per_100km"],
+          description: "Unit for fuel efficiency (default: mpg)",
+        },
+        grade: {
+          type: "string",
+          enum: ["regular", "midgrade", "premium", "diesel", "e85"],
+          description: "Fuel grade (default: regular)",
+        },
+        tank_size: { type: "number", description: "Tank size in gallons for stop planning" },
+      },
+    },
+  },
+];
+
+// ---- Server ----
+
+const API_KEY = process.env.GASBUDDY_API_KEY || "";
+const BASE_URL = process.env.GASBUDDY_BASE_URL || "https://api.gasbuddy.com";
+const USER_ID = process.env.GASBUDDY_USER_ID || "";
+
+const client = new GasBuddyClient({ apiKey: API_KEY, baseUrl: BASE_URL });
+
+const server = new Server(
+  { name: "@striderlabs/mcp-gasbuddy", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    switch (name) {
+      case "search_stations": {
+        const result = await client.searchStations({
+          latitude: args.latitude as number | undefined,
+          longitude: args.longitude as number | undefined,
+          address: args.address as string | undefined,
+          radius: args.radius as number | undefined,
+          fuel: args.fuel as string | undefined,
+          limit: args.limit as number | undefined,
+          minRating: args.minRating as number | undefined,
+          amenities: args.amenities as string[] | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "get_station_details": {
+        const result = await client.getStationDetails(args.station_id as string);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "get_prices": {
+        const result = await client.getPrices({
+          stationId: args.station_id as string | undefined,
+          latitude: args.latitude as number | undefined,
+          longitude: args.longitude as number | undefined,
+          radius: args.radius as number | undefined,
+          grade: args.grade as string | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "report_price": {
+        const result = await client.reportPrice({
+          stationId: args.station_id as string,
+          grade: args.grade as string,
+          price: args.price as number,
+          latitude: args.latitude as number | undefined,
+          longitude: args.longitude as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "get_price_trends": {
+        const result = await client.getPriceTrends({
+          stationId: args.station_id as string | undefined,
+          latitude: args.latitude as number | undefined,
+          longitude: args.longitude as number | undefined,
+          grade: args.grade as string | undefined,
+          days: args.days as number | undefined,
+          region: args.region as string | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "get_deals": {
+        const result = await client.getDeals({
+          latitude: args.latitude as number | undefined,
+          longitude: args.longitude as number | undefined,
+          radius: args.radius as number | undefined,
+          type: args.type as string | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "get_pay_with_gasbuddy": {
+        const userId = (args.user_id as string) || USER_ID;
+        if (!userId) throw new Error("user_id is required (or set GASBUDDY_USER_ID env var)");
+        const result = await client.getPayWithGasBuddy(userId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "find_cheapest": {
+        const result = await client.findCheapest({
+          latitude: args.latitude as number,
+          longitude: args.longitude as number,
+          radius: args.radius as number | undefined,
+          grade: args.grade as string | undefined,
+          limit: args.limit as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "get_favorites": {
+        const userId = (args.user_id as string) || USER_ID;
+        if (!userId) throw new Error("user_id is required (or set GASBUDDY_USER_ID env var)");
+        const result = await client.getFavorites(userId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "get_trip_cost": {
+        const result = await client.getTripCost({
+          originLatitude: args.origin_latitude as number,
+          originLongitude: args.origin_longitude as number,
+          destLatitude: args.dest_latitude as number,
+          destLongitude: args.dest_longitude as number,
+          fuelEfficiency: args.fuel_efficiency as number,
+          fuelEfficiencyUnit: args.fuel_efficiency_unit as string | undefined,
+          grade: args.grade as string | undefined,
+          tankSize: args.tank_size as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("@striderlabs/mcp-gasbuddy server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});