### Start MCP Development Server

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp-servers/README.md

Starts the MCP development server, which includes 8 specialized tools and requires manual initiation.

```bash
npm run start:development

```

--------------------------------

### Start MCP Troubleshooting Server

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp-servers/README.md

Initiates the MCP troubleshooting server for immediate diagnosis of frontend issues. This command is a quick way to get the diagnostic tools running.

```bash
npm run start:troubleshooting

```

--------------------------------

### Start Local Supabase Development Environment

Source: https://github.com/alextorelli/prospectpro/blob/main/README.md

Starts the local Supabase development environment, which includes services like the database and authentication.

```bash
supabase start
```

--------------------------------

### Start MCP Production Server

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp-servers/README.md

Starts the MCP production server, which includes 28 tools and automatically starts when VS Code is launched.

```bash
npm run start:production

```

--------------------------------

### General Utility and Setup Shell Scripts

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/live-tooling-list.txt

A diverse set of shell scripts for various utility tasks and setup procedures. This includes caching, campaign validation, cleanup, installation, and environment resets.

```shell
#!/bin/bash

echo "Caching publishable key..."
# Add caching logic here
echo "Publishable key cached."
```

```shell
#!/bin/bash

echo "Validating campaign setup..."
# Add campaign validation logic
echo "Campaign validation complete."
```

```shell
#!/bin/bash

echo "Cleaning up edge functions..."
# Add cleanup logic for edge functions
echo "Edge functions cleaned up."
```

```shell
#!/bin/bash

echo "Enforcing repository cleanliness..."
# Add checks for clean repository state
echo "Repository cleanliness enforced."
```

```shell
#!/bin/bash

echo "Ensuring Codespace startup..."
# Add logic for Codespace startup procedures
echo "Codespace startup verified."
```

```shell
#!/bin/bash

echo "Ensuring Supabase CLI session..."
# Add logic to ensure active Supabase CLI session
echo "Supabase CLI session confirmed."
```

```shell
#!/bin/bash

echo "Installing Git hooks..."
# Add logic to install Git hooks
echo "Git hooks installed."
```

```shell
#!/bin/bash

echo "Performing post-session tasks..."
# Add post-session commands
echo "Post-session tasks completed."
```

```shell
#!/bin/bash

echo "Running preflight checklist..."
# Add preflight checklist commands
echo "Preflight checklist passed."
```

```shell
#!/bin/bash

echo "Resetting authentication emulator..."
# Add commands to reset auth emulator
echo "Auth emulator reset."
```

```shell
#!/bin/bash

echo "Resetting user campaigns..."
# Add commands to reset user campaigns
echo "User campaigns reset."
```

```shell
#!/bin/bash

echo "Setting up edge authentication (simple)..."
# Add simple edge auth setup logic
echo "Simple edge auth setup complete."
```

```shell
#!/bin/bash

echo "Toggling .gitignore status..."
# Add logic to toggle .gitignore entries
echo ".gitignore status updated."
```

```shell
#!/bin/bash

echo "Running validation suite..."
# Add command to execute the validation suite
echo "Validation suite finished."
```

```shell
#!/bin/bash

echo "Verifying observability setup..."
# Add commands to verify observability tools
echo "Observability verified."
```

--------------------------------

### Install Dependencies and Build Project

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp-servers/README.md

Installs project dependencies and builds the project, specifically ensuring the v4.3.1 null-safe store is bundled. This is a troubleshooting step for blank screens after campaign completion.

```bash
npm install && npm run build
```

--------------------------------

### Start MCP Servers for Development

Source: https://github.com/alextorelli/prospectpro/blob/main/README.md

Starts the MCP (Model Context Protocol) servers for local development purposes. Requires Node.js and npm.

```bash
npm run mcp:start
```

--------------------------------

### Install MCP Dependencies

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp-servers/README.md

Installs dependencies required for the MCP (Multi-Cloud Platform) servers. This command is typically used as a troubleshooting step when MCP servers are not starting.

```bash
npm run mcp:install
```

--------------------------------

### Start Both MCP Servers

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp-servers/README.md

Starts both the production and development MCP servers simultaneously, providing comprehensive development and testing capabilities.

```bash
npm run start:all

```

--------------------------------

### Install Dependencies and Deploy Supabase Functions

Source: https://github.com/alextorelli/prospectpro/blob/main/README.md

Installs project dependencies using npm and deploys Supabase Edge Functions for background discovery and campaign export. Requires Node.js, Supabase CLI, and Vercel CLI.

```bash
npm install
supabase functions deploy business-discovery-background
supabase functions deploy campaign-export-user-aware
supabase functions deploy enrichment-orchestrator
```

--------------------------------

### Clone Repository and Navigate Directory

Source: https://github.com/alextorelli/prospectpro/blob/main/README.md

Clones the ProspectPro repository from GitHub and navigates into the project directory. Requires Git to be installed.

```bash
git clone https://github.com/Alextorelli/ProspectPro.git
cd ProspectPro
```

--------------------------------

### Observability Scripts

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/live-tooling-list.txt

Shell scripts for managing and verifying the observability stack within the project. This includes starting, stopping, and verifying observability services.

```shell
#!/bin/bash

echo "Starting observability stack..."
# Add commands to start observability services (e.g., Prometheus, Grafana)
echo "Observability stack started."
```

