### MCP Server Setup

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Guide to setting up the Local Falcon MCP server for live data access, including installation and configuration with an API key.

```APIDOC
## MCP Server Setup

The Local Falcon MCP server enables live data access for geo-grid scans, AI visibility tracking, and account management. Install the server, configure your API key, and add to your MCP settings for full orchestration capabilities.

```bash
# Install MCP server
npm install @local-falcon/mcp
```

```json
// Add to ~/.config/claude/mcp.json
{
  "mcpServers": {
    "local-falcon": {
      "command": "npx",
      "args": ["@local-falcon/mcp"],
      "env": {
        "LOCAL_FALCON_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

```bash
# Get API key from: https://www.localfalcon.com/api/credentials/
# Requires active Local Falcon subscription
# Restart Claude Code after configuration to load MCP server
```
```

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

### Workflow 2: New Location Setup & Analysis

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/references/mcp-workflows.md

This workflow guides through adding a new business location and performing an initial visibility scan to assess its online presence.

```APIDOC
## Workflow 2: New Location Setup & Analysis

### Description
Add a new location and run an initial visibility scan to get a complete visibility assessment with recommendations.

### Steps

1.  **Search for Local Falcon Business Location**
    *   **Purpose:** Search by business name to get the Place ID.
    *   **Method:** (Assumed POST or GET based on function name)
    *   **Endpoint:** `/local-falcon/searchLocalFalconBusinessLocation`
    *   **Query Parameters:**
        *   `query` (string) - Required - Business name and city (e.g., "Business Name City")
        *   `platform` (string) - Required - Platform to search on (e.g., "google")

2.  **Save Local Falcon Business Location to Account**
    *   **Purpose:** Save the location for ongoing tracking.
    *   **Method:** (Assumed POST)
    *   **Endpoint:** `/local-falcon/saveLocalFalconBusinessLocationToAccount`
    *   **Request Body:**
        *   `place_id` (string) - Required - The Place ID obtained from the previous step.

3.  **List Local Falcon Scan Reports**
    *   **Purpose:** Check if any existing scan data is available for the location.
    *   **Method:** GET
    *   **Endpoint:** `/local-falcon/listLocalFalconScanReports`
    *   **Query Parameters:**
        *   `place_id` (string) - Required - The Place ID of the location.
        *   `limit` (integer) - Optional - Maximum number of reports to return (default 10).

4.  **Run Local Falcon Scan**
    *   **Purpose:** Execute an initial scan if no recent scans are found.
    *   **Method:** POST
    *   **Endpoint:** `/local-falcon/runLocalFalconScan`
    *   **Request Body:**
        *   `place_id` (string) - Required - The Place ID of the location.
        *   `keyword` (string) - Required - The keyword to scan for.
        *   `grid_size` (integer) - Required - The size of the scan grid (e.g., 3, 5, 7, ..., 21).
        *   `ai_analysis` (boolean) - Required - Always set to `true` to enable AI Analysis Report.

5.  **Get Local Falcon Report**
    *   **Purpose:** Retrieve and analyze the results of a scan.
    *   **Method:** GET
    *   **Endpoint:** `/local-falcon/getLocalFalconReport`
    *   **Query Parameters:**
        *   `report_key` (string) - Required - The key of the report generated in the previous step.
```

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

### Installation

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Instructions for installing the Local Falcon skill package and copying it to the appropriate directory for AI agent integration.

```APIDOC
## Installation

Install the skill package and copy to your skills directory for Claude Code, Cursor, or VS Code integration.

```bash
# Install via npm
npm install @local-falcon/local-visibility-skill

# Copy to Claude Code skills directory
cp -r node_modules/@local-falcon/local-visibility-skill ~/.config/claude/skills/local-falcon
```
```

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

### Install Local Falcon MCP Server

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/README.md

Installs the @local-falcon/mcp server, which is used for live data analysis and pairing with the local-visibility-skill. This enables the skill to pull real data and provide specific analysis.

```bash
npm install @local-falcon/mcp
```

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

### Intelligent Scan Setup API

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/references/mcp-workflows.md

This API facilitates the setup of local SEO scans through a conversational approach. It gathers context about the business, suggests relevant keywords, determines appropriate scan grids, and centers the scan logic based on business type and customer behavior. The scan is executed with AI analysis enabled by default.

```APIDOC
## Intelligent Scan Setup

### Description
This workflow guides the setup of a local SEO scan by first gathering essential business context. It intelligently suggests keywords based on the business category, determines the optimal grid size and radius based on whether the business is a storefront, service area business (SAB), or hybrid, and applies correct centering logic for the scan. The scan is executed with AI analysis enabled to provide automated insights.

### Methods & Endpoints

1.  **Discover Business Location**
    *   **Method:** GET (or equivalent internal call)
    *   **Endpoint:** `listAllLocalFalconLocations`
        *   **Description:** Retrieves a list of all saved business locations for the account.
    *   **Method:** GET (or equivalent internal call)
    *   **Endpoint:** `searchForLocalFalconBusinessLocation`
        *   **Description:** Searches for a business location to retrieve its Place ID and Google Business Profile (GBP) data if not already saved.

2.  **Suggest Keywords**
    *   **Description:** Based on the GBP category obtained in Step 1, suggest relevant keywords. Example mapping:
        *   Plumber: `plumber near me`, `emergency plumber`, `plumbing services`
        *   Italian Restaurant: `italian restaurant`, `best pasta near me`, `italian food`
        *   HVAC Contractor: `ac repair near me`, `hvac service`, `heating and cooling`
        *   Personal Injury Attorney: `personal injury lawyer`, `car accident attorney`, `injury attorney near me`
        *   Hair Salon: `hair salon near me`, `haircut`, `best salon`
    *   **Agent Prompt Example:** "Your GBP shows you're a [category]. Most customers search for '[primary keyword]' - want to start there, or is there a specific service you want to track?"

3.  **Determine Grid Size & Radius**
    *   **Description:** Based on business type:
        *   **Storefront:** (Has physical address, no service areas) -> 7x7 or 9x9 grid, 0.5-1mi radius.
        *   **SAB:** (Has service areas defined) -> 13x13+, 3-10mi radius.
        *   **Hybrid:** (Has both address and service areas) -> Depends on customer behavior, requires further questioning.
    *   **Agent Prompt Example:** "Do customers come to your location, or do you go to them?"

4.  **Center Point Logic**
    *   **Storefronts:** Use the business address as the center point (automatic).
    *   **SABs:** Center the scan where customers are located, not necessarily the business office.
    *   **Agent Prompt Example:** "For service businesses, we center the scan where your customers are. Where do you get most of your jobs - any particular neighborhood or part of town?"

5.  **Execute Scan with AI Analysis**
    *   **Method:** POST
    *   **Endpoint:** `/runLocalFalconScan`
    *   **Parameters:**
        *   `place_id` (string) - Required - The Place ID of the business location.
        *   `keyword` (string) - Required - The confirmed keyword to scan for.
        *   `platform` (string) - Optional - Default: `google`. The search platform (e.g., `google`, `bing`).
        *   `grid_size` (integer) - Required - The determined grid size (e.g., 7, 9, 13).
        *   `grid_distance` (integer) - Required - The determined scan radius in miles.
        *   `ai_analysis` (boolean) - Required - Set to `true` to enable AI Analysis.
    *   **Request Example:**
        ```json
        {
          "place_id": "ChIJN1t_tDeuEmsRUsoyG83frdw",
          "keyword": "plumber near me",
          "platform": "google",
          "grid_size": 9,
          "grid_distance": 5,
          "ai_analysis": true
        }
        ```
    *   **Agent Prompt Example:** "Running the scan now with AI Analysis enabled - this will give you expert-level insights automatically."

### Campaign Setup Prompt

*   **Trigger:** User has 3+ locations, mentions "track over time" or "monitor", or asks about multiple locations.
*   **Agent Prompt Example:** "Since you have multiple locations, would you like to set this up as a Campaign? That way it runs automatically on a schedule and you can compare locations."
```

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

### Install Local Visibility Skill for Claude/Cursor/VS Code

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/README.md

Installs the local-visibility-skill using npm and copies it to the Claude skills directory for use with AI agents like Claude, Cursor, and VS Code.

```bash
npm install @local-falcon/local-visibility-skill

cp -r node_modules/@local-falcon/local-visibility-skill ~/.config/claude/skills/local-falcon
```

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

### Install Local Falcon MCP Server

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Installs the Local Falcon MCP server, which enables live data access for geo-grid scans, AI visibility tracking, and account management. This is a prerequisite for full orchestration capabilities.

```bash
# Install MCP server
npm install @local-falcon/mcp
```

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

### Intelligent Scan Setup - Conversational Flow

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/references/mcp-workflows.md

This section details the recommended conversational flow for setting up a local SEO scan. It emphasizes gathering context about the business before asking specific questions, leading to a more effective scan configuration. The process involves pulling business information, suggesting keywords, determining grid size based on business type, applying center point logic, and finally executing the scan with AI analysis.

```pseudocode
Agent: [Uses MCP to pull their business info]
Agent: "I see you're a plumber in Dallas. For plumbers, most customers search
        'plumber near me' or 'emergency plumber'. Want to start with one of those?"
Agent: "Since you're a service area business, we should scan a wider area -
        maybe 10 miles. What's the farthest you'd drive for a job?"
```

```pseudocode
Step 1: Pull Context First
listAllLocalFalconLocations → See what they have saved
  ↓
IF saved: Get GBP data (category, address, service areas)
IF not: searchForLocalFalconBusinessLocation → Get Place ID and GBP data
```

```pseudocode
Step 2: Suggest Keywords Based on GBP Category
Agent says: "Your GBP shows you're a [category]. Most customers search for '[primary keyword]' - want to start there, or is there a specific service you want to track?"
```

```pseudocode
Step 3: Determine Grid Based on Business Type
Agent says: "Do customers come to your location, or do you go to them?"
```

```pseudocode
Step 4: Center Point Logic
Agent says: "For service businesses, we center the scan where your customers are. Where do you get most of your jobs - any particular neighborhood or part of town?"
```

```pseudocode
Step 5: Execute with AI Analysis
runLocalFalconScan:
  place_id: [from discovery]
  keyword: [suggested and confirmed]
  platform: google (default) or user's choice
  grid_size: [appropriate for business type]
  grid_distance: [appropriate for service radius]
  ai_analysis: true  ← ALWAYS ENABLE THIS
Agent says: "Running the scan now with AI Analysis enabled - this will give you expert-level insights automatically."
```

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

### Intelligent Scan Setup: Discovery Phase (MCP First)

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/SKILL.md

The discovery phase of the intelligent scan setup prioritizes using MCP tools to gather business context before asking user questions. It involves checking existing locations, examining GBP data, or searching for a new business if none is saved.

```text
1. listAllLocalFalconLocations - See what locations they already have
2. If they have a location saved:
   - Check GBP data: primary category, address, service areas
   - Check existing scan history: what have they scanned before?
3. If they DON'T have a location saved:
   - Ask for business name OR Place ID
   - searchForLocalFalconBusinessLocation to find it
   - Review the GBP data returned
```

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

### List and Get Local Falcon Campaign Reports (JavaScript)

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Lists all existing campaigns or retrieves detailed performance data for a specific campaign. The list function requires a limit for the number of campaigns to return, while the get function requires a campaign key.

```javascript
// List campaigns
listLocalFalconCampaignReports({
  limit: 20
})

// Response
{
  "campaigns": [
    {
      "campaign_key": "cmp_def456",
      "name": "NYC Pizza Locations Weekly",
      "status": "active",
      "last_run": "2024-01-15T00:00:00Z"
    }
  ]
}

// Get specific campaign details
getLocalFalconCampaignReport({
  campaign_key: "cmp_def456"
})

// Response
{
  "campaign_key": "cmp_def456",
  "name": "NYC Pizza Locations Weekly",
  "locations": [
    {
      "name": "Joe's Pizza - Carmine St",
      "solv": 42.0,
      "atrp": 4.2
    },
    {
      "name": "Joe's Pizza - Broadway",
      "solv": 38.0,
      "atrp": 5.1
    }
  ],
  "average_solv": 40.0,
  "trend": "improving"
}
```

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

### List and Get Local Falcon Trend Reports (JavaScript)

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Accesses historical trend data for a specific location and keyword or retrieves detailed trend analysis. The list function requires a place ID and keyword, while the get function requires a trend key.

```javascript
// List trend reports
listLocalFalconTrendReports({
  place_id: "ChIJXRKnm7WAMogREPoyS76GtY0",
  keyword: "pizza near me"
})

// Get trend details
getLocalFalconTrendReport({
  trend_key: "trd_ghi789"
})

// Response structure
{
  "trend_key": "trd_ghi789",
  "place_id": "ChIJXRKnm7WAMogREPoyS76GtY0",
  "keyword": "pizza near me",
  "data_points": [
    { "date": "2024-01-01", "solv": 35.0, "atrp": 5.2 },
    { "date": "2024-01-08", "solv": 38.0, "atrp": 4.8 },
    { "date": "2024-01-15", "solv": 42.0, "atrp": 4.2 }
  ],
  "trend_direction": "improving",
  "change_30_days": "+7.0%",
  "insights": "Steady improvement correlates with increased review velocity"
}
```

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

### Complete Workflow: New Location Analysis (JavaScript)

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

This workflow demonstrates the end-to-end process of adding a new business location and performing a comprehensive visibility analysis using Local Falcon. It includes steps for checking account credits, searching for a business, saving the location, running an AI-powered scan, and retrieving detailed results including AI analysis and recommendations.

```javascript
// Step 1: Check account credits
const account = await viewLocalFalconAccountInformation();
console.log(`Credits available: ${account.credits_available}`);

// Step 2: Search for the business
const searchResults = await searchForLocalFalconBusinessLocation({
  query: "Joe's Pizza Carmine Street New York",
  platform: "google"
});
const placeId = searchResults.results[0].place_id;
const category = searchResults.results[0].primary_category;

// Step 3: Save location to account
await saveLocalFalconBusinessLocationToAccount({
  place_id: placeId,
  platform: "google"
});

// Step 4: Run initial scan with AI analysis
// Grid recommendation based on category:
// - "Pizza Restaurant" = storefront = 9x9, 1mi radius
const scanResult = await runLocalFalconScan({
  place_id: placeId,
  keyword: "pizza near me",  // Suggested based on category
  platform: "google",
  grid_size: 9,
  grid_distance: 1.0,
  ai_analysis: true  // ALWAYS enable
});

// Step 5: Retrieve and analyze results
const report = await getLocalFalconReport({
  report_key: scanResult.report_key
});

console.log(`
Visibility Assessment for ${report.business_name}
================================================
Keyword: ${report.keyword}
ATRP: ${report.metrics.atrp} (lower is better, 1-3 excellent)
SoLV: ${report.metrics.solv}% (% of top-3 positions)
Found In: ${report.metrics.found_in}/${report.metrics.total_grid_points} points

AI Analysis:
${report.ai_analysis.summary}

Recommendations:
${report.ai_analysis.recommendations.join('
')}
`);
```

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

### Get Local Falcon Competitor Reports (JavaScript)

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Analyzes the competitive landscape by listing competitor reports for a given place ID or retrieving a specific competitor analysis report. The list function requires a place ID, while the get function requires a report key.

```javascript
// List competitor reports
getLocalFalconCompetitorReports({
  place_id: "ChIJXRKnm7WAMogREPoyS76GtY0"
})

// Get specific competitor analysis
getLocalFalconCompetitorReport({
  report_key: "cptr_jkl012"
})

// Response structure
{
  "report_key": "cptr_jkl012",
  "your_business": {
    "name": "Joe's Pizza",
    "solv": 42.0,
    "reviews": 2847,
    "rating": 4.5
  },
  "competitors": [
    {
      "name": "Famous Pizza",
      "solv": 28.0,
      "reviews": 1923,
      "rating": 4.3,
      "distance_from_you": "0.3 miles"
    },
    {
      "name": "Tony's Slice",
      "solv": 15.0,
      "reviews": 856,
      "rating": 4.6,
      "distance_from_you": "0.5 miles"
    }
  ],
  "opportunity_areas": ["Northern grid points show weak competition"],
  "review_gap": "+924 reviews vs nearest competitor"
}
```

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

### Competitive Analysis Workflow

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/SKILL.md

Conducts a competitive analysis by fetching competitor reports for a target location. It identifies gaps and opportunities by comparing performance against competitors.

```bash
1. listAllLocalFalconLocations - Get target location
2. getLocalFalconCompetitorReports - List competitor reports
3. getLocalFalconCompetitorReport - Pull specific analysis
4. Identify gaps and opportunities
```

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

### Get Local Falcon Report

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Retrieves detailed results from a completed scan including metrics, competitor data, and grid-level rankings. Use `fieldmask` parameter to optimize response size for specific data needs.

```APIDOC
## GET /local-falcon/local-visibility-skill/getLocalFalconReport

### Description
Retrieves detailed results from a completed scan including metrics, competitor data, and grid-level rankings. Use `fieldmask` parameter to optimize response size for specific data needs.

### Method
GET

### Endpoint
/local-falcon/local-visibility-skill/getLocalFalconReport

### Parameters
#### Query Parameters
- **report_key** (string) - Required - The unique identifier for the scan report.
- **fieldmask** (string) - Optional - A comma-separated list of fields to include in the response, used for optimizing response size (e.g., "report_key,metrics.atrp,metrics.solv").

### Request Example
```json
{
  "report_key": "rpt_abc123",
  "fieldmask": "report_key,metrics.atrp,metrics.solv"
}
```

### Response
#### Success Response (200)
- **report_key** (string) - Unique identifier for the report.
- **place_id** (string) - Google Place ID of the scanned location.
- **business_name** (string) - Name of the business.
- **keyword** (string) - The keyword used for the scan.
- **platform** (string) - The platform scanned.
- **scan_date** (string) - The date and time the scan was performed (ISO 8601 format).
- **metrics** (object) - Scan performance metrics.
  - **atrp** (float) - Average Total Rank Position (lower is better).
  - **arp** (float) - Average Rank Position where appearing.
  - **solv** (float) - Share of Local Voice % (top 3 positions).
  - **found_in** (integer) - Number of grid points where the business appeared.
  - **total_grid_points** (integer) - Total number of grid points scanned.
  - **saiv** (float) - Share of AI Visibility % (for AI platform scans).
  - **mentions** (integer) - Number of mentions (for AI platform scans).
  - **total_queries** (integer) - Total queries analyzed (for AI platform scans).
- **competitors** (array) - List of competitor data.
  - **name** (string) - Competitor's business name.
  - **solv** (float) - Competitor's Share of Local Voice %.
  - **atrp** (float) - Competitor's Average Total Rank Position.
- **ai_analysis** (object) - AI-generated insights and recommendations (if enabled).
  - **summary** (string) - A summary of the AI analysis.
  - **recommendations** (array of strings) - Actionable recommendations.

#### Response Example (Map Scan)
```json
{
  "report_key": "rpt_abc123",
  "place_id": "ChIJXRKnm7WAMogREPoyS76GtY0",
  "business_name": "Joe's Pizza",
  "keyword": "pizza near me",
  "platform": "google",
  "scan_date": "2024-01-15T14:30:00Z",
  "metrics": {
    "atrp": 4.2,
    "arp": 3.1,
    "solv": 42.0,
    "found_in": 68,
    "total_grid_points": 81
  },
  "competitors": [
    {
      "name": "Famous Pizza",
      "solv": 28.0,
      "atrp": 5.8
    }
  ],
  "ai_analysis": {
    "summary": "Strong performance in core service area with opportunity corridors to the north...",
    "recommendations": ["Focus review generation on delivery speed keywords..."]
  }
}
```

#### Response Example (AI Platform Scan)
```json
{
  "report_key": "rpt_abc123",
  "metrics": {
    "saiv": 35.0,
    "mentions": 7,
    "total_queries": 20
  }
}
```
```

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

### MCP Orchestration: New Location Analysis Workflows

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/SKILL.md

This workflow details the steps for analyzing a new business location using MCP tools. It involves searching for the business, saving it to the account, checking existing scan data, running a new scan with AI analysis, and retrieving the results.

```text
1. searchForLocalFalconBusinessLocation - Get Place ID
2. saveLocalFalconBusinessLocationToAccount - Save location
3. listLocalFalconScanReports - Check existing data
4. runLocalFalconScan - Execute scan (ALWAYS enable AI Analysis Report)
5. getLocalFalconReport - Retrieve results
```

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

### Local Falcon Scan Execution with AI Analysis

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/references/mcp-workflows.md

This snippet shows the parameters for executing a Local Falcon scan, emphasizing the `ai_analysis: true` flag. This ensures that automated, expert-level insights are generated alongside the scan results. The function requires a place ID, keyword, and allows for platform, grid size, and distance specifications.

```pseudocode
runLocalFalconScan:
  place_id: [from discovery]
  keyword: [suggested and confirmed]
  platform: google (default) or user's choice
  grid_size: [appropriate for business type]
  grid_distance: [appropriate for service radius]
  ai_analysis: true
```

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

### Run Local Falcon Scan

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Executes a geo-grid visibility scan for a location and keyword. Returns metrics including ATRP, ARP, SoLV, and competitive data. Always enable `ai_analysis` for expert-level automated insights.

```APIDOC
## POST /local-falcon/local-visibility-skill/runLocalFalconScan

### Description
Executes a geo-grid visibility scan for a location and keyword. Returns metrics including ATRP, ARP, SoLV, and competitive data. Always enable `ai_analysis` for expert-level automated insights.

### Method
POST

### Endpoint
/local-falcon/local-visibility-skill/runLocalFalconScan

### Parameters
#### Request Body
- **place_id** (string) - Required - The Google Place ID of the location to scan.
- **keyword** (string) - Required - The keyword to scan for.
- **platform** (string) - Required - The platform to scan (e.g., google, apple, chatgpt, gemini, grok, aimode, gaio).
- **grid_size** (integer) - Optional - The size of the grid for the scan (e.g., 3, 5, 7, 9, 11, 13, 15, 17, 19, 21). Recommended: 7x7 or 9x9 for storefronts, 13x13+ for service area businesses.
- **grid_distance** (float) - Optional - The distance in miles between grid points. Recommended: 0.5-1mi for storefronts, 3-10mi for service area businesses.
- **center_lat** (float) - Optional - Latitude to center the grid scan. Overrides default center based on place_id.
- **center_lng** (float) - Optional - Longitude to center the grid scan. Overrides default center based on place_id.
- **ai_analysis** (boolean) - Required - Set to `true` to enable automated AI insights.

### Request Example
```json
{
  "place_id": "ChIJXRKnm7WAMogREPoyS76GtY0",
  "keyword": "pizza near me",
  "platform": "google",
  "grid_size": 9,
  "grid_distance": 1.0,
  "center_lat": 40.7308,
  "center_lng": -74.0020,
  "ai_analysis": true
}
```

### Response
#### Success Response (200)
- **report_key** (string) - Unique identifier for the generated report.
- **status** (string) - The current status of the scan (e.g., completed).
- **credits_used** (integer) - The number of credits consumed by the scan.
- **message** (string) - A message indicating the outcome of the scan.

#### Response Example
```json
{
  "report_key": "rpt_abc123",
  "status": "completed",
  "credits_used": 1,
  "message": "Scan completed. AI Analysis Report enabled."
}
```
```

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

### Configure Local Falcon MCP Server

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

Configures the Local Falcon MCP server by adding its settings to the Claude MCP configuration file (`~/.config/claude/mcp.json`). This includes specifying the command to run the server and setting the necessary API key.

```json
// Add to ~/.config/claude/mcp.json
{
  "mcpServers": {
    "local-falcon": {
      "command": "npx",
      "args": ["@local-falcon/mcp"],
      "env": {
        "LOCAL_FALCON_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

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

### Workflow 4: Competitive Analysis

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/references/mcp-workflows.md

This workflow helps understand the competitive landscape by analyzing competitor reports and identifying opportunities for improvement.

```APIDOC
## Workflow 4: Competitive Analysis

### Description
Understand the competitive landscape and identify opportunities by analyzing competitor data.

### Steps

1.  **List All Local Falcon Locations**
    *   **Purpose:** Get details for all target locations.
    *   **Method:** GET
    *   **Endpoint:** `/local-falcon/listAllLocalFalconLocations`

2.  **Get Local Falcon Competitor Reports**
    *   **Purpose:** List available competitor analyses for a given location.
    *   **Method:** GET
    *   **Endpoint:** `/local-falcon/getLocalFalconCompetitorReports`
    *   **Query Parameters:**
        *   `place_id` (string) - Required - The Place ID of the location.

3.  **Get Local Falcon Competitor Report**
    *   **Purpose:** Pull detailed competitor data.
    *   **Method:** GET
    *   **Endpoint:** `/local-falcon/getLocalFalconCompetitorReport`
    *   **Query Parameters:**
        *   `report_key` (string) - Required - The key of the specific competitor report.

4.  **Analyze Competitor Data**
    *   Examine competitor SoLV scores, review counts and ratings, geographic coverage patterns, and areas where competitors are weak.

5.  **Identify Opportunities**
    *   Identify opportunity corridors (low competition areas), review gaps to close, and keywords where the business can gain an advantage.
```

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

### Common Parameters

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/references/mcp-workflows.md

Commonly used parameters across various Local Falcon API endpoints for pagination, filtering, and performance optimization.

```APIDOC
## Common Parameters

### Pagination
*   `limit` (integer) - Optional - Number of results per page. Accepts values from 1 to 100. Defaults to 10.
*   `next_token` (string) - Optional - Token provided in the previous response to retrieve the next page of results.

### Filtering
*   `place_id` (string) - Optional - Filter results by a specific Google or Apple Place ID.
*   `keyword` (string) - Optional - Filter results by a keyword (supports loose matching).
*   `grid_size` (integer) - Optional - Filter results by the scan grid size. Accepted values: 3, 5, 7, 9, 11, 13, 15, 17, 19, 21.
*   `platform` (string) - Optional - Filter results by a specific platform (e.g., "google", "chatgpt").
*   `start_date` (string) - Optional - Filter results within a date range, format MM/DD/YYYY.
*   `end_date` (string) - Optional - Filter results within a date range, format MM/DD/YYYY.
*   `campaign_key` (string) - Optional - Filter scans associated with a specific campaign.

### Field Masks (Performance Optimization)
Use `fieldmask` to specify which fields to include in the response, reducing payload size.

**Examples:**
*   `fieldmask=report_key,arp,atrp,solv`
*   `fieldmask=reports.*.report_key,reports.*.date`
```

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

### Local Falcon Account Health Check Workflow

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/references/mcp-workflows.md

This workflow outlines the steps for performing a quick account health check within the Local Falcon system. It involves checking account information for credits and subscription status, listing all saved locations, reviewing active campaigns, and retrieving the most recent campaign report for analysis. The expected output is a summary of the account status, location count, and campaign health.

```pseudocode
1. viewLocalFalconAccountInformation
   → Check credits available, subscription status

2. listAllLocalFalconLocations
   → See all saved locations

3. listLocalFalconCampaignReports
   → Check for active campaigns

4. getLocalFalconCampaignReport (for most recent)
   → Pull latest data for analysis
```

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

### MCP Server Integration Capabilities (JavaScript)

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/AGENTS.md

Details the integration capabilities with the MCP Server, specifying the package name and the supported functionalities like data retrieval, scan execution, and account management. It also includes a method for detecting tool availability.

```javascript
package: @local-falcon/mcp
capabilities: live_data_retrieval, scan_execution, account_management
detection: Check for tool availability (listLocalFalconScanReports, etc.)
```

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

### AI Visibility Audit Workflow (JavaScript)

Source: https://context7.com/local-falcon/local-visibility-skill/llms.txt

This workflow performs a cross-platform AI visibility audit to assess a business's presence across various AI-driven search and content platforms like ChatGPT, Gemini, AI Mode, and Grok. It iterates through specified platforms, runs scans, retrieves reports, and calculates the SAIV (Search AI Visibility) score, providing platform-specific recommendations.

```javascript
// Run scans across all AI platforms
const platforms = ['chatgpt', 'gemini', 'aimode', 'grok', 'gaio'];
const placeId = "ChIJXRKnm7WAMogREPoyS76GtY0";
const keyword = "best pizza in new york";

const results = {};

for (const platform of platforms) {
  const scan = await runLocalFalconScan({
    place_id: placeId,
    keyword: keyword,
    platform: platform,
    ai_analysis: true
  });

  const report = await getLocalFalconReport({
    report_key: scan.report_key
  });

  results[platform] = report.metrics.saiv;
}

console.log(`
AI Visibility Audit - SAIV Scores
=================================
ChatGPT:      ${results.chatgpt}%
Google Gemini: ${results.gemini}%
Google AI Mode: ${results.aimode}%
AI Overviews:  ${results.gaio}%
Grok:          ${results.grok}%

Platform-Specific Recommendations:
- ChatGPT low? → Optimize Bing Places, Foursquare, editorial lists
- Grok low? → Increase X/Twitter presence and engagement
- AI Overviews low? → Get cited on Reddit, Yelp, industry forums
`);
```

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

### Workflow 6: GBP Health Monitoring

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/references/mcp-workflows.md

This workflow monitors Google Business Profile (GBP) for changes and performance trends, providing alerts and remediation recommendations.

```APIDOC
## Workflow 6: GBP Health Monitoring

### Description
Monitor Google Business Profile (GBP) for changes and performance trends, identify issues, and recommend remediation.

### Steps

1.  **List Local Falcon Guard Reports**
    *   **Purpose:** Check the status of monitored locations.
    *   **Method:** GET
    *   **Endpoint:** `/local-falcon/listLocalFalconGuardReports`

2.  **Get Local Falcon Guard Report**
    *   **Purpose:** Pull specific monitoring data for a location.
    *   **Method:** GET
    *   **Endpoint:** `/local-falcon/getLocalFalconGuardReport`
    *   **Query Parameters:**
        *   `place_id` (string) - Required - The Place ID of the location.

3.  **Check GBP Status**
    *   Verify if any recent GBP edits were detected.
    *   Review performance trends (impressions, calls, directions).
    *   Check for any alerts or warnings.

4.  **Remediate Issues**
    *   If issues are found, identify what changed, assess the impact on visibility, and recommend appropriate remediation steps.
```

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

### Run Local Falcon Scan with AI Analysis

Source: https://github.com/local-falcon/local-visibility-skill/blob/main/SKILL.md

Executes a local scan using the Local Falcon tool, ensuring AI analysis is enabled for expert insights. Requires keyword, platform, grid size, grid distance, and calculated center coordinates.

```bash
runLocalFalconScan with:
- keyword: [selected keyword]
- platform: [selected platform]
- grid_size: [appropriate for business type]
- grid_distance: [appropriate for service radius]
- center_lat/center_lng: [calculated center point]
- ai_analysis: true (ALWAYS)
```