good-eggs-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# Good Eggs MCP Server
+
+MCP server for Good Eggs grocery shopping automation using Playwright. Search for groceries, manage favorites, add items to cart, and view past orders.
+
+## Features
+
+- **Search Groceries** - Search for any grocery item on Good Eggs
+- **Manage Favorites** - Get, add, and remove favorite items
+- **Get Product Details** - View detailed information about any product
+- **Shopping Cart** - Add and remove items from your shopping cart
+- **Find Freebies** - Find items priced at $0.00 on homepage and fresh-picks
+- **Past Orders** - View your order history and reorder items
+
+## Tools
+
+| Tool                           | Description                                         |
+| ------------------------------ | --------------------------------------------------- |
+| `search_for_grocery`           | Search for groceries by keyword                     |
+| `get_favorites`                | Get your favorite/saved grocery items               |
+| `get_grocery_details`          | Get detailed info about a specific product          |
+| `add_to_cart`                  | Add a product to your shopping cart                 |
+| `search_for_freebie_groceries` | Find free items ($0.00) on homepage and fresh-picks |
+| `get_list_of_past_order_dates` | Get dates of your past orders                       |
+| `get_past_order_groceries`     | Get items from a specific past order                |
+| `add_favorite`                 | Add a product to your favorites                     |
+| `remove_favorite`              | Remove a product from your favorites                |
+| `remove_from_cart`             | Remove a product from your shopping cart            |
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- A Good Eggs account (create one at [goodeggs.com](https://www.goodeggs.com))
+
+### Installation
+
+```bash
+npm install
+npm run build
+```
+
+### Configuration
+
+Set the following environment variables:
+
+| Variable             | Required | Description                     | Default |
+| -------------------- | -------- | ------------------------------- | ------- |
+| `GOOD_EGGS_USERNAME` | Yes      | Your Good Eggs account email    | -       |
+| `GOOD_EGGS_PASSWORD` | Yes      | Your Good Eggs account password | -       |
+| `HEADLESS`           | No       | Run browser in headless mode    | `true`  |
+| `TIMEOUT`            | No       | Browser operation timeout (ms)  | `30000` |
+
+### Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "good-eggs": {
+      "command": "npx",
+      "args": ["-y", "good-eggs-mcp-server"],
+      "env": {
+        "GOOD_EGGS_USERNAME": "your-email@example.com",
+        "GOOD_EGGS_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop to connect.
+
+## Usage Examples
+
+### Search for groceries
+
+```
+"Search for organic apples"
+"Find gluten-free bread"
+"Look for chicken breast"
+```
+
+### View and add favorites
+
+```
+"Show me my favorite items"
+"What are my saved groceries?"
+```
+
+### Add items to cart
+
+```
+"Add 2 of those apples to my cart"
+"Put the organic milk in my basket"
+```
+
+### Check deals
+
+```
+"What deals are available today?"
+"Find any free items"
+```
+
+### Reorder from past orders
+
+```
+"Show me my past orders"
+"What did I order on January 3rd?"
+```
+
+## How It Works
+
+This MCP server uses Playwright to automate a browser session with Good Eggs:
+
+1. **On first tool use**: Launches a browser and logs into your Good Eggs account
+2. **Browser session persists**: All subsequent tool calls reuse the same logged-in session
+3. **Smart navigation**: Tools check if you're already on the right page to minimize navigation
+4. **Stealth mode**: Uses playwright-extra with stealth plugin to avoid bot detection
+
+## Development
+
+```bash
+# Install dependencies
+npm run install-all
+
+# Run in development mode
+npm run dev
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+```
+
+## Project Structure
+
+```
+good-eggs/
+├── local/                 # Local server implementation
+│   └── src/
+│       └── index.ts       # Entry point with env validation
+├── shared/                # Shared business logic
+│   └── src/
+│       ├── server.ts      # GoodEggsClient with Playwright automation
+│       ├── tools.ts       # MCP tool definitions
+│       ├── types.ts       # TypeScript types
+│       └── logging.ts     # Logging utilities
+├── tests/                 # Test suites
+├── package.json           # Root workspace config
+└── README.md
+```
+
+## Security Notes
+
+- Your Good Eggs credentials are used only to log into your account
+- The browser session runs locally on your machine
+- No credentials are transmitted to any third-party services
+- Consider using environment variables rather than hardcoding credentials
+
+## Limitations
+
+- Requires a valid Good Eggs account with delivery service in your area
+- Browser automation may occasionally fail if Good Eggs updates their website
+- Some operations (favorites, past orders) require account login
+
+## License
+
+MIT

package/build/index.integration-with-mock.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Integration Test Server Entry Point with Mock Client Factory
+ *
+ * This file is used for integration testing with a mocked Good Eggs client.
+ * It uses the real MCP server but injects a mock client factory to avoid
+ * actual browser automation during CI tests.
+ *
+ * Note: The mock client is defined inline because TypeScript's rootDir
+ * constraints prevent importing from the tests/ directory.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+/**
+ * Creates a mock Good Eggs client for integration testing.
+ * This is kept inline to avoid TypeScript rootDir issues with importing from tests/.
+ */
+function createMockGoodEggsClient() {
+    const mockConfig = {
+        username: 'test@example.com',
+        password: 'testpassword',
+        headless: true,
+        timeout: 30000,
+    };
+    return {
+        initialize: async () => {
+            // Mock initialization - no-op
+        },
+        searchGroceries: async (_query) => {
+            return [
+                {
+                    url: 'https://www.goodeggs.com/product/123',
+                    name: 'Organic Honeycrisp Apples',
+                    brand: 'From Our Farmers',
+                    price: '$4.99',
+                    discount: '16% OFF',
+                },
+                {
+                    url: 'https://www.goodeggs.com/product/456',
+                    name: 'Organic Fuji Apples',
+                    brand: 'Hikari Farms',
+                    price: '$2.99',
+                },
+            ];
+        },
+        getFavorites: async () => {
+            return [
+                {
+                    url: 'https://www.goodeggs.com/product/789',
+                    name: 'Organic Milk',
+                    brand: 'Clover',
+                    price: '$6.99',
+                },
+            ];
+        },
+        getGroceryDetails: async (_groceryUrl) => {
+            return {
+                url: 'https://www.goodeggs.com/product/123',
+                name: 'Organic Honeycrisp Apples',
+                brand: 'From Our Farmers',
+                price: '$4.99',
+                originalPrice: '$5.97',
+                discount: '16% OFF',
+                description: 'Delicious organic honeycrisp apples from local farmers.',
+                availability: ['Sun 1/4', 'Mon 1/5', 'Tue 1/6'],
+            };
+        },
+        addToCart: async (_groceryUrl, quantity) => {
+            return {
+                success: true,
+                message: `Successfully added ${quantity} x Organic Honeycrisp Apples to cart`,
+                itemName: 'Organic Honeycrisp Apples',
+                quantity,
+            };
+        },
+        searchFreebieGroceries: async () => {
+            return [
+                {
+                    url: 'https://www.goodeggs.com/product/deal1',
+                    name: 'Organic Cauliflower',
+                    brand: 'Lakeside Organic Gardens',
+                    price: '$3.99',
+                    discount: '33% OFF',
+                },
+            ];
+        },
+        getPastOrderDates: async () => {
+            return [
+                {
+                    date: 'January 3, 2025',
+                    total: '$45.67',
+                    itemCount: 12,
+                },
+            ];
+        },
+        getPastOrderGroceries: async (_orderDate) => {
+            return [
+                {
+                    url: 'https://www.goodeggs.com/product/past1',
+                    name: 'Celebration Truffles',
+                    brand: 'Good Eggs Select',
+                    price: '$34.49',
+                },
+            ];
+        },
+        addFavorite: async (_groceryUrl) => {
+            return {
+                success: true,
+                message: 'Successfully added Organic Honeycrisp Apples to favorites',
+                itemName: 'Organic Honeycrisp Apples',
+            };
+        },
+        removeFavorite: async (_groceryUrl) => {
+            return {
+                success: true,
+                message: 'Successfully removed Organic Honeycrisp Apples from favorites',
+                itemName: 'Organic Honeycrisp Apples',
+            };
+        },
+        removeFromCart: async (_groceryUrl) => {
+            return {
+                success: true,
+                message: 'Successfully removed Organic Honeycrisp Apples from cart',
+                itemName: 'Organic Honeycrisp Apples',
+            };
+        },
+        getCurrentUrl: async () => {
+            return 'https://www.goodeggs.com/home';
+        },
+        close: async () => {
+            // Mock close - no-op
+        },
+        getConfig: () => {
+            return mockConfig;
+        },
+    };
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    // Create client factory that returns our mock
+    const clientFactory = () => createMockGoodEggsClient();
+    const { server, registerHandlers } = createMCPServer();
+    await registerHandlers(server, clientFactory);
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/build/index.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError, logWarning } from '../shared/logging.js';
+// =============================================================================
+// ENVIRONMENT VALIDATION
+// =============================================================================
+function validateEnvironment() {
+    const required = [
+        {
+            name: 'GOOD_EGGS_USERNAME',
+            description: 'Your Good Eggs account email address',
+            example: 'user@example.com',
+        },
+        {
+            name: 'GOOD_EGGS_PASSWORD',
+            description: 'Your Good Eggs account password',
+            example: 'your-password',
+        },
+    ];
+    const optional = [
+        {
+            name: 'HEADLESS',
+            description: 'Run browser in headless mode (true/false)',
+            defaultValue: 'true',
+        },
+        {
+            name: 'TIMEOUT',
+            description: 'Default timeout for browser operations in milliseconds',
+            defaultValue: '30000',
+        },
+    ];
+    const missing = required.filter(({ name }) => !process.env[name]);
+    if (missing.length > 0) {
+        logError('validateEnvironment', 'Missing required environment variables:');
+        missing.forEach(({ name, description, example }) => {
+            console.error(`  - ${name}: ${description}`);
+            console.error(`    Example: ${example}`);
+        });
+        if (optional.length > 0) {
+            console.error('\nOptional environment variables:');
+            optional.forEach(({ name, description, defaultValue }) => {
+                const defaultStr = defaultValue ? ` (default: ${defaultValue})` : '';
+                console.error(`  - ${name}: ${description}${defaultStr}`);
+            });
+        }
+        console.error('\n----------------------------------------');
+        console.error('Please set the required environment variables and try again.');
+        console.error('\nExample commands:');
+        missing.forEach(({ name, example }) => {
+            console.error(`  export ${name}="${example}"`);
+        });
+        console.error('----------------------------------------\n');
+        process.exit(1);
+    }
+    // Log configuration
+    const headless = process.env.HEADLESS !== 'false';
+    const timeout = process.env.TIMEOUT || '30000';
+    if (!headless) {
+        logWarning('config', 'Running in non-headless mode - browser window will be visible');
+    }
+    if (process.env.TIMEOUT) {
+        logWarning('config', `Custom timeout configured: ${timeout}ms`);
+    }
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+async function main() {
+    // Step 1: Validate environment variables
+    validateEnvironment();
+    // Step 2: Create server using factory
+    const { server, registerHandlers, cleanup } = createMCPServer();
+    // Step 3: Register all handlers (tools)
+    await registerHandlers(server);
+    // Step 4: Set up graceful shutdown
+    const handleShutdown = async () => {
+        logWarning('shutdown', 'Received shutdown signal, closing browser...');
+        await cleanup();
+        process.exit(0);
+    };
+    process.on('SIGINT', handleShutdown);
+    process.on('SIGTERM', handleShutdown);
+    // Step 5: Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('Good Eggs');
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "good-eggs-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Good Eggs grocery shopping with Playwright automation",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "good-eggs-mcp-server": "./build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "shared/**/*.js",
+    "shared/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:integration",
+    "build:integration": "tsc -p tsconfig.integration.json",
+    "start": "node build/index.js",
+    "dev": "tsx src/index.ts",
+    "predev": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prebuild": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prepublishOnly": "node prepare-publish.js && node ../scripts/prepare-npm-readme.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "stage-publish": "npm version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "playwright": "^1.49.1",
+    "playwright-extra": "^4.3.6",
+    "puppeteer-extra-plugin-stealth": "^2.11.2",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.6",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [],
+  "author": "PulseMCP",
+  "license": "MIT"
+}

package/shared/index.d.ts

@@ -0,0 +1,5 @@
+export { createMCPServer, GoodEggsClient, type IGoodEggsClient, type ClientFactory, } from './server.js';
+export { createRegisterTools } from './tools.js';
+export type { GroceryItem, GroceryDetails, PastOrder, CartResult, GoodEggsConfig, } from './types.js';
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+//# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -0,0 +1,6 @@
+// Core server exports
+export { createMCPServer, GoodEggsClient, } from './server.js';
+// Tools exports
+export { createRegisterTools } from './tools.js';
+// Logging exports (re-exported for convenience)
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';

package/shared/logging.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export declare function logServerStart(serverName: string, transport?: string): void;
+/**
+ * Log an error with context
+ */
+export declare function logError(context: string, error: unknown): void;
+/**
+ * Log a warning
+ */
+export declare function logWarning(context: string, message: string): void;
+/**
+ * Log debug information (only in development)
+ */
+export declare function logDebug(context: string, message: string): void;
+//# sourceMappingURL=logging.d.ts.map

package/shared/logging.js

@@ -0,0 +1,34 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export function logServerStart(serverName, transport = 'stdio') {
+    console.error(`MCP server ${serverName} running on ${transport}`);
+}
+/**
+ * Log an error with context
+ */
+export function logError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[ERROR] ${context}: ${message}`);
+    if (stack) {
+        console.error(stack);
+    }
+}
+/**
+ * Log a warning
+ */
+export function logWarning(context, message) {
+    console.error(`[WARN] ${context}: ${message}`);
+}
+/**
+ * Log debug information (only in development)
+ */
+export function logDebug(context, message) {
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+        console.error(`[DEBUG] ${context}: ${message}`);
+    }
+}

package/shared/server.d.ts

@@ -0,0 +1,120 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GoodEggsConfig, GroceryItem, GroceryDetails, PastOrder, CartResult } from './types.js';
+/**
+ * Good Eggs client interface
+ * Defines all methods for interacting with the Good Eggs grocery store
+ */
+export interface IGoodEggsClient {
+    /**
+     * Initialize the browser and log in to Good Eggs
+     * Must be called before using other methods
+     */
+    initialize(): Promise<void>;
+    /**
+     * Search for groceries
+     */
+    searchGroceries(query: string): Promise<GroceryItem[]>;
+    /**
+     * Get user's favorite items
+     */
+    getFavorites(): Promise<GroceryItem[]>;
+    /**
+     * Get detailed information about a specific grocery item
+     */
+    getGroceryDetails(groceryUrl: string): Promise<GroceryDetails>;
+    /**
+     * Add an item to the shopping cart
+     */
+    addToCart(groceryUrl: string, quantity: number): Promise<CartResult>;
+    /**
+     * Search for freebie/deal groceries
+     */
+    searchFreebieGroceries(): Promise<GroceryItem[]>;
+    /**
+     * Get list of past order dates
+     */
+    getPastOrderDates(): Promise<PastOrder[]>;
+    /**
+     * Get groceries from a specific past order
+     */
+    getPastOrderGroceries(orderDate: string): Promise<GroceryItem[]>;
+    /**
+     * Add an item to favorites
+     */
+    addFavorite(groceryUrl: string): Promise<CartResult>;
+    /**
+     * Remove an item from favorites
+     */
+    removeFavorite(groceryUrl: string): Promise<CartResult>;
+    /**
+     * Remove an item from the cart
+     */
+    removeFromCart(groceryUrl: string): Promise<CartResult>;
+    /**
+     * Get the current page URL
+     */
+    getCurrentUrl(): Promise<string>;
+    /**
+     * Close the browser
+     */
+    close(): Promise<void>;
+    /**
+     * Get the configuration
+     */
+    getConfig(): GoodEggsConfig;
+}
+/**
+ * Good Eggs client implementation using Playwright
+ */
+export declare class GoodEggsClient implements IGoodEggsClient {
+    private browser;
+    private context;
+    private page;
+    private config;
+    private isInitialized;
+    constructor(config: GoodEggsConfig);
+    private ensureBrowser;
+    initialize(): Promise<void>;
+    searchGroceries(query: string): Promise<GroceryItem[]>;
+    getFavorites(): Promise<GroceryItem[]>;
+    getGroceryDetails(groceryUrl: string): Promise<GroceryDetails>;
+    addToCart(groceryUrl: string, quantity: number): Promise<CartResult>;
+    searchFreebieGroceries(): Promise<GroceryItem[]>;
+    getPastOrderDates(): Promise<PastOrder[]>;
+    getPastOrderGroceries(orderDate: string): Promise<GroceryItem[]>;
+    addFavorite(groceryUrl: string): Promise<CartResult>;
+    removeFavorite(groceryUrl: string): Promise<CartResult>;
+    removeFromCart(groceryUrl: string): Promise<CartResult>;
+    getCurrentUrl(): Promise<string>;
+    close(): Promise<void>;
+    getConfig(): GoodEggsConfig;
+}
+export type ClientFactory = () => IGoodEggsClient;
+export declare function createMCPServer(): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;
+    cleanup: () => Promise<void>;
+};
+//# sourceMappingURL=server.d.ts.map