```shell
#!/bin/bash

echo "Stopping observability stack..."
# Add commands to stop observability services
echo "Observability stack stopped."
```

--------------------------------

### Deployment and Testing Workflow

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

A script outlining the workflow for deploying and testing core functions. It includes ensuring a Supabase CLI session, deploying functions like `business-discovery-background` and `campaign-export-user-aware`, testing authentication patterns, and finally updating documentation.

```bash
# 1. Ensure Supabase CLI session
source scripts/ensure-supabase-cli-session.sh

# 2. Deploy all core functions
cd /workspaces/ProspectPro/supabase && \
npx --yes supabase@latest functions deploy business-discovery-background && \
npx --yes supabase@latest functions deploy enrichment-orchestrator && \
npx --yes supabase@latest functions deploy campaign-export-user-aware

# 3. Test core functionality
./scripts/test-auth-patterns.sh "$SUPABASE_SESSION_JWT"
./scripts/campaign-validation.sh

# 4. Update documentation
npm run docs:update
```

--------------------------------

### Shell Script: Install Git Hooks

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/repo-GPS/integration-filetree.txt

A script to automate the installation of Git hooks. Git hooks are scripts that Git executes before or after certain events, such as committing or pushing. This script likely copies hook files from a designated directory into the project's `.git/hooks/` directory, ensuring consistent pre-commit or pre-push checks across the team.

```shell
#!/bin/bash

# Script to install Git hooks for the project.
# This script copies hook scripts from a 'hooks' directory to the .git/hooks directory.

HOOKS_DIR="infrastructure/git-hooks"
GIT_HOOKS_DIR=".git/hooks"

# Ensure the Git hooks directory exists
if [ ! -d "$GIT_HOOKS_DIR" ]; then
    echo "Error: .git/hooks directory not found. Are you in a Git repository?"
    exit 1
fi

# Check if the source hooks directory exists
if [ ! -d "$HOOKS_DIR" ]; then
    echo "Error: Git hooks source directory '$HOOKS_DIR' not found."
    exit 1
fi

echo "Installing Git hooks..."

# Find all executable scripts in the HOOKS_DIR and link them to .git/hooks
find "$HOOKS_DIR" -type f -executable -print0 | while IFS= read -r -d $'\0' hook_file;
do
    hook_name=$(basename "$hook_file")
    echo "Linking $hook_name..."
    # Remove existing hook if it exists
    rm -f "$GIT_HOOKS_DIR/$hook_name"
    # Create a symbolic link or copy the file
    ln -s "$(pwd)/$hook_file" "$GIT_HOOKS_DIR/$hook_name"
    # Ensure the link is executable (though the original file should be)
    chmod +x "$GIT_HOOKS_DIR/$hook_name"
done

echo "Git hooks installed successfully."
exit 0

```

--------------------------------

### Roadmap Management Shell Scripts

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/live-tooling-list.txt

Shell scripts for managing project roadmaps. This includes seeding the roadmap, starting epics, and synchronizing epics to GitHub.

```shell
#!/bin/bash

echo "Seeding roadmap data..."
# Add seeding logic here
echo "Roadmap seeded."
```

```shell
#!/bin/bash

EPIC_NAME="new-feature"
echo "Starting epic: ${EPIC_NAME}"
# Add logic to start a new epic
echo "Epic ${EPIC_NAME} started."
```

```shell
#!/bin/bash

echo "Syncing epics to GitHub..."
# Add logic to sync epics with GitHub issues/PRs
echo "Epics synced to GitHub."
```

--------------------------------

### Deno Edge Function Integration Tests Setup

Source: https://context7.com/alextorelli/prospectpro/llms.txt

Sets up the test environment variables and runs Deno integration tests for edge functions. Requires sourcing a local environment script before running tests.

```bash
# Set up test environment variables
source dev-tools/scripts/testing/test-env.local.sh

# Run all edge function tests
deno test --allow-all app/backend/functions/tests/
```

--------------------------------

### Test Business Discovery with cURL

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Executes a POST request to the business-discovery-background Supabase function to test the discovery module. Requires a Supabase URL environment variable.

```bash
curl -X POST "$SUPABASE_URL/functions/v1/business-discovery-background"
```

--------------------------------

### MCP Tool Integration Examples (JavaScript)

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/workflows/observability/instructions.md

Demonstrates how to use the MCP (Monitoring, Control, and Provisioning) toolset for real-time error correlation, performance monitoring of databases, and checking integration health. Assumes the 'mcp' object is globally available.

```javascript
await mcp.supabase_troubleshooting.correlate_errors({
  timeWindowStart: new Date(Date.now() - 3600000).toISOString(),
});

await mcp.supabase.analyze_slow_queries({ thresholdMs: 1000, limit: 20 });
await mcp.supabase.check_pool_health();
await mcp.drizzle_orm.query({ ... });

await mcp.integration_hub.check_integration_health();
```

--------------------------------

### Run Observability Server (Node.js)

Source: https://github.com/alextorelli/prospectpro/blob/main/README.md

Command to start the MCP Observability Server, which exposes various telemetry tools. This is a key component for troubleshooting and monitoring campaign performance.

```bash
npm run start:observability
```

--------------------------------

