LocalLens — Autonomous Local Business Intelligence & Alexa+ MCP Server

Why is this shop losing to its neighbours on Google, and what should it fix first?

India has more than 60 million small businesses, and for clinics, gyms, coaching centres, bakeries and boutiques, "near me" searches on Google Maps decide who gets the walk-in. The owner can see they're behind. They can't see why, or what to fix first.

LocalLens is an AI agent that plans, searches, compares and acts on live search data from SerpApi:

1. Resolves the business on Google Maps (google_maps, search + place details).

2. Finds its real competitors: the businesses Google actually ranks around its coordinates (google_maps with ll).

3. Tracks rank for three real intent searches ("dental clinic in Mangalagiri", "best dental clinic Mangalagiri", "dental clinic near me").

4. Reads reviews for the business and its top 3 competitors (google_maps_reviews): 90-day velocity, owner-reply rate, unanswered negatives, and what customers praise or complain about.

5. Audits the website linked from the listing (HTTPS, mobile, speed, SEO basics).

6. Scores everything into a transparent Visibility Score (0–100), side by side with each competitor.

7. Acts: a prioritised fix list where every fix cites its evidence ("You reply to 5% of reviews; competitors reply to 60%"), a shareable report, and a WhatsApp-ready summary in English and Telugu.

It also has a Scan-an-area mode for web agencies and consultants (one search → every business in a category, ranked by fixable gap), and an MCP server so any agent (Claude, Alexa+, IDE agents) can call it as a tool.

Quick start (≤ 5 commands)

git clone <repo-url> locallens && cd locallens
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
export SERPAPI_KEY=your_key            # optional: without it LocalLens runs on labelled demo data
uvicorn locallens.web.app:app --port 8000     # open http://localhost:8000

MCP server (Streamable HTTP, spec 2025-11-25): python -m locallens.mcp_server → http://127.0.0.1:8765/mcp, then python examples/mcp_client.py. Tests: pytest -q.

Related MCP server: AEO Scanner

🎙️ Amazon Alexa+ Multimodal Companion (/alexa)

When a user asks:

"Alexa, ask LocalLens how Sunrise Dental Care in Mangalagiri is doing against competitors."

1. Self-Hosted MCP Intelligence Server (locallens/mcp_server.py):

   • Exposes streamable HTTP tools (analyze_business_tool, compare_competitors, scan_area_tool, alexa_morning_briefing).

   • Adheres to the latest Model Context Protocol specification (2025-11-25+).

2. Echo Show 10 Multimodal Smart Display Simulator (/alexa):

   • Authentic smart display dark-mode interface featuring circular score gauges, competitive rank badges, and spoken audio synthesis via browser SpeechSynthesis.

3. Nebius Studio NVIDIA H100 Synthesis (/api/nebius/synthesis):

   • Multi-agent competitor reasoning and web reputation synthesis accelerated on NVIDIA H100 Hopper tensor cores (>50 tokens/sec).

4. Instant WhatsApp Lead Digest Generator (/api/whatsapp):

   • Formats one-click wa.me links with bilingual (English + Telugu) action plans for local business owners.

How it uses SerpApi

Every response is cached on disk by its parameters, so re-running an analysis costs 0 searches, and a per-analysis budget (default 14) makes runaway loops impossible. Area scan costs 1 search.

Architecture

flowchart LR
  U[Owner / agency / agent] --> W[Web UI · FastAPI]
  U --> M[MCP server · Streamable HTTP]
  W --> E[LocalLens agent]
  M --> E
  E --> S[SerpApi client<br/>cache · budget · fixtures]
  S --> GM[google_maps]
  S --> GR[google_maps_reviews]
  E --> A[Website audit]
  E --> SC[Visibility Score] --> F[Fix list] --> R[Report · WhatsApp EN/TE]

The Visibility Score

Competitors are scored the same way, except their website isn't audited (presence only), so the comparison is conservative.

Demo data

Without SERPAPI_KEY, LocalLens uses fixtures/: two fictional scenarios (a Mangalagiri dental clinic and a Vijayawada gym) recorded in SerpApi's documented response shapes (python scripts/make_fixtures.py). The UI shows a DEMO DATA badge. With a key, the same code path runs on live Google results.

Project layout

locallens/serp.py      SerpApi client: cache, budget, fixtures
locallens/engine.py    the agent: resolve → competitors → ranks → reviews → audit → score → fixes
locallens/reviews.py   review velocity, reply rate, praise/complaint themes
locallens/scoring.py   Visibility Score
locallens/fixes.py     evidence-backed fix list (+ Telugu)
locallens/report.py    printable HTML report
locallens/web/         FastAPI app + single-page UI
locallens/mcp_server.py  MCP tools: analyze_business_tool, compare_competitors, scan_area_tool
vendor/sitecheck.py    website audit engine (pre-existing, see SUBMISSION.md)

MIT licensed.