fetchpet-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,181 @@
+# Fetch Pet MCP Server
+
+MCP server for Fetch Pet insurance claims management using Playwright automation. Submit claims, track claim status, and view claim details including EOB and invoices.
+
+## Features
+
+- **Prepare Claims** - Fill out claim forms with validation (without submitting)
+- **Submit Claims** - Actually submit prepared claims with explicit user confirmation
+- **View All Claims** - See all claims (active and historical) in a single call
+- **Claim Details** - Get detailed information including EOB and invoice downloads
+
+## Tools
+
+| Tool                      | Description                                                         |
+| ------------------------- | ------------------------------------------------------------------- |
+| `prepare_claim_to_submit` | Prepare a claim form for submission (validates but does NOT submit) |
+| `submit_claim`            | Submit a prepared claim (requires user confirmation token)          |
+| `get_claims`              | Get all claims (both active/pending and historical/completed)       |
+| `get_claim_details`       | Get detailed claim info including EOB and invoice downloads         |
+
+## Setup
+
+### Prerequisites
+
+- Node.js 18+
+- A Fetch Pet account (create one at [fetchpet.com](https://fetchpet.com))
+
+### Environment Variables
+
+| Variable                | Required | Description                        | Default                   |
+| ----------------------- | -------- | ---------------------------------- | ------------------------- |
+| `FETCHPET_USERNAME`     | Yes      | Your Fetch Pet account email       | -                         |
+| `FETCHPET_PASSWORD`     | Yes      | Your Fetch Pet account password    | -                         |
+| `HEADLESS`              | No       | Run browser in headless mode       | `true`                    |
+| `TIMEOUT`               | No       | Browser operation timeout (ms)     | `30000`                   |
+| `FETCHPET_DOWNLOAD_DIR` | No       | Directory to save downloaded files | `/tmp/fetchpet-downloads` |
+
+### Claude Desktop
+
+Make sure you have your Fetch Pet account credentials ready.
+
+Then proceed to the setup instructions below. If this is your first time using MCP Servers, you'll want to make sure you have the [Claude Desktop application](https://claude.ai/download) and follow the [official MCP setup instructions](https://modelcontextprotocol.io/quickstart/user).
+
+#### Manual Setup
+
+You're going to need Node working on your machine so you can run `npx` commands in your terminal. If you don't have Node, you can install it from [nodejs.org](https://nodejs.org/en/download).
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Modify your `claude_desktop_config.json` file to add the following:
+
+```json
+{
+  "mcpServers": {
+    "fetchpet": {
+      "command": "npx",
+      "args": ["-y", "fetchpet-mcp-server"],
+      "env": {
+        "FETCHPET_USERNAME": "your-email@example.com",
+        "FETCHPET_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop and you should be ready to go!
+
+## Usage Examples
+
+### Submit a new claim
+
+```
+"Submit a claim for my dog Buddy - I have an invoice from Test Vet Clinic for $150 dated January 15th for an annual checkup"
+```
+
+The assistant will:
+
+1. Use `prepare_claim_to_submit` to fill out the form
+2. Show you exactly what will be submitted
+3. Ask for your explicit confirmation
+4. Only then call `submit_claim` with the confirmation token
+
+### View claims
+
+```
+"Show me my active claims"
+"What claims are pending?"
+"Show my claim history"
+"What's the status of my recent claims?"
+```
+
+### Get claim details
+
+```
+"Get details for claim ABC123"
+"Download the EOB for my last claim"
+"Show me the invoice for that claim"
+```
+
+## How It Works
+
+This MCP server uses Playwright to automate a browser session with Fetch Pet:
+
+1. **On server start**: Launches a browser in the background and logs into your Fetch Pet account
+2. **Browser session persists**: All subsequent tool calls reuse the same logged-in session
+3. **Smart navigation**: Tools navigate to the appropriate pages as needed
+4. **Stealth mode**: Uses playwright-extra with stealth plugin to avoid bot detection
+
+### Claim Submission Safety
+
+The claim submission process is designed with safety in mind:
+
+1. **`prepare_claim_to_submit`** fills out the form and validates everything but does NOT click submit
+2. It returns a unique confirmation token
+3. **`submit_claim`** requires this token, ensuring explicit user confirmation
+4. Without the correct token, claims cannot be submitted
+
+## Development
+
+```bash
+# Install dependencies
+npm run install-all
+
+# Run in development mode
+npm run dev
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run manual tests (requires real credentials)
+npm run test:manual
+
+# Lint
+npm run lint
+```
+
+## Project Structure
+
+```
+fetchpet/
+├── local/                 # Local server implementation
+│   └── src/
+│       └── index.ts       # Entry point with env validation
+├── shared/                # Shared business logic
+│   └── src/
+│       ├── server.ts      # FetchPetClient 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 Fetch Pet 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
+- Downloaded documents (EOB, invoices) are saved to the configured download directory
+
+## Limitations
+
+- Requires a valid Fetch Pet account
+- Browser automation may occasionally fail if Fetch Pet updates their website
+- Some operations require navigating between pages which takes time
+- The website uses a React app, so dynamic content loading may require waits
+
+## License
+
+MIT

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

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * Integration test entry point that uses a mock client.
+ * This allows testing MCP server functionality without actual browser automation.
+ */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { createRegisterTools } from '../shared/tools.js';
+import { logServerStart, logError } from '../shared/logging.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
+// =============================================================================
+// MOCK CLIENT FOR INTEGRATION TESTS
+// =============================================================================
+class MockFetchPetClient {
+    mockToken = null;
+    async initialize() {
+        // Mock initialization - no actual browser
+    }
+    async prepareClaimToSubmit(petName, invoiceDate, invoiceAmount, providerName, claimDescription, _invoiceFilePath, _medicalRecordsPath) {
+        this.mockToken = 'mock-confirmation-token-12345';
+        return {
+            petName,
+            invoiceDate,
+            invoiceAmount,
+            providerName,
+            claimDescription,
+            isReadyToSubmit: true,
+            validationErrors: [],
+            confirmationMessage: `IMPORTANT: This claim has been prepared but NOT submitted yet.
+
+To submit this claim, call submit_claim with confirmation_token: "${this.mockToken}"
+
+Claim Details:
+- Pet: ${petName}
+- Invoice Date: ${invoiceDate}
+- Amount: ${invoiceAmount}
+- Provider: ${providerName}
+- Description: ${claimDescription}
+
+The user MUST explicitly confirm they want to submit this claim before calling submit_claim.`,
+        };
+    }
+    async submitClaim(confirmationToken) {
+        if (confirmationToken !== this.mockToken) {
+            return {
+                success: false,
+                message: 'Invalid or expired confirmation token',
+            };
+        }
+        this.mockToken = null;
+        return {
+            success: true,
+            message: 'Claim submitted successfully (mock)',
+            claimId: 'MOCK-CLAIM-001',
+            confirmationNumber: 'MOCK-CONF-12345',
+        };
+    }
+    async getClaims() {
+        return [
+            {
+                claimId: 'MOCK-ACTIVE-001',
+                petName: 'Buddy',
+                claimDate: '2025-01-15',
+                claimAmount: '$250.00',
+                status: 'pending',
+                description: 'Annual checkup',
+                providerName: 'Mock Vet Clinic',
+            },
+            {
+                claimId: 'MOCK-ACTIVE-002',
+                petName: 'Luna',
+                claimDate: '2025-01-20',
+                claimAmount: '$175.50',
+                status: 'processing',
+                description: 'Dental cleaning',
+                providerName: 'Pet Dental Care',
+            },
+            {
+                claimId: 'MOCK-HIST-001',
+                petName: 'Buddy',
+                claimDate: '2024-12-01',
+                claimAmount: '$500.00',
+                status: 'approved',
+                description: 'Emergency surgery',
+                providerName: 'Emergency Vet Hospital',
+            },
+            {
+                claimId: 'MOCK-HIST-002',
+                petName: 'Luna',
+                claimDate: '2024-11-15',
+                claimAmount: '$85.00',
+                status: 'paid',
+                description: 'Vaccinations',
+                providerName: 'Mock Vet Clinic',
+            },
+        ];
+    }
+    async getClaimDetails(claimId) {
+        return {
+            claimId,
+            petName: 'Buddy',
+            claimDate: '2025-01-15',
+            claimAmount: '$250.00',
+            status: 'pending',
+            description: 'Annual checkup and vaccinations',
+            providerName: 'Mock Vet Clinic',
+            reimbursementAmount: '$200.00',
+            deductible: '$50.00',
+            copay: '$0.00',
+            eobSummary: 'EOB available for download',
+            invoiceSummary: 'Invoice available for download',
+        };
+    }
+    async getCurrentUrl() {
+        return 'https://my.fetchpet.com/dashboard';
+    }
+    async close() {
+        // Mock cleanup
+    }
+    getConfig() {
+        return {
+            username: 'mock@example.com',
+            password: 'mock-password',
+            headless: true,
+            timeout: 30000,
+            downloadDir: '/tmp/mock-downloads',
+        };
+    }
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+async function main() {
+    const server = new Server({
+        name: 'fetchpet-mcp-server',
+        version: VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Create mock client
+    const mockClient = new MockFetchPetClient();
+    // Register tools with mock client factory
+    const registerTools = createRegisterTools(() => mockClient, async () => {
+        await mockClient.initialize();
+        return mockClient;
+    });
+    registerTools(server);
+    // Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('Fetch Pet (Mock Mode)');
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/build/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError, logWarning } from '../shared/logging.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
+// =============================================================================
+// ENVIRONMENT VALIDATION
+// =============================================================================
+function validateEnvironment() {
+    const required = [
+        {
+            name: 'FETCHPET_USERNAME',
+            description: 'Your Fetch Pet account email address',
+            example: 'user@example.com',
+        },
+        {
+            name: 'FETCHPET_PASSWORD',
+            description: 'Your Fetch Pet 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',
+        },
+        {
+            name: 'FETCHPET_DOWNLOAD_DIR',
+            description: 'Directory to save downloaded documents (EOB, invoices)',
+            defaultValue: '/tmp/fetchpet-downloads',
+        },
+    ];
+    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';
+    const downloadDir = process.env.FETCHPET_DOWNLOAD_DIR || '/tmp/fetchpet-downloads';
+    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`);
+    }
+    if (process.env.FETCHPET_DOWNLOAD_DIR) {
+        logWarning('config', `Custom download directory: ${downloadDir}`);
+    }
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+async function main() {
+    // Step 1: Validate environment variables
+    validateEnvironment();
+    // Step 2: Create server using factory
+    const { server, registerHandlers, cleanup, startBackgroundLogin } = createMCPServer({
+        version: VERSION,
+    });
+    // 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('Fetch Pet');
+    // Step 6: Start background login process
+    // This kicks off Playwright and performs login without blocking the stdio connection.
+    // If login fails, the server will close with an error.
+    logWarning('login', 'Starting background login to Fetch Pet...');
+    startBackgroundLogin((error) => {
+        // Login failed - log error and exit
+        logError('login', `Background login failed: ${error.message}`);
+        logError('login', 'Server shutting down due to authentication failure.');
+        // Clean up and exit with error
+        cleanup()
+            .catch((cleanupError) => {
+            logError('cleanup', `Error during cleanup: ${cleanupError}`);
+        })
+            .finally(() => {
+            process.exit(1);
+        });
+    });
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "fetchpet-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Fetch Pet insurance claims management with Playwright automation",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "fetchpet-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": [
+    "mcp",
+    "fetch",
+    "pet",
+    "insurance",
+    "claims",
+    "playwright"
+  ],
+  "author": "PulseMCP",
+  "license": "MIT"
+}

package/shared/index.d.ts

@@ -0,0 +1,5 @@
+export { createMCPServer, FetchPetClient, type IFetchPetClient, type ClientFactory, type CreateMCPServerOptions, } from './server.js';
+export { createRegisterTools } from './tools.js';
+export type { Claim, ClaimDetails, ClaimSubmissionData, ClaimSubmissionResult, FetchPetConfig, } 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, FetchPetClient, } 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}`);
+    }
+}