### TypeScript Discovery Module Supporting Services

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Details the supporting TypeScript service files for the discovery module, including request authentication, business taxonomy, and API integrations for Google Places, Foursquare, and Census targeting.

```typescript
// Supporting Services
/app/backend/functions/_shared/authenticateRequest.ts         # Session JWT validation
/app/backend/functions/_shared/business-taxonomy.ts         # MECE business categories (300+ types)
/app/backend/functions/_shared/google-places-service.ts         # Google Places API integration
/app/backend/functions/_shared/foursquare-service.ts         # Foursquare Places API integration
/app/backend/functions/_shared/census-targeting.ts         # Geographic targeting logic
```

--------------------------------

### TypeScript Enrichment Module Supporting Services

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Lists the supporting TypeScript service files for the enrichment module, covering API clients for Hunter.io and NeverBounce, Cobalt SOS integration, budget controls, and caching mechanisms.

```typescript
// Supporting Services
/app/backend/functions/_shared/hunter-service.ts         # Hunter.io API client with caching
/app/backend/functions/_shared/neverbounce-service.ts         # NeverBounce verification client
/app/backend/functions/_shared/cobalt-sos-service.ts         # Secretary of State filings (cache-first)
/app/backend/functions/_shared/budget-controls.ts         # Tier-based cost management
/app/backend/functions/_shared/enrichment-cache.ts         # 24-hour result caching system
```

--------------------------------

### TypeScript Core Discovery Module Structure

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Illustrates the directory structure for the core discovery module functions in TypeScript. Includes primary discovery functions, optimized/legacy versions, and testing utilities.

```typescript
// Core Discovery Module Functions
/app/backend/functions/business-discovery-background/                    # PRIMARY: Tier-aware async discovery
/app/backend/functions/business-discovery-optimized/                    # Session-aware sync discovery
/app/backend/functions/business-discovery-user-aware/                    # Legacy compatibility discovery
/app/backend/functions/test-business-discovery/                    # Discovery smoke tests
/app/backend/functions/test-google-places/                    # Google Places API testing
```

--------------------------------

### Development Task Automation Scripts

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/workflows/development-workflow/instructions.md

Provides commands for automating daily development tasks. Includes starting the development server with Vite and running a comprehensive full-stack test suite.

```bash
# VS Code Task: "Start Codespace"
# Triggers: Supabase session, project linking, MCP server startup
npm run dev  # Start Vite dev server

# VS Code Task: "Test: Full Stack Validation"
npm run test:all  # Runs Vitest, pgTAP, Deno, MCP Validation
```

--------------------------------

### List Backend Functions for Orchestration

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/reference-scan.txt

This markdown entry lists specific backend functions that are managed by the system architect. It provides examples of function names and their corresponding directory within 'app/backend/functions/'.

```markdown
- **Edge Functions**: `/app/backend/functions/` (business-discovery-background, enrichment-orchestrator, campaign-export-user-aware)
```

--------------------------------

### Execute Enrichment Pipeline Tests

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Runs a bash script to test the entire enrichment pipeline. This script likely simulates data flow through the enrichment services.

```bash
./scripts/test-enrichment-pipeline.sh
```

--------------------------------

### Build and Test MCP Service Layer

Source: https://github.com/alextorelli/prospectpro/blob/main/README.md

Installs dependencies, builds, and tests the MCP (Model Context Protocol) service layer located in the dev-tools/agents/mcp directory. Requires Node.js and npm.

```bash
cd dev-tools/agents/mcp
npm install
npm run build
npm test
```

--------------------------------

### Test Enrichment Orchestration with cURL

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Executes a POST request to the enrichment-orchestrator Supabase function to test the enrichment module. Requires a Supabase URL environment variable.

```bash
curl -X POST "$SUPABASE_URL/functions/v1/enrichment-orchestrator"
```

--------------------------------

### Shell Script for Installing Git Hooks

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/session_store/integration-filetree.txt

The `install-git-hooks.sh` script automates the process of setting up git hooks for the repository. Git hooks are scripts that Git executes before or after certain events, such as committing or pushing. This script likely copies or links hook scripts from a designated directory into the `.git/hooks/` directory of the repository. It uses standard file system operations.

```shell
#!/bin/bash

# This script installs git hooks for the repository.
# It typically involves copying hook scripts from a central location
# (e.g., 'infrastructure/git-hooks/') to the '.git/hooks/' directory.

HOOKS_DIR="./infrastructure/git-hooks"
GIT_HOOKS_DIR=".git/hooks"

if [ ! -d "$GIT_HOOKS_DIR" ]; then
    echo "Error: Not inside a git repository or .git/hooks directory not found."
    exit 1
fi

if [ ! -d "$HOOKS_DIR" ]; then
    echo "Error: Git hooks directory '$HOOKS_DIR' not found."
    exit 1
fi

# Copy or link hook scripts
for hook in "$HOOKS_DIR"/*;
do
    if [ -f "$hook" ]; then
        hook_name=$(basename "$hook")
        echo "Installing hook: $hook_name"
        cp "$hook" "$GIT_HOOKS_DIR/$hook_name"
        chmod +x "$GIT_HOOKS_DIR/$hook_name"
    fi
done

echo "Git hooks installed successfully."

exit 0

```

--------------------------------

### Run npm Scripts for Documentation Automation

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/mmd-shared/guidelines/DOCUMENTATION_STANDARDS.md

