@roilab/crm-cli 0.1.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/CHANGELOG.md +195 -25
  2. package/SKILL.md +256 -7
  3. package/SURFACE.txt +237 -69
  4. package/dist/bin/crm.js +28 -2
  5. package/dist/bin/crm.js.map +1 -1
  6. package/dist/src/commands/access.js +104 -0
  7. package/dist/src/commands/access.js.map +1 -0
  8. package/dist/src/commands/brief.js +52 -0
  9. package/dist/src/commands/brief.js.map +1 -0
  10. package/dist/src/commands/chat.js +220 -0
  11. package/dist/src/commands/chat.js.map +1 -0
  12. package/dist/src/commands/commands.js +89 -0
  13. package/dist/src/commands/commands.js.map +1 -0
  14. package/dist/src/commands/comment.js +1 -0
  15. package/dist/src/commands/comment.js.map +1 -1
  16. package/dist/src/commands/generic.js +335 -5
  17. package/dist/src/commands/generic.js.map +1 -1
  18. package/dist/src/commands/integrations.js +236 -0
  19. package/dist/src/commands/integrations.js.map +1 -0
  20. package/dist/src/commands/mention.js +139 -0
  21. package/dist/src/commands/mention.js.map +1 -0
  22. package/dist/src/commands/options.js +21 -1
  23. package/dist/src/commands/options.js.map +1 -1
  24. package/dist/src/commands/rank.js +300 -0
  25. package/dist/src/commands/rank.js.map +1 -0
  26. package/dist/src/commands/report.js +209 -0
  27. package/dist/src/commands/report.js.map +1 -0
  28. package/dist/src/commands/review.js +136 -0
  29. package/dist/src/commands/review.js.map +1 -1
  30. package/dist/src/commands/skill.js +1005 -0
  31. package/dist/src/commands/skill.js.map +1 -0
  32. package/dist/src/commands/task.js +298 -4
  33. package/dist/src/commands/task.js.map +1 -1
  34. package/dist/src/commands/time.js +242 -0
  35. package/dist/src/commands/time.js.map +1 -0
  36. package/dist/src/lib/skillBundles.js +84 -0
  37. package/dist/src/lib/skillBundles.js.map +1 -0
  38. package/dist/src/lib/skillManifest.js +77 -0
  39. package/dist/src/lib/skillManifest.js.map +1 -0
  40. package/dist/src/lib/skillSidecar.js +69 -0
  41. package/dist/src/lib/skillSidecar.js.map +1 -0
  42. package/dist/src/lib/skillWriter.js +162 -0
  43. package/dist/src/lib/skillWriter.js.map +1 -0
  44. package/dist/src/transport/envelope.js +12 -2
  45. package/dist/src/transport/envelope.js.map +1 -1
  46. package/dist/src/transport/http.js +27 -0
  47. package/dist/src/transport/http.js.map +1 -1
  48. package/dist/src/transport/run.js +6 -0
  49. package/dist/src/transport/run.js.map +1 -1
  50. package/dist/src/types.js.map +1 -1
  51. package/dist/src/utils/server-nudge.js +57 -0
  52. package/dist/src/utils/server-nudge.js.map +1 -0
  53. package/dist/src/utils/version-check.js +68 -0
  54. package/dist/src/utils/version-check.js.map +1 -1
  55. package/package.json +58 -57
  56. package/skill-bundles/tools/ahrefs-tool/SKILL.md +134 -0
  57. package/skill-bundles/tools/brightlocal-tool/SKILL.md +154 -0
  58. package/skill-bundles/tools/dataforseo-tool/SKILL.md +118 -0
  59. package/skill-bundles/tools/google-analytics-tool/SKILL.md +143 -0
  60. package/skill-bundles/tools/google-search-console-tool/SKILL.md +133 -0
  61. package/skill-bundles/tools/local-falcon-tool/SKILL.md +142 -0
  62. package/skill-bundles/tools/localseodata-tool/SKILL.md +388 -0
  63. package/skill-bundles/tools/lsa-spy-tool/SKILL.md +113 -0
  64. package/skill-bundles/tools/screaming-frog-tool/SKILL.md +166 -0
  65. package/skill-bundles/tools/semrush-tool/SKILL.md +121 -0
  66. package/skill-bundles/tools/serpapi-tool/SKILL.md +148 -0
  67. package/skill-bundles/tools/task-preflight/SKILL.md +149 -0
  68. package/skill-bundles/tools/tool-routing/SKILL.md +59 -0
  69. package/skill-bundles/tools/whitespark-tool/SKILL.md +129 -0
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: lsa-spy-tool
3
+ description: When the user wants to check Local Services Ads rankings, see who's ranking in LSA results, monitor LSA competitive landscape, or track LSA ranking changes. Trigger on "LSA rankings," "Local Services Ads," "Google Guaranteed," "Google Screened," "who's ranking in LSAs," or "LSA competitors."
4
+ ---
5
+
6
+ # LSA Spy Tool
7
+
8
+ You have direct access to LSA Spy via MCP. This skill tells you WHEN to use each operation and WHAT to do with the results.
9
+
10
+ ## When to Use LSA Spy vs Other Tools
11
+
12
+ | You Need | Use LSA Spy | Use Instead |
13
+ |----------|------------|-------------|
14
+ | Who's ranking in LSA results right now | ✅ | — |
15
+ | LSA ranking changes over time | ✅ | — |
16
+ | Find a specific business in LSA results | ✅ | — |
17
+ | Which markets have LSA coverage | ✅ | — |
18
+ | Map pack / organic rankings | ❌ | Local Falcon |
19
+ | LSA ad setup and optimization strategy | ❌ Use LSA Spy for data, then | `lsa-ads` skill for strategy |
20
+ | Keyword search volume | ❌ | Semrush, Ahrefs |
21
+
22
+ ## Core Workflows
23
+
24
+ ### Check Current LSA Rankings
25
+
26
+ **When:** User asks "who's ranking in LSAs" or "how are we doing in LSAs" for a market.
27
+
28
+ 1. `list_markets` — find the relevant market ID by category + city
29
+ 2. `get_rankings` — current top-ranking businesses with positions
30
+ 3. If looking for a specific business: `find_business` with the business name
31
+
32
+ **What the data tells you:**
33
+ - Position 1-3: These businesses get the vast majority of LSA leads
34
+ - Businesses appearing consistently: Strong review profile + responsiveness + budget
35
+ - Missing from results entirely: Either not running LSAs or profile issues
36
+
37
+ ### Check Who's in a Market
38
+
39
+ **When:** User wants the full competitive landscape, not just who's ranking right now.
40
+
41
+ 1. `list_markets` — find market ID
42
+ 2. `get_businesses` — ALL businesses that have appeared, with average rank and appearance frequency
43
+ 3. Sort by average rank to find consistent top performers
44
+ 4. Look for businesses with high appearance frequency but mediocre rank (they're spending but not optimizing)
45
+
46
+ **What to look for:**
47
+ - Number of total competitors: Saturated markets (50+) vs thin markets (under 15)
48
+ - Average rank spread: Tight (competitive) vs wide (a few businesses dominate)
49
+ - New entrants: Businesses appearing recently that weren't there before
50
+
51
+ ### Monitor Ranking Changes
52
+
53
+ **When:** User wants to track movement — who's going up, who's going down.
54
+
55
+ 1. `list_markets` — find market ID
56
+ 2. `get_ranking_changes` — set days parameter (7 for weekly, 30 for monthly view)
57
+
58
+ **What the changes tell you:**
59
+ - Business moved UP: Likely got more/better reviews, improved responsiveness, or competitors dropped
60
+ - Business moved DOWN: Lost reviews, slow response times, budget issues, or new competitors entered
61
+ - NEW entrant: Fresh competitor — check their review count and rating
62
+ - Business DISAPPEARED: Paused ads, lost Google Guaranteed/Screened badge, or got suspended
63
+
64
+ ### Market Intelligence
65
+
66
+ **When:** User considering entering LSAs or wants strategic overview.
67
+
68
+ 1. `list_markets` — see all tracked markets
69
+ 2. `get_market_details` — see tracked search queries for a specific market
70
+ 3. `get_rankings` + `get_businesses` — understand competitive density
71
+ 4. Cross-reference top rankers' review counts against user's business
72
+
73
+ ## Interpreting LSA Spy Data
74
+
75
+ ### What Drives LSA Rankings
76
+
77
+ LSA rankings are NOT like organic/map pack. The primary factors:
78
+ 1. **Reviews** — count and rating (most important)
79
+ 2. **Responsiveness** — how fast you answer/respond to leads
80
+ 3. **Proximity** — distance from searcher
81
+ 4. **Business hours** — being open when someone searches
82
+ 5. **Budget** — having sufficient weekly budget
83
+ 6. **Badge status** — Google Guaranteed or Google Screened active
84
+
85
+ ### Reading the Rankings
86
+
87
+ | What You See | What It Means |
88
+ |--------------|---------------|
89
+ | Same 3 businesses always in top 3 | They have review + responsiveness advantage — hard to displace without matching both |
90
+ | High turnover in rankings | Market is competitive, small changes in signals cause movement |
91
+ | Business with fewer reviews ranking higher | Likely better responsiveness score or closer proximity |
92
+ | Business disappeared suddenly | Badge issue, budget exhausted, or suspension |
93
+ | Many businesses with similar rank | Tight competition — reviews and responsiveness are the tiebreakers |
94
+
95
+ ### Key Metrics to Track
96
+
97
+ - **Average rank**: Where a business typically appears (lower is better)
98
+ - **Appearance frequency**: How often they show up at all (consistency matters)
99
+ - **Rank trend**: Moving up or down over time
100
+ - **Market density**: Total competitors — affects cost per lead and difficulty
101
+
102
+ ## What to Do Next
103
+
104
+ | What You Found | Next Action | Skill |
105
+ |----------------|-------------|-------|
106
+ | User not ranking in LSAs | Check if LSA profile is set up, verify Google Guaranteed/Screened badge | `lsa-ads` |
107
+ | User ranking but in position 5+ | Diagnose: reviews, responsiveness, budget | `lsa-ads`, `review-management` |
108
+ | Competitor has way more reviews | Build review generation strategy to close gap | `review-management` |
109
+ | User wants to enter a new LSA market | Assess competitive density, review requirements, estimated budget | `lsa-ads` |
110
+ | LSA data needs to go in a client report | Include LSA rankings alongside organic/map pack data | `local-reporting` |
111
+ | Want to compare LSA vs organic visibility | Run Local Falcon scan for same keywords | `local-falcon-tool` |
112
+
113
+ **Default next step:** LSA rankings without review context are incomplete. Always check the user's review count and rating against the top 3 LSA competitors before making recommendations.
@@ -0,0 +1,166 @@
1
+ ---
2
+ name: screaming-frog-tool
3
+ description: When the user wants a technical site audit, crawl data analysis, location page quality checks, duplicate content detection, schema validation at scale, or internal linking analysis. Trigger on "Screaming Frog," "site crawl," "technical audit," "crawl data," "broken links," "duplicate content," "location page audit," or when analyzing exported crawl CSV/Excel files.
4
+ ---
5
+
6
+ # Screaming Frog Tool
7
+
8
+ Screaming Frog is a desktop crawler with community-built MCP servers available. Even without MCP, the agent can analyze exported crawl data (CSV/Excel). This is your primary technical SEO audit tool.
9
+
10
+ ## When to Use Screaming Frog vs Other Tools
11
+
12
+ | You Need | Use Screaming Frog | Use Instead |
13
+ |----------|-------------------|-------------|
14
+ | Full technical site crawl | ✅ Most detailed crawler | Semrush site audit (lighter) |
15
+ | Location page quality audit at scale | ✅ Best for this | — |
16
+ | Custom data extraction (NAP, schema fields) | ✅ Unique capability | — |
17
+ | Duplicate content detection | ✅ | — |
18
+ | Internal linking analysis | ✅ | — |
19
+ | Redirect chain detection | ✅ | — |
20
+ | Schema validation per page | ✅ Custom extraction | — |
21
+ | Missing titles/metas across hundreds of pages | ✅ | — |
22
+ | Keyword rankings | ❌ | Local Falcon, Semrush |
23
+ | Backlink data | ❌ | Ahrefs |
24
+ | Search traffic data | ❌ | GSC, GA4 |
25
+ | Citation data | ❌ | BrightLocal |
26
+
27
+ ## How the Agent Interacts with Screaming Frog
28
+
29
+ ### With MCP Connected
30
+ The agent can trigger crawls and read results directly.
31
+
32
+ ### Without MCP (More Common)
33
+ The user runs the crawl locally and exports data. The agent analyzes the exported CSV/Excel files.
34
+
35
+ **Tell the user what to export:**
36
+ 1. Run the crawl in Screaming Frog
37
+ 2. Export: Internal > All (CSV)
38
+ 3. If needed: Bulk Export > specific reports (response codes, directives, schema, etc.)
39
+ 4. Upload the CSV to the conversation
40
+
41
+ ## Core Workflows
42
+
43
+ ### Location Page Technical Audit
44
+
45
+ **When:** User has a multi-location site and needs to verify all location pages are technically sound.
46
+
47
+ **What to check in crawl data:**
48
+
49
+ | Check | Where to Find | What's Wrong If... |
50
+ |-------|--------------|-------------------|
51
+ | Title tags | Title 1 column | Duplicate titles across locations, missing titles, truncated titles |
52
+ | Meta descriptions | Meta Description 1 | Duplicate metas, missing metas, boilerplate metas |
53
+ | H1 tags | H1-1 column | Missing H1, duplicate H1s, H1 doesn't include service + city |
54
+ | Word count | Word Count column | Under 300 words = thin content (Google may not index) |
55
+ | Status codes | Status Code column | 404 errors, 302 redirects (should be 301), 5xx errors |
56
+ | Canonical tags | Canonical Link Element 1 | Self-referencing canonical missing, or canonical pointing to wrong page |
57
+ | Internal links in | Inlinks column | 0 or 1 internal links = orphan page |
58
+ | Schema present | Custom extraction needed | No LocalBusiness schema on location pages |
59
+ | NAP on page | Custom extraction needed | Missing or inconsistent NAP |
60
+ | Page speed | PageSpeed tab (if PSI integration enabled) | LCP > 2.5s, CLS > 0.1 |
61
+
62
+ ### Custom Extraction for Local SEO
63
+
64
+ **What to tell the user to configure:**
65
+
66
+ **LocalBusiness Schema Extraction:**
67
+ - Extraction: CSS Selector or XPath
68
+ - Target: `script[type="application/ld+json"]`
69
+ - This extracts the full JSON-LD block — agent can then validate schema fields
70
+
71
+ **NAP Extraction:**
72
+ - Business name: CSS selector for the element containing business name
73
+ - Phone: CSS selector for tel: links
74
+ - Address: CSS selector for address block
75
+
76
+ **Per-page schema validation the agent should do:**
77
+ 1. Is `@type` correct? (e.g., Dentist, Plumber, LocalBusiness)
78
+ 2. Does `name` match GBP exactly?
79
+ 3. Does `address` match GBP exactly?
80
+ 4. Does `telephone` match GBP exactly?
81
+ 5. Are `openingHoursSpecification` present?
82
+ 6. Are `geo` coordinates present and correct?
83
+ 7. Is `areaServed` present (for SABs)?
84
+
85
+ ### Duplicate Content Detection
86
+
87
+ **When:** Multi-location sites often have boilerplate location pages with only the city name changed.
88
+
89
+ **What to check:**
90
+ - Near-duplicate detection (Screaming Frog has this built in)
91
+ - Word count column — if all location pages are exactly the same word count, they're probably templated
92
+ - Title tag patterns — if all titles are "[Service] in [City] | [Brand]" with identical supporting content, Google may not index them all
93
+
94
+ **What "unique enough" looks like:**
95
+ - Unique intro paragraph mentioning specific area landmarks, neighborhoods, demographics
96
+ - Unique service details relevant to that location
97
+ - Unique testimonials or case studies from that area
98
+ - Different photos per location
99
+ - Unique FAQ based on common questions from that area's customers
100
+
101
+ ### Internal Linking Analysis
102
+
103
+ **When:** Location pages aren't getting organic traffic and you suspect they're orphaned or poorly linked.
104
+
105
+ **What to check:**
106
+ - **Inlinks column**: How many internal pages link to each location page
107
+ - **Crawl depth**: How many clicks from homepage to reach each location page
108
+ - **Link structure**: Are location pages linked from the main navigation, footer, or buried?
109
+
110
+ **Healthy internal linking for location pages:**
111
+ - Every location page linked from a locations index/directory page
112
+ - Location pages linked from service pages (where relevant)
113
+ - Location pages linked from each other (nearby locations)
114
+ - Crawl depth: Max 3 clicks from homepage
115
+
116
+ ### Redirect Audit
117
+
118
+ **When:** User migrated sites, changed URLs, or has old location pages that redirected.
119
+
120
+ **What to check:**
121
+ - 302 redirects (should usually be 301 for permanent moves)
122
+ - Redirect chains (A → B → C → D — should be A → D)
123
+ - Redirect loops (A → B → A)
124
+ - Old location URLs that 404 instead of redirecting
125
+
126
+ ## Interpreting Crawl Data for Local SEO
127
+
128
+ ### Priority Issues (Fix First)
129
+
130
+ | Issue | Impact | How to Find |
131
+ |-------|--------|------------|
132
+ | Location pages returning 404 | Pages completely invisible | Status Code = 404, filter to location URLs |
133
+ | Location pages not in sitemap | Google may not discover them | Cross-reference sitemap URLs with crawled URLs |
134
+ | Location pages blocked by robots.txt | Google can't crawl them | Indexability column = "Blocked by Robots.txt" |
135
+ | Location pages with noindex | Google won't index them | Meta Robots column contains "noindex" |
136
+
137
+ ### Important Issues (Fix Next)
138
+
139
+ | Issue | Impact | How to Find |
140
+ |-------|--------|------------|
141
+ | Duplicate titles across locations | Google may suppress duplicates | Title 1 column — sort and find duplicates |
142
+ | Thin content (under 300 words) | Google may not index | Word Count column < 300 |
143
+ | Missing schema | Losing structured data signals | Custom extraction shows empty |
144
+ | Orphan pages (0-1 internal links) | Low crawl priority, low authority | Inlinks column = 0 or 1 |
145
+
146
+ ### Maintenance Issues (Fix When Possible)
147
+
148
+ | Issue | Impact | How to Find |
149
+ |-------|--------|------------|
150
+ | Missing meta descriptions | Lower CTR from search results | Meta Description 1 = empty |
151
+ | Images without alt text | Accessibility + minor SEO signal | Images tab, Alt Text column empty |
152
+ | Redirect chains | Wasted crawl budget, slow page loads | Redirect Chains report |
153
+
154
+ ## What to Do Next
155
+
156
+ | What You Found | Next Action | Skill |
157
+ |----------------|-------------|-------|
158
+ | Location pages with thin content | Rewrite with unique, substantial content per location | `local-landing-pages` |
159
+ | Missing schema on location pages | Implement LocalBusiness schema | `local-schema` |
160
+ | Duplicate titles/metas | Rewrite with unique, keyword-targeted titles per location | `local-landing-pages` |
161
+ | Orphan location pages | Fix internal linking structure | `local-landing-pages` |
162
+ | Indexing issues (noindex, robots.txt, missing from sitemap) | Fix technical issues | `local-seo-audit` |
163
+ | NAP inconsistencies found via custom extraction | Fix on-page NAP to match GBP exactly | `gbp-optimization`, `local-citations` |
164
+ | All technical issues documented | Package into audit report for client | `client-deliverables` |
165
+
166
+ **Default next step:** Screaming Frog crawl data is a goldmine but it's raw. Always prioritize: indexing blockers → content issues → structural issues → optimization opportunities.
@@ -0,0 +1,121 @@
1
+ ---
2
+ name: semrush-tool
3
+ description: When the user wants keyword research with search volume, competitive keyword analysis, site audit data, position tracking, or competitor organic analysis. Trigger on "keyword research," "search volume," "keyword difficulty," "what keywords do they rank for," "site audit," "Semrush," or "competitive analysis." Use Semrush for keyword data and competitive intelligence — use Ahrefs for backlink-focused analysis.
4
+ ---
5
+
6
+ # Semrush Tool
7
+
8
+ > **Note:** LocalSEOData (`localseodata-tool`) now covers keyword suggestions, search volume, keyword trends, and keyword opportunities. Use LocalSEOData as default. Semrush remains the stronger choice for advanced keyword gap analysis, Keyword Magic Tool, and combined keyword + site audit workflows.
9
+
10
+ Semrush has an official MCP server. When connected, use it for keyword research, competitive organic analysis, and technical site audits. This is your primary keyword intelligence tool.
11
+
12
+ ## When to Use Semrush vs Other Tools
13
+
14
+ | You Need | Use Semrush | Use Instead |
15
+ |----------|------------|-------------|
16
+ | Keyword search volume for local terms | ✅ Best for this | — |
17
+ | Keyword difficulty scores | ✅ | Ahrefs (different scale, both valid) |
18
+ | What keywords a competitor ranks for | ✅ Best for this | — |
19
+ | Keyword gap (you vs competitor) | ✅ Best for this | — |
20
+ | Backlink analysis | ⚠️ Decent but not best | Ahrefs (larger index) |
21
+ | Link intersect / link gap | ⚠️ Can do it | Ahrefs (preferred for links) |
22
+ | Technical site audit | ✅ Good crawler | Screaming Frog (more detailed) |
23
+ | Position tracking by location | ✅ | Local Falcon (geogrid is better for local) |
24
+ | Citation management | ❌ | BrightLocal, Whitespark |
25
+ | Live SERP snapshot | ❌ | SerpAPI |
26
+ | Geogrid rankings | ❌ | Local Falcon |
27
+
28
+ ## Core Workflows
29
+
30
+ ### Local Keyword Research
31
+
32
+ **When:** User needs to find keywords to target with volume and difficulty data.
33
+
34
+ **What to pull:**
35
+ 1. **Keyword Overview**: Volume, KD, CPC, SERP features for target keywords
36
+ 2. **Keyword Magic Tool**: Related keywords from a seed term (e.g., "plumber buffalo" → generates hundreds of variations)
37
+ 3. **Keyword Gap**: Compare user's domain vs 2-3 competitors to find keywords competitors rank for that user doesn't
38
+
39
+ **How to interpret for local:**
40
+ - Volume under 100/mo is common for local keywords — that's normal and still valuable
41
+ - KD under 40 for local service keywords is achievable
42
+ - CPC above $5 means high commercial intent — prioritize these
43
+ - Look for keyword clusters: same service, different locations (e.g., "dentist Orchard Park," "dentist Hamburg," "dentist West Seneca")
44
+
45
+ **What to do with the data:**
46
+ - Group keywords by service category
47
+ - Map keywords to existing or needed pages
48
+ - Identify gaps where competitors rank but you don't
49
+ - Feed into `local-keyword-research` skill for full keyword strategy
50
+ - Feed into `local-landing-pages` skill for page creation
51
+
52
+ ### Competitor Organic Analysis
53
+
54
+ **When:** User wants to know what keywords competitors rank for or how they compare.
55
+
56
+ **What to pull:**
57
+ 1. **Domain Overview**: Total organic keywords, traffic estimate, top keywords
58
+ 2. **Organic Research**: All keywords a competitor ranks for with positions
59
+ 3. **Keyword Gap**: Side-by-side comparison showing where competitor ranks and you don't
60
+
61
+ **What to look for:**
62
+ - Keywords where competitor ranks top 10 and you rank 11-20 (quick wins — you're close)
63
+ - Keywords where competitor ranks and you don't rank at all (content gaps)
64
+ - Keywords where you rank higher than competitor (protect these)
65
+ - Competitor's top traffic-driving keywords (understand their strategy)
66
+
67
+ ### Technical Site Audit
68
+
69
+ **When:** User needs a crawl of their website for technical issues.
70
+
71
+ **What Semrush's audit catches:**
72
+ - Broken links (internal and external)
73
+ - Missing/duplicate title tags and meta descriptions
74
+ - Slow pages
75
+ - Redirect chains
76
+ - Missing schema markup
77
+ - Crawlability issues
78
+ - HTTPS issues
79
+
80
+ **For local specifically, check:**
81
+ - Location page titles: unique per location?
82
+ - Location page meta descriptions: unique per location?
83
+ - Internal linking to location pages
84
+ - Schema presence on location pages
85
+ - Canonical tags on similar location pages
86
+
87
+ **When to use Screaming Frog instead:** If you need custom extraction (NAP data, specific schema fields) or the site has 1000+ location pages, Screaming Frog gives more control.
88
+
89
+ ### Position Tracking
90
+
91
+ **When:** User wants to track keyword rankings over time at a specific location.
92
+
93
+ - Set location to city/ZIP level
94
+ - Track target keywords weekly
95
+ - Compare against competitors in the same tracker
96
+
97
+ **When to use Local Falcon instead:** For local businesses, geogrid ranking (Local Falcon) is more meaningful than point-based position tracking (Semrush) because rankings vary by searcher location. Use Semrush position tracking for organic rankings, Local Falcon for map pack rankings.
98
+
99
+ ## Key Data Points and What They Mean
100
+
101
+ | Metric | What It Is | What It Means for Local SEO |
102
+ |--------|-----------|---------------------------|
103
+ | Search Volume | Monthly searches | Under 100 is normal for local — still valuable if intent is high |
104
+ | Keyword Difficulty (KD) | How hard to rank organically | Under 40 = achievable for local businesses with good content |
105
+ | CPC | Cost per click in Google Ads | High CPC = high commercial intent = priority keyword |
106
+ | Competitive Density | How many advertisers bid on this keyword | High density = proven money keyword |
107
+ | SERP Features | What appears in results (local pack, ads, PAA, etc.) | Local pack present = GBP optimization matters for this keyword |
108
+ | Traffic | Estimated monthly organic visits | Relative metric — compare competitors to each other |
109
+
110
+ ## What to Do Next
111
+
112
+ | What You Found | Next Action | Skill |
113
+ |----------------|-------------|-------|
114
+ | Keywords identified with volume data | Map keywords to pages and build content | `local-landing-pages` |
115
+ | Keyword gaps vs competitors | Prioritize gaps by volume × intent and create pages | `local-keyword-research` |
116
+ | Competitor ranking for keywords you're not | Analyze if it's a content gap or authority gap | `local-competitor-analysis` |
117
+ | Technical issues from site audit | Fix critical issues first (broken links, missing titles) | `local-seo-audit` |
118
+ | High-CPC keywords worth running ads for | Set up PPC campaigns | `local-ppc-ads` |
119
+ | Keywords with local pack in SERP | Optimize GBP for those keywords | `gbp-optimization` |
120
+
121
+ **Default next step:** Keyword data without a page plan is just a spreadsheet. Always map keywords → pages → publish → measure.
@@ -0,0 +1,148 @@
1
+ ---
2
+ name: serpapi-tool
3
+ description: When the user wants to check live SERP results for a keyword, see what's in the local pack right now, check People Also Ask, see AI Overviews, verify SERP features, or do a quick spot-check of local search results. Trigger on "what shows up when you search," "check the SERP," "who's in the map pack," "what does the search results page look like," or "search for [keyword]."
4
+ ---
5
+
6
+ # SerpAPI Tool
7
+
8
+ > **Note:** LocalSEOData (`localseodata-tool`) now covers live SERP data via `organic_serp`, `local_pack`, `maps`, and `local_finder` endpoints. Use LocalSEOData as default. SerpAPI remains useful if LocalSEOData is not connected, or for non-Google engines (Bing, Yahoo).
9
+
10
+ You have direct access to SerpAPI via MCP. This gives you live, real-time search results from Google, Bing, and other engines at any location.
11
+
12
+ ## When to Use SerpAPI vs Other Tools
13
+
14
+ | You Need | Use SerpAPI | Use Instead |
15
+ |----------|------------|-------------|
16
+ | Live SERP snapshot right now | ✅ | — |
17
+ | What's in the local pack for a query | ✅ | Local Falcon for geographic grid coverage |
18
+ | People Also Ask questions | ✅ | — |
19
+ | AI Overview content | ✅ | Local Falcon GAIO scan for geographic coverage |
20
+ | Quick rank check at one location | ✅ | Local Falcon for systematic multi-point |
21
+ | SERP features present (ads, knowledge panel, etc.) | ✅ | — |
22
+ | Rankings across a geographic grid | ❌ Too slow point by point | Local Falcon |
23
+ | Keyword volume/difficulty | ❌ | Semrush, Ahrefs, DataForSEO |
24
+ | Historical ranking trends | ❌ Snapshot only | Local Falcon trends |
25
+
26
+ ## Core Workflows
27
+
28
+ ### Check Live SERP for a Local Keyword
29
+
30
+ **When:** User wants to see what Google shows right now for a search.
31
+
32
+ ```json
33
+ {
34
+ "params": {
35
+ "q": "emergency plumber",
36
+ "engine": "google",
37
+ "location": "Buffalo, New York, United States"
38
+ },
39
+ "mode": "compact"
40
+ }
41
+ ```
42
+
43
+ **What to extract from results:**
44
+ - `local_results` — the map pack (positions, business names, ratings, reviews)
45
+ - `organic_results` — organic listings below the map
46
+ - `ads` — paid ads present (indicates commercial value)
47
+ - `related_questions` — People Also Ask (content opportunity)
48
+ - `ai_overview` — AI Overview content if present
49
+ - `knowledge_graph` — knowledge panel for branded searches
50
+
51
+ ### Check Google Maps Results Specifically
52
+
53
+ **When:** User wants to see local business listings specifically.
54
+
55
+ ```json
56
+ {
57
+ "params": {
58
+ "q": "dentist",
59
+ "engine": "google_maps",
60
+ "location": "Orchard Park, New York"
61
+ }
62
+ }
63
+ ```
64
+
65
+ Use `google_maps` engine when you want more than the top 3 map pack — this returns the full local finder results.
66
+
67
+ ### Check Local Results from a Specific Location
68
+
69
+ **When:** User wants to see results as if searching FROM a specific place.
70
+
71
+ ```json
72
+ {
73
+ "params": {
74
+ "q": "chiropractor near me",
75
+ "engine": "google_local",
76
+ "location": "Amherst, New York"
77
+ }
78
+ }
79
+ ```
80
+
81
+ **Important:** Location parameter simulates searching FROM that location. "Near me" queries will show results near that location.
82
+
83
+ ### Quick Competitive SERP Analysis
84
+
85
+ **When:** User wants to understand the competitive landscape for a keyword.
86
+
87
+ Run the search, then analyze:
88
+ 1. **Are there ads?** → Keyword has commercial value
89
+ 2. **Is there a local pack?** → Google sees local intent
90
+ 3. **How many reviews do map pack businesses have?** → Review benchmark
91
+ 4. **Is there an AI Overview?** → Content needs to be AI-optimizable
92
+ 5. **What are the PAA questions?** → Content/FAQ opportunities
93
+ 6. **Who's ranking organically?** → Directories vs. actual businesses
94
+
95
+ ### Verify SERP Features for Keyword Research
96
+
97
+ **When:** Building keyword strategy and need to know which keywords trigger which features.
98
+
99
+ Run searches for each target keyword and note:
100
+ - Local pack present → prioritize GBP optimization for this keyword
101
+ - Ads present → keyword has conversion value, consider PPC
102
+ - AI Overview present → optimize content for AI citation
103
+ - Featured snippet → structured content opportunity
104
+ - PAA questions → FAQ content opportunities
105
+ - No local pack → keyword may not have local intent, reconsider targeting
106
+
107
+ ## Engine Selection Guide
108
+
109
+ | Engine | When to Use |
110
+ |--------|-------------|
111
+ | `google` | Default — full SERP with all features including local pack |
112
+ | `google_maps` | Want full local/maps results beyond top 3 |
113
+ | `google_local` | Local finder results specifically |
114
+ | `google_light` | Quick check, less data, faster response |
115
+ | `google_news` | Check if keyword has news coverage |
116
+ | `google_images` | Check image results for a query |
117
+ | `bing` | Check Bing results (relevant for Copilot/AI search) |
118
+
119
+ ## Interpreting Results for Local SEO
120
+
121
+ ### Local Pack Analysis
122
+ - **Position 1-3**: These businesses dominate — note their review counts, ratings, categories
123
+ - **No local pack**: Google doesn't see local intent for this query — reconsider keyword strategy
124
+ - **Ads above local pack**: Competitive keyword — organic alone may not be enough
125
+
126
+ ### People Also Ask (PAA)
127
+ - Each PAA question is a content opportunity
128
+ - If your target keyword generates PAAs like "How much does [service] cost in [city]?" — create content answering that
129
+ - PAA questions often become FAQ schema candidates
130
+
131
+ ### AI Overview
132
+ - If present: Google is summarizing content for this query
133
+ - Note which sources are cited — those sites have the content structure Google prefers
134
+ - Your content needs to be factual, well-structured, and directly answering the query
135
+
136
+ ## What to Do Next
137
+
138
+ | What You Found | Next Action | Skill |
139
+ |----------------|-------------|-------|
140
+ | Local pack shows competitors with more reviews | Build review strategy | `review-management` |
141
+ | No local pack for target keyword | This isn't a local keyword — adjust strategy | `local-keyword-research` |
142
+ | AI Overview present, user not cited | Optimize content for AI visibility | `ai-local-search` |
143
+ | PAA questions found | Create FAQ content targeting those questions | `local-landing-pages` |
144
+ | Ads present, user not running ads | Consider PPC for this keyword | `local-ppc-ads` |
145
+ | Want geographic ranking data, not just this one point | Run a proper geogrid scan | `local-falcon-tool` |
146
+ | User in map pack but wrong position | Diagnose with geogrid analysis | `geogrid-analysis` |
147
+
148
+ **Default next step:** SerpAPI gives you a snapshot. For ongoing tracking, set up Local Falcon scans. Use SerpAPI for exploration and spot-checks, Local Falcon for measurement.