leadslokal-mcp 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# LeadsLokal MCP Server
+
+MCP server for LeadsLokal — search, score, and pitch local business leads.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_leads` | Search businesses by category, state, and filters (no_website, no_socials, no_booking, has_phone) |
+| `get_lead_detail` | Fetch full profile by business_id or name + location |
+| `score_opportunity` | Score a lead 0–100 based on gaps and strengths, returns pitch angle |
+| `get_pitch_context` | Personalized pitch hook for website / booking / social / seo |
+
+## Getting an API key
+
+Log in to your LeadsLokal account → **Settings → API Keys → Generate Key**.
+
+Your key starts with `sk-ll-`. Copy it — it's shown only once.
+
+---
+
+## Option A — Remote HTTP (no install required)
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "leadslokal": {
+      "type": "http",
+      "url": "https://leadslokal.com/api/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Option B — Local npm (run via npx)
+
+```json
+{
+  "mcpServers": {
+    "leadslokal": {
+      "command": "npx",
+      "args": ["-y", "leadslokal-mcp"],
+      "env": {
+        "LEADSLOKAL_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Local setup
+
+```bash
+npm install -g leadslokal-mcp
+# or run directly: npx leadslokal-mcp
+```
+
+---
+
+## Example agent workflow
+
+```
+1. search_leads(category="plumbing", state="CA", filters=["no_website"], min_rating=4.0)
+   → returns 127 leads
+
+2. score_opportunity(lead) for each
+   → top 20 high-intent leads
+
+3. get_pitch_context(lead, service_type="website")
+   → "Pacific Flow Services — 4.7★ · 89 reviews, no website = high-value prospect (75/100)"
+   → "Customers are searching but there's no website to land on..."
+```

package/dist/index.js

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// ─── Config ──────────────────────────────────────────────────────────────────
+const BASE_URL = (process.env.LEADSLOKAL_BASE_URL ?? "https://leadslokal.com").replace(/\/$/, "");
+const API_KEY = process.env.LEADSLOKAL_API_KEY ?? "";
+// ─── API helper ──────────────────────────────────────────────────────────────
+async function fetchLeads(path) {
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+    if (API_KEY)
+        headers["Authorization"] = `Bearer ${API_KEY}`;
+    const res = await fetch(`${BASE_URL}${path}`, { headers });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`API error ${res.status}: ${text.slice(0, 200)}`);
+    }
+    return res.json();
+}
+// ─── Scoring ─────────────────────────────────────────────────────────────────
+const BOOKING_CATEGORIES = [
+    "restaurant", "salon", "spa", "nail", "barbershop", "barber",
+    "gym", "yoga", "fitness", "dental", "dentist", "doctor", "medical",
+    "veterinary", "vet", "beauty", "massage", "chiropractor", "therapist",
+];
+function needsBooking(category) {
+    const lower = category.toLowerCase();
+    return BOOKING_CATEGORIES.some((c) => lower.includes(c));
+}
+function isLocked(value) {
+    if (typeof value === "string")
+        return value === "__locked__";
+    if (Array.isArray(value))
+        return value.length > 0 && value[0] === "__locked__";
+    return false;
+}
+function scoreOpportunity(lead) {
+    let score = 0;
+    const tags = [];
+    const gaps = [];
+    const hasWebsite = Boolean(lead.website) && !isLocked(lead.website);
+    const hasSocials = lead.socials.length > 0 &&
+        !lead.socials.some((s) => s.platform === "__locked__");
+    const hasBooking = lead.bookingApps.length > 0 && !isLocked(lead.bookingApps);
+    const rating = lead.reviewRating ?? 0;
+    const reviews = lead.reviewCount ?? 0;
+    const hasPhone = lead.phones.length > 0 && !isLocked(lead.phones);
+    // Website gap — biggest revenue opportunity
+    if (!hasWebsite) {
+        score += 35;
+        tags.push("no_website");
+        gaps.push("no website");
+    }
+    // Social gap
+    if (!hasSocials) {
+        score += 20;
+        tags.push("no_socials");
+        gaps.push("no social media");
+    }
+    // Booking gap — only relevant for appointment-based businesses
+    if (!hasBooking && needsBooking(lead.category)) {
+        score += 20;
+        tags.push("no_booking");
+        gaps.push("no online booking");
+    }
+    // Rating quality — proof of good service makes pitching easier
+    if (rating >= 4.5) {
+        score += 15;
+        tags.push("excellent_rating");
+    }
+    else if (rating >= 4.0) {
+        score += 10;
+        tags.push("good_rating");
+    }
+    else if (rating >= 3.5) {
+        score += 4;
+    }
+    // Review volume — indicates active customer base
+    if (reviews >= 200) {
+        score += 10;
+        tags.push("high_volume");
+    }
+    else if (reviews >= 100) {
+        score += 7;
+    }
+    else if (reviews >= 50) {
+        score += 4;
+    }
+    // Reachable by phone
+    if (hasPhone) {
+        score += 5;
+        tags.push("has_phone");
+    }
+    score = Math.min(score, 100);
+    const label = score >= 65 ? "high" : score >= 35 ? "medium" : "low";
+    // Build a human-readable pitch angle
+    const metricParts = [];
+    if (rating > 0 && reviews > 0) {
+        metricParts.push(`${rating}★ · ${reviews} reviews`);
+    }
+    metricParts.push(...gaps);
+    const pitchAngle = metricParts.length > 0
+        ? `${lead.name} — ${metricParts.join(", ")} = ${label}-value prospect (${score}/100)`
+        : `${lead.name} — score ${score}/100`;
+    return { score, label, pitchAngle, opportunityTags: tags, gaps };
+}
+const SERVICE_LABELS = {
+    website: "website design & development",
+    booking: "online booking & scheduling",
+    social: "social media management",
+    seo: "local SEO & Google presence",
+};
+function getPitchContext(lead, service) {
+    const rating = lead.reviewRating ?? 0;
+    const reviews = lead.reviewCount ?? 0;
+    const category = lead.category;
+    const location = lead.location;
+    const { gaps } = scoreOpportunity(lead);
+    const lines = [];
+    lines.push(`### Pitch hook for ${lead.name}`);
+    lines.push(`**Service:** ${SERVICE_LABELS[service]}`);
+    lines.push(`**Category:** ${category} — ${location}`);
+    if (rating > 0) {
+        lines.push(`**Social proof:** ${rating}★ average across ${reviews} reviews`);
+    }
+    lines.push("");
+    lines.push("**Opening angle:**");
+    switch (service) {
+        case "website": {
+            if (!lead.website || isLocked(lead.website)) {
+                if (reviews >= 100) {
+                    lines.push(`"${lead.name} has ${reviews} Google reviews and a ${rating}★ rating — customers are clearly searching for you online, but there's no website to send them to. Every competitor with a site is capturing those clicks."`);
+                }
+                else {
+                    lines.push(`"${lead.name} has strong reviews but no website — customers looking you up after a recommendation have nowhere to land. A simple site would immediately convert that search traffic."`);
+                }
+                lines.push("");
+                lines.push("**Why they'll listen:** Their Google Business profile is doing the heavy lifting. A website funnels those searches into actual leads.");
+            }
+            else {
+                lines.push(`"${lead.name} already has a web presence — pitch a redesign, SEO audit, or conversion optimization. Lead with their Google rating as proof the demand is there."`);
+            }
+            break;
+        }
+        case "booking": {
+            if (!lead.bookingApps.length || isLocked(lead.bookingApps)) {
+                lines.push(`"${lead.name} is a ${category} with ${reviews} reviews but no way to book online. Customers calling to schedule is friction that costs them business — especially evenings and weekends when the phone is unattended."`);
+                lines.push("");
+                lines.push("**Platform angle:** Suggest a tool that matches their category:");
+                if (category.toLowerCase().includes("restaurant")) {
+                    lines.push("- OpenTable or Resy for reservations");
+                    lines.push("- Toast or Square for online ordering");
+                }
+                else if (["salon", "spa", "nail", "barber", "beauty", "massage"].some((c) => category.toLowerCase().includes(c))) {
+                    lines.push("- Booksy, Vagaro, or Fresha — industry-standard booking");
+                }
+                else if (["gym", "yoga", "fitness"].some((c) => category.toLowerCase().includes(c))) {
+                    lines.push("- Mindbody or Glofox — class scheduling + memberships");
+                }
+                else {
+                    lines.push("- Acuity Scheduling or Calendly — works for any appointment business");
+                }
+            }
+            else {
+                lines.push(`"${lead.name} already uses ${lead.bookingApps.join(", ")}. Pitch additional integrations: email reminders, rebooking campaigns, or a loyalty program."`);
+            }
+            break;
+        }
+        case "social": {
+            if (!lead.socials.length || lead.socials.some((s) => s.platform === "__locked__")) {
+                lines.push(`"${lead.name} has ${reviews} happy customers but zero social presence. Their reviews mention real experiences that could become content — before/afters, testimonials, daily specials. They're leaving audience growth on the table."`);
+                lines.push("");
+                lines.push("**Content angle:** Pull from their review text to show what content would resonate:");
+                lines.push(`- Turn their top reviews into Instagram / Facebook posts`);
+                lines.push(`- ${category} lends itself to visual content — photos and short-form video`);
+            }
+            else {
+                const platforms = lead.socials.map((s) => s.platform).filter((p) => p !== "__locked__");
+                lines.push(`"${lead.name} is on ${platforms.join(", ")}. Pitch a growth retainer: content calendar, paid social ads, or engagement management."`);
+            }
+            break;
+        }
+        case "seo": {
+            lines.push(`"${lead.name} has ${reviews} reviews and a ${rating}★ rating — that's strong social proof Google rewards. With targeted local SEO, you can push them to the top of '${category} near me' searches in ${location}."`);
+            lines.push("");
+            lines.push("**Keyword opportunity:** target searches like:");
+            lines.push(`- "${category} in ${location}"`);
+            lines.push(`- "best ${category} near me"`);
+            lines.push(`- "${category} open now ${location}"`);
+            break;
+        }
+    }
+    lines.push("");
+    lines.push("**Identified gaps:** " + (gaps.length > 0 ? gaps.join(", ") : "none detected"));
+    if (lead.phones.length > 0 && !isLocked(lead.phones)) {
+        lines.push(`**Phone:** ${lead.phones[0]}`);
+    }
+    if (lead.mapsLink) {
+        lines.push(`**Google Maps:** ${lead.mapsLink}`);
+    }
+    return lines.join("\n");
+}
+// ─── MCP Server ──────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "leadslokal",
+    version: "1.0.0",
+});
+// Tool 1: search_leads
+server.tool("search_leads", "Search for enriched local business leads with filters. Returns a list of businesses with contact info, social presence, booking platforms, tech stack, and review metrics.", {
+    category: z.string().describe("Business category to search (e.g. 'plumbing', 'restaurant', 'salon')"),
+    state: z
+        .string()
+        .describe("US state abbreviation or name (e.g. 'CA', 'Texas'). Required."),
+    city: z
+        .string()
+        .optional()
+        .describe("City to narrow the search (applied as a keyword filter)"),
+    filters: z
+        .array(z.enum(["no_website", "no_socials", "no_booking", "has_phone"]))
+        .optional()
+        .describe("Opportunity filters: no_website, no_socials, no_booking, has_phone"),
+    min_rating: z
+        .number()
+        .min(0)
+        .max(5)
+        .optional()
+        .describe("Minimum Google review rating (0-5)"),
+    page: z.number().int().min(1).optional().default(1).describe("Page number"),
+    per_page: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .default(20)
+        .describe("Results per page (max 100)"),
+}, async ({ category, state, city, filters, min_rating, page, per_page }) => {
+    const params = new URLSearchParams();
+    if (category)
+        params.append("category", category);
+    if (state)
+        params.append("state", state);
+    if (city)
+        params.append("q", city);
+    // Map filters to API params
+    const filterSet = new Set(filters ?? []);
+    if (filterSet.has("no_website"))
+        params.set("website", "without");
+    if (filterSet.has("no_socials"))
+        params.set("socials", "without");
+    if (filterSet.has("no_booking"))
+        params.set("booking", "without");
+    params.set("page", String(page ?? 1));
+    params.set("perPage", String(per_page ?? 20));
+    const data = await fetchLeads(`/api/businesses?${params.toString()}`);
+    let leads = data.rows;
+    // Client-side min_rating filter (API doesn't support this natively)
+    if (min_rating != null) {
+        leads = leads.filter((r) => (r.reviewRating ?? 0) >= min_rating);
+    }
+    // If has_phone filter requested, filter client-side
+    if (filterSet.has("has_phone")) {
+        leads = leads.filter((r) => r.phones.length > 0 && !isLocked(r.phones));
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    leads,
+                    total: data.pagination.total,
+                    returned: leads.length,
+                    page: data.pagination.page,
+                    totalPages: data.pagination.totalPages,
+                    analytics: data.analytics,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// Tool 2: get_lead_detail
+server.tool("get_lead_detail", "Get the full profile for a specific business lead, including all contact info, social links, booking platforms, tech stack, and review metrics.", {
+    business_id: z
+        .string()
+        .optional()
+        .describe("Business ID from a previous search_leads result"),
+    name: z
+        .string()
+        .optional()
+        .describe("Business name (used if business_id is not available)"),
+    location: z
+        .string()
+        .optional()
+        .describe("City, state, or address to narrow search by name"),
+}, async ({ business_id, name, location }) => {
+    if (!business_id && !name) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Error: provide either business_id or name.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const params = new URLSearchParams();
+    params.set("perPage", "5");
+    if (name)
+        params.set("q", name);
+    if (location)
+        params.append("q", location);
+    const data = await fetchLeads(`/api/businesses?${params.toString()}`);
+    let match;
+    if (business_id) {
+        match = data.rows.find((r) => r.id === business_id);
+    }
+    if (!match && name) {
+        const nameLower = name.toLowerCase();
+        match =
+            data.rows.find((r) => r.name.toLowerCase() === nameLower) ??
+                data.rows.find((r) => r.name.toLowerCase().includes(nameLower)) ??
+                data.rows[0];
+    }
+    if (!match) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No business found matching "${name ?? business_id}".`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const scored = scoreOpportunity(match);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    lead: match,
+                    opportunityScore: scored.score,
+                    opportunityLabel: scored.label,
+                    opportunityTags: scored.opportunityTags,
+                    gaps: scored.gaps,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// Tool 3: score_opportunity
+server.tool("score_opportunity", "Score a lead's opportunity from 0–100 based on their gaps (no website, no socials, no booking) and strengths (rating, review count, phone). Returns score, label (high/medium/low), pitch angle, and opportunity tags.", {
+    lead: z
+        .object({
+        id: z.string(),
+        name: z.string(),
+        category: z.string(),
+        location: z.string(),
+        phones: z.array(z.string()),
+        website: z.string().nullable(),
+        mapsLink: z.string().nullable(),
+        bookingApps: z.array(z.string()),
+        techStack: z.array(z.string()),
+        socials: z.array(z.object({ platform: z.string(), url: z.string() })),
+        reviewRating: z.number().nullable(),
+        reviewCount: z.number(),
+    })
+        .describe("A lead object from search_leads or get_lead_detail"),
+}, async ({ lead }) => {
+    const result = scoreOpportunity(lead);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// Tool 4: get_pitch_context
+server.tool("get_pitch_context", "Generate a personalized pitch hook for a specific service based on the lead's gaps, category, rating, and reviews. Returns an opening angle, platform recommendations, and reachability info.", {
+    lead: z
+        .object({
+        id: z.string(),
+        name: z.string(),
+        category: z.string(),
+        location: z.string(),
+        phones: z.array(z.string()),
+        website: z.string().nullable(),
+        mapsLink: z.string().nullable(),
+        bookingApps: z.array(z.string()),
+        techStack: z.array(z.string()),
+        socials: z.array(z.object({ platform: z.string(), url: z.string() })),
+        reviewRating: z.number().nullable(),
+        reviewCount: z.number(),
+    })
+        .describe("A lead object from search_leads or get_lead_detail"),
+    service_type: z
+        .enum(["website", "booking", "social", "seo"])
+        .describe("The service you are pitching: website (design/dev), booking (online scheduling), social (social media management), seo (local SEO)"),
+}, async ({ lead, service_type }) => {
+    const pitchContext = getPitchContext(lead, service_type);
+    return {
+        content: [
+            {
+                type: "text",
+                text: pitchContext,
+            },
+        ],
+    };
+});
+// ─── Start ────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "leadslokal-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for LeadsLokal — search, score, and pitch local business leads",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "leadslokal-mcp": "dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}