These npm scripts automate various documentation tasks, including diagram generation, preparation, and bootstrapping. They help enforce configuration normalization, compliance, and initial diagram seeding. Ensure Node.js and npm are installed.

```bash
npm run docs:generate
npm run docs:prepare
npm run docs:bootstrap
```

--------------------------------

### TypeScript Core Enrichment Module Structure

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Outlines the directory structure for the core enrichment module functions in TypeScript. Features the primary orchestrator and specific service integrations like Hunter.io and NeverBounce.

```typescript
// Core Enrichment Module Functions
/app/backend/functions/enrichment-orchestrator/                    # PRIMARY: Multi-service coordination
/app/backend/functions/enrichment-hunter/                    # Hunter.io email discovery + 24hr caching
/app/backend/functions/enrichment-neverbounce/                    # NeverBounce email verification
/app/backend/functions/enrichment-business-license/                    # Professional licensing data (Enterprise)
/app/backend/functions/enrichment-pdl/                    # People Data Labs integration (Enterprise)
```

--------------------------------

### Production MCP Adapter Implementation

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp/README.md

An example `MCPClientAdapter` implementation for production environments, responsible for creating actual MCP clients using the SDK and managing resource cleanup.

```typescript
class ProductionMCPAdapter implements MCPClientAdapter {
  async createClient(
    serverName: string,
    config: MCPServerConfig
  ): Promise<MCPClient> {
    // Use actual MCP SDK to create clients
    return new ProductionMCPClient(serverName, config);
  }

  async dispose(): Promise<void> {
    // Cleanup MCP SDK resources
  }
}
```

--------------------------------

### MCP Server Configuration Example (JSON)

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp/README.md

Illustrates the structure of an MCP server configuration file. It defines different server environments (development, production) with their respective commands, arguments, environment variables, and timeouts.

```json
{
  "mcpServers": {
    "development": {
      "command": "node",
      "args": ["./dev-server.js"],
      "timeout": 5000
    },
    "production": {
      "command": "python",
      "args": ["-m", "prod_server"],
      "env": { "NODE_ENV": "production" },
      "timeout": 10000
    }
  }
}
```

--------------------------------

### Documentation Update Commands

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Commands to update the system reference and documentation. The `docs:update` command performs a full documentation update, including codebase indexing and system reference regeneration. The `postdeploy` command is used for automatic updates after deployments.

```bash
# Full documentation update (codebase index + system reference)
npm run docs:update

# Update after deployments (automatic via postdeploy hook)
npm run postdeploy
```

--------------------------------

### SQL Migrations for ProspectPro Backend

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/session_store/app-filetree.txt

Contains SQL scripts for database migrations in the ProspectPro backend. These scripts are used to manage schema changes, install database extensions like pgtap, and set up initial database structures.

```sql
-- Migrations for ProspectPro backend

-- Example: Initial schema setup
CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    email TEXT UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Example: Installing pgtap extension
CREATE EXTENSION IF NOT EXISTS pgtap;

```

--------------------------------

### MCP Server Tools (JavaScript)

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/session_store/dev-tools-filetree.txt

JavaScript files defining tools for various MCP servers, including development, integration hub, PostgreSQL, production, and Supabase troubleshooting. These scripts likely handle server setup, configuration, and maintenance tasks.

```javascript
function setupDevelopmentServer(config) {
  console.log('Setting up development server with config:', config);
  // Development-specific setup logic
  return { status: 'development server ready' };
}

module.exports = { setupDevelopmentServer };
```

```javascript
function setupPostgresServer(dbConfig) {
  console.log('Initializing PostgreSQL server with:', dbConfig);
  // PostgreSQL connection and initialization logic
  return { status: 'PostgreSQL server initialized' };
}

module.exports = { setupPostgresServer };
```

--------------------------------

### Shell Script for Launching React DevTools

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/session_store/integration-filetree.txt

The `launch-react-devtools.sh` script is a utility to help developers launch the React Developer Tools. This script might automate the process of opening the standalone DevTools application or configuring the browser environment to connect to it. It simplifies the setup for debugging React applications. It uses standard shell commands.

```shell
#!/bin/bash

# This script launches the React Developer Tools.
# It might open the standalone application or ensure the browser extension is active.

echo "Launching React Developer Tools..."

# Example: Command to open standalone React DevTools (replace with actual command if different)
# open -a "React Developer Tools"

# Or, if it's a browser extension, you might need browser-specific commands
# For Chrome, you might guide the user to chrome://extensions

echo "Please ensure React Developer Tools are installed and accessible."

exit 0

```

--------------------------------

### Build and Deploy Frontend to Production

Source: https://github.com/alextorelli/prospectpro/blob/main/README.md

Builds the frontend application for production and deploys it using Vercel. Requires npm and Vercel CLI.

```bash
npm run build
cd dist && vercel --prod
```

--------------------------------

### Example Migration Rollback SQL

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/workflows/production-ops/instructions.md

Provides an example SQL script for rolling back a migration. This script should contain the inverse operations of the original migration, such as dropping a column that was added.

```sql
-- Create inverse migration immediately
-- Example: If migration adds column, inverse drops column
BEGIN;
  -- Rollback SQL here
  ALTER TABLE campaigns DROP COLUMN IF EXISTS new_column;
COMMIT;
```

--------------------------------

### Prepare Documentation with NPM Script

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/shared/mermaid/guidelines/diagram-guidelines.md

This NPM script prepares documentation by linting diagrams and refreshing documentation references. It also invokes the diagram bundle script.

```bash
npm run docs:prepare
```

--------------------------------

### Hunter.io Email Finder API

Source: https://github.com/alextorelli/prospectpro/blob/main/integration/data/hunter-io.md

This section details the GET /email-finder endpoint for discovering email addresses.

```APIDOC
## GET /v2/email-finder

### Description
This endpoint allows you to find email addresses associated with a given company domain. You can provide either the first and last name or the full name of the individual.

### Method
GET

### Endpoint
`https://api.hunter.io/v2/email-finder`

### Parameters
#### Query Parameters
- **domain** (string) - Required - The company domain (e.g., `example.com`).
- **first_name** (string) - Required (if `full_name` not provided) - The first name of the person.
- **last_name** (string) - Required (if `full_name` not provided) - The last name of the person.
- **full_name** (string) - Required (if `first_name` and `last_name` not provided) - The full name of the person.
- **api_key** (string) - Required - Your Hunter.io API key.
- **company** (string) - Optional - The company name.
- **position** (string) - Optional - The job title.
- **seniority** (string) - Optional - The seniority level (e.g., `junior`, `senior`, `executive`).
- **country** (string) - Optional - The country.
- **confidence_threshold** (integer) - Optional - The minimum confidence score for the returned email.

### Request Example
```bash
curl "https://api.hunter.io/v2/email-finder?domain=example.com&first_name=John&last_name=Doe&api_key=YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the discovered email and related information.
  - **email** (string) - Suggested email address.
  - **score** (integer) - Confidence score for the email (0-100).
  - **domain** (string) - The domain used for discovery.
  - **first_name** (string) - The first name.
  - **last_name** (string) - The last name.
  - **position** (string) - The job title if provided.
  - **seniority** (string) - The seniority level.
  - **department** (string) - The department classification.
  - **linkedin_url** (string) - Public LinkedIn profile URL if available.
  - **twitter** (string) - Twitter handle if available.
  - **phone_number** (string) - Phone number if available.
  - **accept_all** (boolean) - Indicates if the domain accepts all email addresses.
  - **sources** (array) - An array of objects, each containing a `uri` field pointing to the source URL used for validation.
  - **verification** (object) - Contains verification details.
    - **status** (enum) - Verification status (`valid`, `invalid`, `disposable`, `accept_all`, `webmail`, `unknown`).
    - **date** (string) - Verification timestamp in ISO format.

#### Response Example
```json
{
  "data": {
    "email": "john.doe@example.com",
    "score": 95,
    "domain": "example.com",
    "first_name": "John",
    "last_name": "Doe",
    "position": "Software Engineer",
    "seniority": "mid-level",
    "department": "Technology",
    "linkedin_url": "https://www.linkedin.com/in/johndoe",
    "twitter": "@johndoe",
    "phone_number": "+1-555-555-1212",
    "accept_all": false,
    "sources": [
      {
        "uri": "https://www.example.com/contact",
        "extracted_at": "2023-10-27T10:00:00Z",
        "title": "Contact Us - Example Corp"
      }
    ],
    "verification": {
      "status": "valid",
      "date": "2023-10-27T10:05:00Z"
    }
  }
}
```

### Error Handling
- The API may return errors for invalid requests, missing parameters, or authentication issues. Refer to Hunter.io documentation for specific error codes and messages.
```

--------------------------------

### Shell Script for Validating Supabase Architecture

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/session_store/integration-filetree.txt

The `validate-supabase-architecture.sh` script is designed to verify the configuration and setup of the Supabase

--------------------------------

### Context Snapshot Script

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/coverage.md

A shell script designed to capture the current state or context of the development environment. This is useful for diagnostics, debugging, or creating reproducible snapshots of the project's setup.

```bash
# dev-tools/agents/scripts/context-snapshot.sh
# Placeholder for context snapshot script
```

--------------------------------

### NPM Commands for Linting and Building

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/README.md

These NPM commands are used to run linting checks and build the project. They ensure code quality and prepare the project for deployment.

```bash
npm run lint
npm run build
```

--------------------------------

### Infrastructure Script for Schema Check

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/live-tooling-list.txt

A shell script used within the infrastructure setup to check the schema of documentation, likely ensuring consistency or validity.

--------------------------------

### Environment Loading and Configuration Scripts

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/live-tooling-list.txt

Scripts for loading environment variables and configurations, including versioned approaches. These scripts are essential for setting up the application's runtime environment.

```javascript
import dotenv from 'dotenv';
import path from 'path';

function loadEnvironment(envPath = '.env') {
  dotenv.config({ path: path.resolve(process.cwd(), envPath) });
  console.log('Environment loaded successfully.');
}

export { loadEnvironment };
```

```javascript
import fs from 'fs';
import path from 'path';

function loadEnvironmentV2(filePath) {
  try {
    const fullPath = path.resolve(process.cwd(), filePath);
    const envConfig = JSON.parse(fs.readFileSync(fullPath, 'utf-8'));
    Object.keys(envConfig).forEach(key => {
      process.env[key] = envConfig[key];
    });
    console.log('Environment v2 loaded successfully.');
  } catch (error) {
    console.error('Error loading environment v2:', error);
  }
}

export { loadEnvironmentV2 };
```

--------------------------------

### Get Current Environment with EnvironmentContextManager (TypeScript)

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/context/CONTEXTMANAGER_QUICKREF.md

Retrieve the name of the current active environment using EnvironmentContextManager. This function helps in determining the active operational context.

```typescript
import { EnvironmentContextManager } from "./context-manager";

// Get current environment
const env = EnvironmentContextManager.getCurrentEnvironment();
```

--------------------------------

### Frontend TypeScript Configuration and Main Application

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/session_store/app-filetree.txt

Configuration files and the main entry point for the ProspectPro frontend application. Includes TypeScript configurations for Vite and the primary React App component.

```typescript
// app/frontend/tsconfig.node.json
{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true
  },
  "include": ["vite.config.devtools.ts"]
}

// app/frontend/src/main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'
import { AuthProvider } from './contexts/AuthContext'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <AuthProvider>
      <App />
    </AuthProvider>
  </React.StrictMode>
)

// app/frontend/src/App.tsx
import React from 'react'
import Layout from './components/Layout'

function App() {
  return (
    <Layout>
      {/* Route definitions will go here */}
      <h1>ProspectPro Dashboard</h1>
    </Layout>
  )
}

export default App

```

--------------------------------

### Configuration Files

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/live-tooling-list.txt

Various configuration files used by the project, including environment settings, validation rules, and tool-specific configurations like PostCSS and Tailwind CSS.

```json
{
  "NODE_ENV": "development",
  "API_KEY": "your_dev_api_key",
  "DATABASE_URL": "postgres://user:pass@localhost:5432/dbname"
}
```

```json
{
  "allowedDomains": [
    "example.com",
    "api.example.com"
  ],
  "blockedPaths": [
    "/private",
    "/admin"
  ]
}
```

```json
{
  "plugins": {
    "tailwindcss": {},
    "postcss-preset-env": {}
  }
}
```

```json
{
  "compilerOptions": {
    "target": "ES2016",
    "module": "CommonJS",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}
```

```json
{
  "build": {
    "env": {
      "NEXT_PUBLIC_GA_ID": "G-XXXXXXXXXX"
    }
  }
}
```

--------------------------------

### Unit Testing Utilities (TypeScript)

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/session_store/dev-tools-filetree.txt

TypeScript files used for setting up and executing unit tests. `setup.ts` likely contains helper functions or configurations required before running tests, ensuring a consistent test environment.

```typescript
import * as path from 'path';

export async function setupTestEnvironment(): Promise<void> {
  console.log('Setting up test environment...');
  // Initialize mock services, load configurations, etc.
  // Example: Load test data
  // const fixtureData = require('../fixtures/fixture-dataset.json');
  // console.log('Test data loaded:', fixtureData);
  console.log('Test environment setup complete.');
}

// Example usage within a test file:
// setupTestEnvironment().then(() => { /* run tests */ });
```

--------------------------------

### Validate Authentication Patterns

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Executes a bash script to test various authentication patterns, likely using a provided Supabase session JWT. This is used for validation module testing.

```bash
./scripts/test-auth-patterns.sh "$SUPABASE_SESSION_JWT"
```

--------------------------------

### VS Code Task: Deploy Frontend

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/workflows/development-workflow/instructions.md

This task automates the deployment of the frontend by running linting, testing, building, and then deploying to Vercel. It ensures code quality and a smooth production release.

```bash
npm run lint && npm run test && npm run build && vercel --prod
```

--------------------------------

### Vercel Frontend Deployment - Bash

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/workflows/production-ops/instructions.md

Outlines the command for deploying the frontend application to Vercel. This command is typically automated within a CI/CD pipeline and includes linting, testing, building the application, and then deploying to production. It relies on npm scripts and the Vercel CLI.

```bash
# VS Code Task: "Deploy: Full Automated Frontend"
npm run lint && npm test && npm run build && vercel --prod
```

--------------------------------

### Test Session Authentication Validation

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Executes a POST request to the test-new-auth Supabase function to test session authentication and RLS policies. Requires a Supabase URL environment variable.

```bash
curl -X POST "$SUPABASE_URL/functions/v1/test-new-auth"
```

--------------------------------

### Shell Scripts for MCP Service Management

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/repo-GPS/dev-tools-filetree.txt

Collection of shell scripts for managing the MCP service, including starting, stopping, and deploying the service layer. These scripts are essential for operating the MCP infrastructure.

```shell
#!/bin/bash

echo "Starting MCP service..."
# Add commands to start the MCP service here
# Example: pm2 start mcp-service.js

echo "MCP service started."
```

```shell
#!/bin/bash

echo "Stopping MCP service..."
# Add commands to stop the MCP service here
# Example: pm2 stop mcp-service.js

echo "MCP service stopped."
```

```shell
#!/bin/bash

echo "Deploying MCP service layer..."
# Add commands for deploying the MCP service layer here
# Example: docker build -t mcp-service-layer:latest .
# Example: docker push your-registry/mcp-service-layer:latest

echo "MCP service layer deployed."
```

--------------------------------

### Get Place Details - Foursquare Places API

Source: https://github.com/alextorelli/prospectpro/blob/main/integration/data/foursquare-places.md

Retrieves detailed information about a specific place using its Foursquare ID. Supports authentication via an API key and allows for field selection to minimize payload size.

```APIDOC
## GET /places/{fsq_id}

### Description
Retrieves detailed information about a specific place using its Foursquare ID. Supports authentication via an API key and allows for field selection to minimize payload size.

### Method
GET

### Endpoint
`https://api.foursquare.com/v3/places/{fsq_id}`

### Parameters
#### Path Parameters
- **fsq_id** (string) - Required - Unique Foursquare place identifier obtained from Foursquare Places search results.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response. Recommended: `fsq_id,name,categories,location,geocodes,international_phone,website,features,price,rating,stats,delivery,caterings,photos`.

#### Request Body
This endpoint does not accept a request body.

### Request Example
```json
{
  "example": "No request body"
}
```

### Response
#### Success Response (200)
- **fsq_id** (string) - Unique Foursquare place identifier.
- **name** (string) - Business name.
- **location** (object) - Contains address details like `formatted_address`, `address`, `locality`, `region`, `postcode`, `country`.
- **geocodes** (object) - Contains coordinate information like `latitude` and `longitude`.
- **categories** (array<object>) - List of category objects, each with `id` and `name`.
- **international_phone** (string) - International phone number.
- **website** (string) - Website URL.
- **rating** (number) - Foursquare rating (0–10 scale).
- **price** (integer) - Price tier (1–4).
- **stats** (object) - Contains statistics like `total_ratings`.
- **features** (object) - Contains feature flags like `delivery`.
- **delivery** (array<object>) - List of delivery provider URLs.
- **photos** (array<object>) - Photo metadata.

#### Response Example
```json
{
  "fsq_id": "5339e887498d70134303c424",
  "categories": [
    {
      "id": 13000,
      "name": "Coffee Shop",
      "plural_name": "Coffee Shops",
      "short_name": "Coffee Shop",
      "icon": {
        "prefix": "https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
        "suffix": ".png"
      }
    }
  ],
  "chains": [],
  "distance": 285,
  "geocodes": {
    "centroid": {
      "latitude": 34.052235,
      "longitude": -118.243683
    },
    "roof": {
      "latitude": 34.052235,
      "longitude": -118.243683
    }
  },
  "link": "foursquare://places/5339e887498d70134303c424",
  "location": {
    "address": "700 W 7th St",
    "admin_regions": [],
    "cc": "US",
    "city": "Los Angeles",
    "country": "United States",
    "cross_street": "at Figueroa St",
    "formatted_address": "700 W 7th St, Los Angeles, CA 90017, United States",
    "postcode": "90017",
    "region": "CA",
    "state": "CA"
  },
  "name": "Starbucks",
  "related_places": {
    "children": []
  },
  "timezone": "America/Los_Angeles"
}
```

### Error Handling
- **400 Bad Request**: Invalid request parameters or missing required fields.
- **401 Unauthorized**: Invalid or missing API key.
- **404 Not Found**: The specified `fsq_id` does not exist.
- **429 Too Many Requests**: Rate limit exceeded.
```

--------------------------------

### TypeScript Core Validation Module Structure

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Details the directory structure for the core validation module functions in TypeScript, focusing on session diagnostics, RLS validation, and authentication testing suites.

```typescript
// Core Validation Module Functions
/app/backend/functions/test-new-auth/                    # PRIMARY: Session diagnostics & RLS validation
/app/backend/functions/test-official-auth/                    # Supabase reference auth implementation
/app/backend/functions/auth-diagnostics/                    # Authentication testing suite
```

--------------------------------

### Supabase CLI Helper Functions

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/live-tooling-list.txt

Shell script containing helper functions for interacting with the Supabase CLI. This facilitates common Supabase operations within the project's scripts.

--------------------------------

### Execute Discovery Smoke Tests

Source: https://github.com/alextorelli/prospectpro/blob/main/docs/technical/SYSTEM_REFERENCE.md

Runs a bash script to perform smoke tests on the discovery module. This script likely sets up necessary environment variables and calls discovery-related functions.

```bash
source scripts/ensure-supabase-cli-session.sh
./scripts/campaign-validation.sh
```

--------------------------------

### Initialize and Use MCP Client Manager in TypeScript

Source: https://context7.com/alextorelli/prospectpro/llms.txt

This snippet demonstrates the initialization of the MCPClientManager, connecting to different MCP services (production, observability, troubleshooting), and invoking various tools with parameters. It includes error handling and graceful shutdown procedures. Dependencies include the MCPClientManager, ConfigLocator, WorkspaceContext, and TracingTelemetrySink classes.

```typescript
import { MCPClientManager } from './dev-tools/agents/mcp/MCPClientManager';
import { ConfigLocator } from './dev-tools/agents/mcp/ConfigLocator';
import { WorkspaceContext } from './dev-tools/agents/mcp/WorkspaceContext';
import { TracingTelemetrySink } from './dev-tools/agents/mcp/TracingTelemetrySink';

// Initialize MCP client manager with production configuration
const configLocator = new ConfigLocator({
  workspacePath: '/workspace/ProspectPro',
  configOverridePath: process.env.MCP_CONFIG_PATH
});

const workspaceContext = new WorkspaceContext({
  workspacePath: '/workspace/ProspectPro',
  projectName: 'ProspectPro'
});

const telemetrySink = new TracingTelemetrySink({
  serviceName: 'prospectpro-mcp-client',
  endpoint: 'http://localhost:4318/v1/traces'
});

const mcpManager = new MCPClientManager({
  configLocator,
  workspaceContext,
  telemetrySink,
  retryOptions: {
    maxAttempts: 3,
    baseDelayMs: 1000,
    maxDelayMs: 30000,
    backoffMultiplier: 2,
    jitter: true
  }
});

// Initialize and connect to production MCP server
async function initializeMCPServices() {
  try {
    await mcpManager.initialize();
    console.log('MCP Client Manager initialized successfully');

    // Get production server client
    const productionClient = await mcpManager.getClient('production');
    console.log('Connected to production MCP server');

    // List available tools from the server
    const tools = await productionClient.listTools();
    console.log('Available tools:', tools);

    // Call a tool with parameters
    const result = await productionClient.callTool('business-discovery', {
      businessType: 'restaurant',
      location: 'Seattle, WA',
      maxResults: 10
    });
    console.log('Discovery result:', result);

    // Get observability server for telemetry
    const observabilityClient = await mcpManager.getClient('observability');

    // Capture API trace for debugging
    const traceResult = await observabilityClient.callTool('capture_api_trace', {
      apiEndpoint: 'enrichment-orchestrator',
      businessName: 'Acme Corp',
      tierKey: 'PROFESSIONAL'
    });
    console.log('Trace captured:', traceResult);

  } catch (error) {
    console.error('MCP initialization failed:', error);
    throw error;
  }
}

// Graceful shutdown
async function shutdownMCPServices() {
  await mcpManager.disconnectAll();
  console.log('All MCP clients disconnected');
}

// Example: Using MCP troubleshooting server
async function debugCampaignCosts(campaignId: string) {
  const troubleshootingClient = await mcpManager.getClient('troubleshooting');

  // Compare costs across multiple campaigns
  const costComparison = await troubleshootingClient.callTool('compare_campaign_costs', {
    campaignIds: [campaignId, 'campaign_ref1', 'campaign_ref2'],
    includeBreakdown: true
  });

  console.log('Cost comparison:', costComparison);

  // Predict ROI for future campaigns
  const roiPrediction = await troubleshootingClient.callTool('predict_campaign_roi', {
    campaignId,
    projectedConversionRate: 0.15,
    averageDealValue: 5000
  });

  console.log('ROI prediction:', roiPrediction);

  return { costComparison, roiPrediction };
}

// Export for use in application
export { mcpManager, initializeMCPServices, shutdownMCPServices, debugCampaignCosts };

```

--------------------------------

### Workflow Configuration Files

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/context/session_store/dev-tools-filetree.txt

Configuration files (JSON) and instructions (Markdown) for different development workflows, including development, observability, production operations, and system architecture. These define the specific settings and steps for each workflow.

```json
{
  "workflowName": "development",
  "steps": [
    {"name": "setup-environment", "script": "./scripts/setup-dev.sh"},
    {"name": "run-tests", "script": "npm test"}
  ],
  "dependencies": {
    "nodejs": ">=16.0.0"
  }
}
```

```json
{
  "workflowName": "production-ops",
  "steps": [
    {"name": "monitor-services", "script": "./scripts/monitor.sh"},
    {"name": "deploy-update", "script": "./scripts/deploy.sh"}
  ],
  "alerting": {
    "email": "ops@example.com",
    "threshold": "99.9% uptime"
  }
}
```

--------------------------------

### Create New Backend Function Directory

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/workspace/context/session_store/reference-scan.txt

This command demonstrates how to create a new directory for a backend function using `mkdir -p`. It follows the standard project structure of placing new functions within 'app/backend/functions/'.

```bash
mkdir -p app/backend/functions/my-new-function
```

--------------------------------

### Development Scripts with npm

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp/README.md

Common development scripts for managing dependencies, running tests (watch, coverage), building TypeScript, linting, and executing usage examples using `npm`.

```bash
# Install dependencies
npm install

# Run tests
npm test
npm run test:watch
npm run test:coverage

# Build TypeScript
npm run build

# Lint code
npm run lint
npm run lint:fix

# Run usage example
npm run example
```

--------------------------------

### Implement Custom TelemetrySink (TypeScript)

Source: https://github.com/alextorelli/prospectpro/blob/main/dev-tools/agents/mcp/README.md

Provides an example of creating a custom implementation of the TelemetrySink interface for custom observability. It outlines methods for logging info, warnings, errors, and events.

```typescript
// Custom implementation
class MyTelemetrySink implements TelemetrySink {
  info(message: string, properties?: Record<string, any>): void {
    console.log(`[INFO] ${message}`, properties);
  }

  warn(message: string, properties?: Record<string, any>): void {
    console.warn(`[WARN] ${message}`, properties);
  }

  error(
    message: string,
    error?: Error,
    properties?: Record<string, any>
  ): void {
    console.error(`[ERROR] ${message}`, error, properties);
  }

  event(event: TelemetryEvent): void {
    console.log(`[EVENT] ${event.name}`, event.properties);
  }
}
```