@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.
- package/CHANGELOG.md +195 -25
- package/SKILL.md +256 -7
- package/SURFACE.txt +237 -69
- package/dist/bin/crm.js +28 -2
- package/dist/bin/crm.js.map +1 -1
- package/dist/src/commands/access.js +104 -0
- package/dist/src/commands/access.js.map +1 -0
- package/dist/src/commands/brief.js +52 -0
- package/dist/src/commands/brief.js.map +1 -0
- package/dist/src/commands/chat.js +220 -0
- package/dist/src/commands/chat.js.map +1 -0
- package/dist/src/commands/commands.js +89 -0
- package/dist/src/commands/commands.js.map +1 -0
- package/dist/src/commands/comment.js +1 -0
- package/dist/src/commands/comment.js.map +1 -1
- package/dist/src/commands/generic.js +335 -5
- package/dist/src/commands/generic.js.map +1 -1
- package/dist/src/commands/integrations.js +236 -0
- package/dist/src/commands/integrations.js.map +1 -0
- package/dist/src/commands/mention.js +139 -0
- package/dist/src/commands/mention.js.map +1 -0
- package/dist/src/commands/options.js +21 -1
- package/dist/src/commands/options.js.map +1 -1
- package/dist/src/commands/rank.js +300 -0
- package/dist/src/commands/rank.js.map +1 -0
- package/dist/src/commands/report.js +209 -0
- package/dist/src/commands/report.js.map +1 -0
- package/dist/src/commands/review.js +136 -0
- package/dist/src/commands/review.js.map +1 -1
- package/dist/src/commands/skill.js +1005 -0
- package/dist/src/commands/skill.js.map +1 -0
- package/dist/src/commands/task.js +298 -4
- package/dist/src/commands/task.js.map +1 -1
- package/dist/src/commands/time.js +242 -0
- package/dist/src/commands/time.js.map +1 -0
- package/dist/src/lib/skillBundles.js +84 -0
- package/dist/src/lib/skillBundles.js.map +1 -0
- package/dist/src/lib/skillManifest.js +77 -0
- package/dist/src/lib/skillManifest.js.map +1 -0
- package/dist/src/lib/skillSidecar.js +69 -0
- package/dist/src/lib/skillSidecar.js.map +1 -0
- package/dist/src/lib/skillWriter.js +162 -0
- package/dist/src/lib/skillWriter.js.map +1 -0
- package/dist/src/transport/envelope.js +12 -2
- package/dist/src/transport/envelope.js.map +1 -1
- package/dist/src/transport/http.js +27 -0
- package/dist/src/transport/http.js.map +1 -1
- package/dist/src/transport/run.js +6 -0
- package/dist/src/transport/run.js.map +1 -1
- package/dist/src/types.js.map +1 -1
- package/dist/src/utils/server-nudge.js +57 -0
- package/dist/src/utils/server-nudge.js.map +1 -0
- package/dist/src/utils/version-check.js +68 -0
- package/dist/src/utils/version-check.js.map +1 -1
- package/package.json +58 -57
- package/skill-bundles/tools/ahrefs-tool/SKILL.md +134 -0
- package/skill-bundles/tools/brightlocal-tool/SKILL.md +154 -0
- package/skill-bundles/tools/dataforseo-tool/SKILL.md +118 -0
- package/skill-bundles/tools/google-analytics-tool/SKILL.md +143 -0
- package/skill-bundles/tools/google-search-console-tool/SKILL.md +133 -0
- package/skill-bundles/tools/local-falcon-tool/SKILL.md +142 -0
- package/skill-bundles/tools/localseodata-tool/SKILL.md +388 -0
- package/skill-bundles/tools/lsa-spy-tool/SKILL.md +113 -0
- package/skill-bundles/tools/screaming-frog-tool/SKILL.md +166 -0
- package/skill-bundles/tools/semrush-tool/SKILL.md +121 -0
- package/skill-bundles/tools/serpapi-tool/SKILL.md +148 -0
- package/skill-bundles/tools/task-preflight/SKILL.md +149 -0
- package/skill-bundles/tools/tool-routing/SKILL.md +59 -0
- package/skill-bundles/tools/whitespark-tool/SKILL.md +129 -0
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ahrefs-tool
|
|
3
|
+
description: When the user wants backlink analysis, link gap analysis, competitor link profiles, referring domain data, or link building research. Trigger on "backlinks," "who links to," "link profile," "referring domains," "link gap," "Ahrefs," "link building research," or "why do they outrank me" (often a link authority issue).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Ahrefs Tool
|
|
7
|
+
|
|
8
|
+
> **Note:** LocalSEOData (`localseodata-tool`) now has `backlink_summary` and `backlink_gap` endpoints. Use LocalSEOData for quick backlink overviews and gap analysis. Ahrefs remains the preferred tool for deep link analysis — anchor text profiles, lost/new links, referring domain details, and content gap analysis.
|
|
9
|
+
|
|
10
|
+
Ahrefs has an official MCP server. When connected, use it for backlink analysis and link-focused competitive intelligence. Ahrefs has the largest backlink index — it's the authoritative source for link data.
|
|
11
|
+
|
|
12
|
+
## When to Use Ahrefs vs Other Tools
|
|
13
|
+
|
|
14
|
+
| You Need | Use Ahrefs | Use Instead |
|
|
15
|
+
|----------|-----------|-------------|
|
|
16
|
+
| Backlink profile for a domain | ✅ Best backlink database | — |
|
|
17
|
+
| Referring domains count/list | ✅ | — |
|
|
18
|
+
| Link gap (who links to competitor but not you) | ✅ Best for this | — |
|
|
19
|
+
| Lost/broken backlinks | ✅ | — |
|
|
20
|
+
| Anchor text analysis | ✅ | — |
|
|
21
|
+
| Keyword search volume | ⚠️ Can do it | Semrush (better keyword tool) |
|
|
22
|
+
| Keyword gap analysis | ⚠️ Can do it | Semrush (preferred for keywords) |
|
|
23
|
+
| Content Explorer (find linkable content) | ✅ Unique to Ahrefs | — |
|
|
24
|
+
| Technical site audit | ⚠️ Has one | Screaming Frog (more detailed) |
|
|
25
|
+
| SERP data | ❌ | SerpAPI |
|
|
26
|
+
| Local pack rankings | ❌ | Local Falcon |
|
|
27
|
+
| Citation data | ❌ | BrightLocal |
|
|
28
|
+
|
|
29
|
+
## Core Workflows
|
|
30
|
+
|
|
31
|
+
### Analyze a Business's Link Profile
|
|
32
|
+
|
|
33
|
+
**When:** User asks "why aren't we ranking?" or needs to understand link authority.
|
|
34
|
+
|
|
35
|
+
**What to pull:**
|
|
36
|
+
1. **Domain Rating (DR)**: Overall link authority score (0-100)
|
|
37
|
+
2. **Referring Domains**: Unique domains linking to the site (more important than total backlinks)
|
|
38
|
+
3. **Backlink list**: Individual backlinks with source, anchor text, follow/nofollow, first seen date
|
|
39
|
+
4. **Referring domains by DR**: Quality distribution of linking domains
|
|
40
|
+
|
|
41
|
+
**How to interpret for local:**
|
|
42
|
+
- DR 20-40: Typical for local businesses
|
|
43
|
+
- DR 40-60: Strong local site, likely has press or industry links
|
|
44
|
+
- DR 60+: Very strong, probably a brand or large multi-location
|
|
45
|
+
- Referring domains matter more than total backlinks (10 links from 10 domains > 50 links from 2 domains)
|
|
46
|
+
- Local relevance matters: 1 link from a local news site > 10 links from random blogs
|
|
47
|
+
|
|
48
|
+
**Red flags:**
|
|
49
|
+
- Sudden spike in referring domains (could be spam or negative SEO)
|
|
50
|
+
- Mostly nofollow links (limited authority transfer)
|
|
51
|
+
- Anchor text heavily keyword-stuffed (penalty risk)
|
|
52
|
+
- Links from irrelevant or low-quality sites
|
|
53
|
+
|
|
54
|
+
### Link Gap Analysis (Competitor vs You)
|
|
55
|
+
|
|
56
|
+
**When:** User wants to find link building opportunities from competitor profiles.
|
|
57
|
+
|
|
58
|
+
**What to pull:**
|
|
59
|
+
1. **Link Intersect**: Domains that link to competitors but NOT to user's site
|
|
60
|
+
2. Filter by DR 20+ (skip low-quality)
|
|
61
|
+
3. Filter by dofollow links
|
|
62
|
+
4. Sort by referring domain authority
|
|
63
|
+
|
|
64
|
+
**What to look for:**
|
|
65
|
+
- Local directories linking to competitors but not you → citation opportunity
|
|
66
|
+
- Local news/media sites → PR opportunity
|
|
67
|
+
- Industry associations or organizations → membership/sponsorship opportunity
|
|
68
|
+
- Local blogs or community sites → content/relationship opportunity
|
|
69
|
+
- .edu or .gov sites → high authority, worth extra effort
|
|
70
|
+
|
|
71
|
+
**How to prioritize opportunities:**
|
|
72
|
+
1. Local relevance (local site > random site)
|
|
73
|
+
2. Domain authority (DR 30+ preferred)
|
|
74
|
+
3. Dofollow status (dofollow > nofollow for SEO, but nofollow still has value)
|
|
75
|
+
4. Achievability (directory listings are easy, editorial links take effort)
|
|
76
|
+
|
|
77
|
+
### Lost Link Recovery
|
|
78
|
+
|
|
79
|
+
**When:** Rankings dropped and you suspect link loss, or routine maintenance.
|
|
80
|
+
|
|
81
|
+
**What to pull:**
|
|
82
|
+
1. **Lost backlinks** (filtered by recent timeframe)
|
|
83
|
+
2. Filter by referring domain DR 20+
|
|
84
|
+
3. Check if the linking page is gone (404) or the link was removed
|
|
85
|
+
|
|
86
|
+
**What to do:**
|
|
87
|
+
- Page 404'd → Reach out and ask to update the link
|
|
88
|
+
- Link removed → Understand why (content changed? contact changed?)
|
|
89
|
+
- Domain expired → Check if link was valuable enough to pursue alternative
|
|
90
|
+
- High-DR losses → Priority recovery targets
|
|
91
|
+
|
|
92
|
+
### Anchor Text Analysis
|
|
93
|
+
|
|
94
|
+
**When:** Checking for over-optimization or understanding link profile health.
|
|
95
|
+
|
|
96
|
+
**What healthy local anchor text looks like:**
|
|
97
|
+
- Brand name (40-60%): "Smith Plumbing," "smithplumbing.com"
|
|
98
|
+
- Generic (15-25%): "click here," "website," "learn more"
|
|
99
|
+
- Location-based (10-20%): "plumber in Buffalo," "Buffalo NY plumbing"
|
|
100
|
+
- Exact match keywords (under 10%): "emergency plumber" — too much of this is a penalty risk
|
|
101
|
+
|
|
102
|
+
### Content Explorer (Find Linkable Content Ideas)
|
|
103
|
+
|
|
104
|
+
**When:** User needs content ideas that attract links.
|
|
105
|
+
|
|
106
|
+
- Search for topics in your industry + location
|
|
107
|
+
- Find content that got the most links in your space
|
|
108
|
+
- Analyze what made it linkable (data, tools, guides, local research)
|
|
109
|
+
- Create something better for your market
|
|
110
|
+
|
|
111
|
+
## Key Metrics and What They Mean
|
|
112
|
+
|
|
113
|
+
| Metric | What It Is | Local SEO Context |
|
|
114
|
+
|--------|-----------|-------------------|
|
|
115
|
+
| Domain Rating (DR) | Ahrefs' authority score (0-100) | Compare to local competitors, not national brands |
|
|
116
|
+
| Referring Domains | Unique domains linking to you | The #1 link metric — more unique domains = more authority |
|
|
117
|
+
| URL Rating (UR) | Authority of a specific page | Useful for comparing location page authority |
|
|
118
|
+
| Dofollow % | Percentage of links passing authority | Below 50% dofollow is weak |
|
|
119
|
+
| Anchor text distribution | What text is used in links | Over-optimized anchors can trigger penalties |
|
|
120
|
+
| Link velocity | Rate of new links acquired | Steady growth is healthy, spikes are suspicious |
|
|
121
|
+
|
|
122
|
+
## What to Do Next
|
|
123
|
+
|
|
124
|
+
| What You Found | Next Action | Skill |
|
|
125
|
+
|----------------|-------------|-------|
|
|
126
|
+
| Competitor has 3x more referring domains | Build a link acquisition strategy | `local-link-building` |
|
|
127
|
+
| Found link gap opportunities (directories) | These are citation opportunities | `local-citations` |
|
|
128
|
+
| Found link gap opportunities (editorial/media) | Build targeted outreach campaigns | `local-link-building` |
|
|
129
|
+
| Anchor text over-optimized | Diversify with brand and generic anchors going forward | `local-link-building` |
|
|
130
|
+
| Lost high-value links | Outreach to recover, then build replacements | `local-link-building` |
|
|
131
|
+
| Link profile is fine but still not ranking locally | Links aren't the issue — check GBP, reviews, proximity | `geogrid-analysis`, `gbp-optimization` |
|
|
132
|
+
| Need this data in a client report | Include link profile comparison in deliverables | `client-deliverables` |
|
|
133
|
+
|
|
134
|
+
**Default next step:** Link analysis always raises the question "is this a link problem or something else?" If the link profile is comparable to competitors, the issue is likely GBP, reviews, or relevance — not links.
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: brightlocal-tool
|
|
3
|
+
description: When the user wants citation audits, citation building, review monitoring across platforms, GBP audit scoring, or white-label local SEO reports. Trigger on "citation audit," "check my citations," "NAP consistency," "where am I listed," "BrightLocal," "directory listings," "review monitoring," or "client report."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# BrightLocal Tool
|
|
7
|
+
|
|
8
|
+
> **Note:** LocalSEOData (`localseodata-tool`) now covers citation audits (`citation_audit`), multi-platform reviews (`multi_platform_reviews`), and reputation auditing (`reputation_audit`). Use LocalSEOData as default for data pulls. BrightLocal remains useful for citation building/submission and review monitoring dashboards.
|
|
9
|
+
|
|
10
|
+
BrightLocal has an official MCP server. When connected, use it for citation management, review aggregation, GBP auditing, and client reporting. This is your primary citation intelligence tool.
|
|
11
|
+
|
|
12
|
+
## When to Use BrightLocal vs Other Tools
|
|
13
|
+
|
|
14
|
+
| You Need | Use BrightLocal | Use Instead |
|
|
15
|
+
|----------|----------------|-------------|
|
|
16
|
+
| Citation audit (where is this business listed?) | ✅ Best for this | — |
|
|
17
|
+
| NAP consistency check across directories | ✅ Best for this | — |
|
|
18
|
+
| Citation building (submit to directories) | ✅ Managed service | Whitespark (alternative) |
|
|
19
|
+
| Review monitoring across multiple platforms | ✅ | — |
|
|
20
|
+
| GBP profile audit/scoring | ✅ | — |
|
|
21
|
+
| White-label client reports | ✅ | — |
|
|
22
|
+
| Keyword search volume | ❌ | Semrush, Ahrefs |
|
|
23
|
+
| Backlink analysis | ❌ | Ahrefs |
|
|
24
|
+
| Geogrid rankings | ❌ | Local Falcon |
|
|
25
|
+
| Live SERP data | ❌ | SerpAPI |
|
|
26
|
+
| Technical site audit | ❌ | Screaming Frog |
|
|
27
|
+
|
|
28
|
+
## Core Workflows
|
|
29
|
+
|
|
30
|
+
### Citation Audit
|
|
31
|
+
|
|
32
|
+
**When:** User asks "where am I listed?" or "are my citations consistent?" or this is part of a local SEO audit.
|
|
33
|
+
|
|
34
|
+
**What to pull:**
|
|
35
|
+
1. **Citation Tracker**: All found citations for the business
|
|
36
|
+
2. **Accuracy scores**: NAP match percentage per directory
|
|
37
|
+
3. **Directory coverage**: Which directories have listings vs which don't
|
|
38
|
+
4. **Duplicate detection**: Multiple listings on the same directory
|
|
39
|
+
|
|
40
|
+
**How to interpret:**
|
|
41
|
+
- Accuracy score above 90%: Good — minor fixes needed
|
|
42
|
+
- Accuracy score 70-90%: Moderate issues — old phone numbers, address variations
|
|
43
|
+
- Accuracy score below 70%: Serious problems — inconsistent data confusing Google
|
|
44
|
+
- Missing from major directories (Google, Yelp, Facebook, Apple Maps, Bing): Critical gaps
|
|
45
|
+
- Duplicates on same directory: Splitting ranking signals — need to merge or remove
|
|
46
|
+
|
|
47
|
+
**Priority directories to check:**
|
|
48
|
+
1. Google Business Profile (the #1 citation)
|
|
49
|
+
2. Apple Maps / Apple Business Connect
|
|
50
|
+
3. Bing Places
|
|
51
|
+
4. Yelp
|
|
52
|
+
5. Facebook
|
|
53
|
+
6. Industry-specific directories (Healthgrades, Avvo, Angi, etc.)
|
|
54
|
+
7. Data aggregators (Data Axle, Neustar/Localeze, Foursquare)
|
|
55
|
+
|
|
56
|
+
### Citation Building
|
|
57
|
+
|
|
58
|
+
**When:** Audit reveals missing directories or user needs new citations built.
|
|
59
|
+
|
|
60
|
+
BrightLocal offers managed citation building — they submit to directories on your behalf.
|
|
61
|
+
|
|
62
|
+
**What to specify:**
|
|
63
|
+
- Business NAP (must be exactly consistent with GBP)
|
|
64
|
+
- Categories
|
|
65
|
+
- Description
|
|
66
|
+
- Photos
|
|
67
|
+
- Target directories (or let BrightLocal recommend based on industry)
|
|
68
|
+
|
|
69
|
+
**Timeline:** Most submissions process in 2-4 weeks. Some directories take longer.
|
|
70
|
+
|
|
71
|
+
**After building:** Re-audit in 6-8 weeks to verify submissions were accepted and data is accurate.
|
|
72
|
+
|
|
73
|
+
### Review Monitoring
|
|
74
|
+
|
|
75
|
+
**When:** User wants to track reviews across Google, Yelp, Facebook, and industry platforms.
|
|
76
|
+
|
|
77
|
+
**What to pull:**
|
|
78
|
+
1. **Review feed**: All reviews across connected platforms
|
|
79
|
+
2. **Review count and rating per platform**
|
|
80
|
+
3. **New review alerts**: Recent reviews needing responses
|
|
81
|
+
4. **Sentiment trends**: Rating direction over time
|
|
82
|
+
|
|
83
|
+
**What to look for:**
|
|
84
|
+
- Platforms where reviews are accumulating but no one is responding
|
|
85
|
+
- Rating discrepancies between platforms (4.8 on Google but 3.2 on Yelp — investigate)
|
|
86
|
+
- Review velocity compared to competitors
|
|
87
|
+
- Negative review patterns (recurring complaints = operational issue)
|
|
88
|
+
|
|
89
|
+
### GBP Audit
|
|
90
|
+
|
|
91
|
+
**When:** Need a quick health check on the Google Business Profile.
|
|
92
|
+
|
|
93
|
+
**What BrightLocal checks:**
|
|
94
|
+
- Profile completeness (photos, description, hours, categories, attributes)
|
|
95
|
+
- NAP consistency with website and citations
|
|
96
|
+
- Review response rate
|
|
97
|
+
- Post activity
|
|
98
|
+
- Category accuracy
|
|
99
|
+
|
|
100
|
+
**Scoring:** BrightLocal generates an audit score. Use this as a starting point, then apply `gbp-optimization` skill for the detailed playbook.
|
|
101
|
+
|
|
102
|
+
### Client Reporting
|
|
103
|
+
|
|
104
|
+
**When:** Need to generate a client-facing report.
|
|
105
|
+
|
|
106
|
+
**What to include:**
|
|
107
|
+
- Citation health score and changes
|
|
108
|
+
- Review summary (count, rating, new reviews)
|
|
109
|
+
- GBP audit score
|
|
110
|
+
- Ranking data (if using BrightLocal's rank tracker)
|
|
111
|
+
|
|
112
|
+
**Note:** BrightLocal reports are white-labelable. For agencies, brand them before sending.
|
|
113
|
+
|
|
114
|
+
## Interpreting Citation Data
|
|
115
|
+
|
|
116
|
+
### NAP Consistency Scoring
|
|
117
|
+
|
|
118
|
+
| Score | Status | Action |
|
|
119
|
+
|-------|--------|--------|
|
|
120
|
+
| 95-100% | Excellent | Monitor quarterly |
|
|
121
|
+
| 85-94% | Good | Fix remaining inconsistencies |
|
|
122
|
+
| 70-84% | Needs work | Prioritize top directories, fix data aggregators |
|
|
123
|
+
| Below 70% | Critical | Full citation cleanup needed before other optimization |
|
|
124
|
+
|
|
125
|
+
### Common Citation Issues
|
|
126
|
+
|
|
127
|
+
| Issue | What Causes It | How to Fix |
|
|
128
|
+
|-------|---------------|-----------|
|
|
129
|
+
| Old phone number | Business changed numbers, aggregators have old data | Update aggregators first (Data Axle, Neustar, Foursquare), then individual directories |
|
|
130
|
+
| Old address | Business moved, aggregators propagated old address | Same — fix at aggregator level |
|
|
131
|
+
| Name variations | "Smith Plumbing" vs "Smith Plumbing LLC" vs "Smith's Plumbing" | Standardize to match GBP exactly |
|
|
132
|
+
| Duplicate listings | Multiple submissions over time, or auto-generated listings | Claim and merge or request removal |
|
|
133
|
+
| Wrong category | Directory auto-assigned category | Manually update on each directory |
|
|
134
|
+
|
|
135
|
+
### Aggregator Priority
|
|
136
|
+
|
|
137
|
+
Fix data aggregators FIRST — they feed data to hundreds of downstream directories:
|
|
138
|
+
1. **Data Axle** (formerly Infogroup) — feeds the most directories
|
|
139
|
+
2. **Neustar/Localeze** — second-largest aggregator
|
|
140
|
+
3. **Foursquare** — feeds Apple Maps and many apps
|
|
141
|
+
4. **Yelp** — both a directory and a data source for Apple Maps
|
|
142
|
+
|
|
143
|
+
## What to Do Next
|
|
144
|
+
|
|
145
|
+
| What You Found | Next Action | Skill |
|
|
146
|
+
|----------------|-------------|-------|
|
|
147
|
+
| NAP inconsistencies across directories | Fix aggregators first, then individual directories | `local-citations` |
|
|
148
|
+
| Missing from key directories | Build citations on missing directories | `local-citations` |
|
|
149
|
+
| Low review count on Google | Build review generation strategy | `review-management` |
|
|
150
|
+
| GBP audit shows incomplete profile | Optimize the profile | `gbp-optimization` |
|
|
151
|
+
| Citations clean but still not ranking | Citations aren't the issue — check other factors | `geogrid-analysis`, `local-seo-audit` |
|
|
152
|
+
| Need to present findings to client | Package citation report with recommendations | `client-deliverables` |
|
|
153
|
+
|
|
154
|
+
**Default next step:** Citation cleanup is a slow process (4-8 weeks for aggregator changes to propagate). Start the cleanup, then work on other optimization while waiting.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dataforseo-tool
|
|
3
|
+
description: When the user needs bulk SERP data, local pack data at scale, keyword volumes for hundreds of terms at once, Google Maps business data programmatically, or is building custom local SEO tools/dashboards. Trigger on "bulk keyword data," "SERP data at scale," "DataForSEO," "Google Maps API data," "business data API," or when any other keyword/SERP tool would be too slow for the volume needed.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# DataForSEO Tool
|
|
7
|
+
|
|
8
|
+
> **Note:** LocalSEOData (`localseodata-tool`) is built on DataForSEO and provides a simplified, pre-assembled layer for most local SEO data needs. Use LocalSEOData as default. DataForSEO is still the right choice for massive bulk operations (1000+ queries) or custom pipeline builds that need raw API access.
|
|
9
|
+
|
|
10
|
+
DataForSEO has an official MCP server. When connected, use it for bulk SEO data operations — SERP results, keyword volumes, business data, and backlinks at scale. This is your bulk data and custom tooling API.
|
|
11
|
+
|
|
12
|
+
## When to Use DataForSEO vs Other Tools
|
|
13
|
+
|
|
14
|
+
| You Need | Use DataForSEO | Use Instead |
|
|
15
|
+
|----------|---------------|-------------|
|
|
16
|
+
| Keyword volume for 500+ terms at once | ✅ Best for bulk | Semrush (for smaller batches) |
|
|
17
|
+
| SERP results for many keyword+location combos | ✅ Best for scale | SerpAPI (for individual queries) |
|
|
18
|
+
| Google Maps business data programmatically | ✅ | — |
|
|
19
|
+
| Google reviews for a business via API | ✅ | — |
|
|
20
|
+
| Local pack monitoring at scale (custom build) | ✅ | Local Falcon (turnkey solution) |
|
|
21
|
+
| Backlink data | ⚠️ Has it, smaller index | Ahrefs (preferred) |
|
|
22
|
+
| Single keyword research | ❌ Overkill | Semrush |
|
|
23
|
+
| Single SERP check | ❌ Overkill | SerpAPI |
|
|
24
|
+
| Citation audit | ❌ | BrightLocal |
|
|
25
|
+
| Geogrid ranking visualization | ❌ | Local Falcon |
|
|
26
|
+
|
|
27
|
+
## When DataForSEO Is the Right Choice
|
|
28
|
+
|
|
29
|
+
DataForSEO is the right tool when:
|
|
30
|
+
- **Volume**: You need data for 100+ keywords, 50+ locations, or 20+ competitors at once
|
|
31
|
+
- **Custom builds**: You're building a dashboard, tool, or automated system
|
|
32
|
+
- **Programmatic access**: You need structured data for processing, not human reading
|
|
33
|
+
- **Cost efficiency at scale**: Pay-per-task pricing beats subscription tools for bulk operations
|
|
34
|
+
|
|
35
|
+
DataForSEO is NOT the right tool when:
|
|
36
|
+
- You need one quick answer (use SerpAPI or Semrush)
|
|
37
|
+
- You need a turnkey product with visualizations (use Local Falcon, BrightLocal)
|
|
38
|
+
- You need editorial link analysis (use Ahrefs)
|
|
39
|
+
|
|
40
|
+
## Core Workflows
|
|
41
|
+
|
|
42
|
+
### Bulk Local Keyword Volume
|
|
43
|
+
|
|
44
|
+
**When:** Have a large keyword list and need volume data for all of them.
|
|
45
|
+
|
|
46
|
+
**Endpoints:**
|
|
47
|
+
- `keywords_data/google_ads/search_volume` — volume, CPC, competition for keyword list
|
|
48
|
+
- `keywords_data/google_ads/keywords_for_site` — keywords a domain gets traffic for
|
|
49
|
+
|
|
50
|
+
**Use case:** You've generated 200 service+city keyword combinations from `local-keyword-research`. Instead of checking each one in Semrush, batch them through DataForSEO.
|
|
51
|
+
|
|
52
|
+
**What you get:** Volume, CPC, competition level, monthly trends for each keyword.
|
|
53
|
+
|
|
54
|
+
### Bulk SERP Data
|
|
55
|
+
|
|
56
|
+
**When:** Need to check local pack presence across many keywords or locations.
|
|
57
|
+
|
|
58
|
+
**Endpoints:**
|
|
59
|
+
- `serp/google/organic/live` — full SERP with local pack
|
|
60
|
+
- `serp/google/maps/live` — Google Maps results
|
|
61
|
+
- `serp/google/local_finder/live` — local finder specifically
|
|
62
|
+
|
|
63
|
+
**Use case:** Check 50 keywords across 10 cities to see which trigger local packs and who appears in them. That's 500 SERP checks — impossible manually, trivial via DataForSEO.
|
|
64
|
+
|
|
65
|
+
**What to extract:**
|
|
66
|
+
- Does a local pack appear? (local intent confirmation)
|
|
67
|
+
- Who's in the local pack? (competitor identification)
|
|
68
|
+
- Are ads present? (commercial value)
|
|
69
|
+
- AI Overview present? (content optimization signal)
|
|
70
|
+
|
|
71
|
+
### Google Business Data
|
|
72
|
+
|
|
73
|
+
**When:** Need GBP information about competitors or a market programmatically.
|
|
74
|
+
|
|
75
|
+
**Endpoints:**
|
|
76
|
+
- `business_data/google/my_business_info` — GBP details (name, address, categories, hours, photos, etc.)
|
|
77
|
+
- `business_data/google/reviews` — Google reviews with text, rating, date
|
|
78
|
+
|
|
79
|
+
**Use case:**
|
|
80
|
+
- Pull GBP data for top 20 competitors in a market to compare categories, review counts, ratings
|
|
81
|
+
- Extract reviews for sentiment analysis
|
|
82
|
+
- Monitor competitor GBP changes over time
|
|
83
|
+
|
|
84
|
+
### Custom Local Rank Monitoring
|
|
85
|
+
|
|
86
|
+
**When:** Building a custom ranking tool or dashboard instead of using Local Falcon.
|
|
87
|
+
|
|
88
|
+
**Approach:**
|
|
89
|
+
1. Define grid of coordinates for the service area
|
|
90
|
+
2. For each coordinate, run `serp/google/maps/live` with target keyword
|
|
91
|
+
3. Parse results to find target business position at each point
|
|
92
|
+
4. Aggregate into ARP/SoLV-style metrics
|
|
93
|
+
5. Schedule to run weekly/monthly
|
|
94
|
+
|
|
95
|
+
**When to build custom vs use Local Falcon:**
|
|
96
|
+
- Local Falcon: Turnkey, visual, campaign management, client-shareable reports
|
|
97
|
+
- DataForSEO custom: Full control, custom metrics, integrates into your own systems, cheaper at very high volume
|
|
98
|
+
|
|
99
|
+
## Pricing Awareness
|
|
100
|
+
|
|
101
|
+
- Pay-per-task model — each API call costs credits
|
|
102
|
+
- SERP tasks: ~$0.002-0.005 per result
|
|
103
|
+
- Keyword data: ~$0.05 per batch of keywords
|
|
104
|
+
- Business data: ~$0.005 per result
|
|
105
|
+
- Always estimate total cost before running bulk operations
|
|
106
|
+
- Use async endpoints for large batches (submit tasks, poll for results)
|
|
107
|
+
|
|
108
|
+
## What to Do Next
|
|
109
|
+
|
|
110
|
+
| What You Got | Next Action | Skill |
|
|
111
|
+
|--------------|-------------|-------|
|
|
112
|
+
| Bulk keyword volumes | Group by service, map to pages, prioritize by volume × intent | `local-keyword-research` |
|
|
113
|
+
| SERP data showing local pack presence | Focus GBP optimization on keywords with local packs | `gbp-optimization` |
|
|
114
|
+
| Competitor GBP data | Analyze category usage, review benchmarks, service coverage | `local-competitor-analysis` |
|
|
115
|
+
| Competitor reviews extracted | Analyze for sentiment themes, common complaints/praise | `review-management` |
|
|
116
|
+
| Custom ranking data | Interpret using geogrid analysis framework | `geogrid-analysis` |
|
|
117
|
+
|
|
118
|
+
**Default next step:** DataForSEO gives you raw data. Always pair it with an analysis skill to turn data into decisions.
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: google-analytics-tool
|
|
3
|
+
description: When the user wants traffic data, conversion tracking, user behavior on location pages, GBP traffic attribution, or geographic traffic patterns. Trigger on "Google Analytics," "GA4," "traffic," "conversions," "how many leads," "phone calls," "form submissions," "where is my traffic coming from," or "is my website converting."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Google Analytics (GA4) Tool
|
|
7
|
+
|
|
8
|
+
GA4 has an official MCP server from Google. When connected, use it for website traffic analysis, conversion attribution, and user behavior data. GA4 answers "what happens AFTER someone finds you."
|
|
9
|
+
|
|
10
|
+
## When to Use GA4 vs Other Tools
|
|
11
|
+
|
|
12
|
+
| You Need | Use GA4 | Use Instead |
|
|
13
|
+
|----------|--------|-------------|
|
|
14
|
+
| Traffic to location pages | ✅ | — |
|
|
15
|
+
| Conversion tracking (calls, forms, bookings) | ✅ | — |
|
|
16
|
+
| Traffic source attribution (organic vs paid vs GBP) | ✅ | — |
|
|
17
|
+
| Geographic traffic patterns | ✅ | — |
|
|
18
|
+
| User behavior (bounce rate, engagement, time on page) | ✅ | — |
|
|
19
|
+
| GBP-specific traffic (via UTM) | ✅ | — |
|
|
20
|
+
| What keywords people searched to find you | ❌ Very limited | GSC (query data) |
|
|
21
|
+
| Search rankings | ❌ | Local Falcon, Semrush |
|
|
22
|
+
| Backlinks | ❌ | Ahrefs |
|
|
23
|
+
| SERP features | ❌ | SerpAPI |
|
|
24
|
+
|
|
25
|
+
## Critical Distinction
|
|
26
|
+
|
|
27
|
+
GA4 shows what happens ON YOUR WEBSITE. It does NOT show:
|
|
28
|
+
- GBP interactions that don't reach your website (calls from GBP, directions from GBP, map views)
|
|
29
|
+
- Map pack clicks that go to the GBP profile, not the website
|
|
30
|
+
- Local Falcon/ranking data
|
|
31
|
+
|
|
32
|
+
For complete local performance: GA4 (website) + GSC (organic queries) + GBP Insights (profile interactions) + Local Falcon (map rankings).
|
|
33
|
+
|
|
34
|
+
## Core Workflows
|
|
35
|
+
|
|
36
|
+
### Location Page Traffic Analysis
|
|
37
|
+
|
|
38
|
+
**When:** User asks "how are my location pages performing?" or "which locations get the most traffic?"
|
|
39
|
+
|
|
40
|
+
**What to pull:**
|
|
41
|
+
1. Landing page report filtered to location page URLs
|
|
42
|
+
2. Metrics: Sessions, users, engaged sessions, engagement rate, conversions
|
|
43
|
+
3. Compare across location pages
|
|
44
|
+
|
|
45
|
+
**How to interpret:**
|
|
46
|
+
- Location page with high traffic but low engagement: Content doesn't match what visitors expect — check title alignment
|
|
47
|
+
- Location page with high engagement but low conversions: Missing or weak CTA (call button, form, booking link)
|
|
48
|
+
- Location page with no traffic: Not indexed (check GSC) or no keyword targeting (check `local-keyword-research`)
|
|
49
|
+
- Big traffic differences between location pages: Might reflect market size, or some pages are better optimized
|
|
50
|
+
|
|
51
|
+
### Conversion Tracking
|
|
52
|
+
|
|
53
|
+
**When:** User asks "how many leads am I getting?" or wants to measure ROI.
|
|
54
|
+
|
|
55
|
+
**Key local conversions to track:**
|
|
56
|
+
| Conversion Event | How to Track | Setup Required |
|
|
57
|
+
|-----------------|-------------|----------------|
|
|
58
|
+
| Phone calls (click-to-call) | Event on `tel:` link clicks | Yes — event must be configured |
|
|
59
|
+
| Form submissions | Event on form submit/thank-you page | Yes — event or thank-you page trigger |
|
|
60
|
+
| Direction requests | Event on directions link clicks | Yes — event on link |
|
|
61
|
+
| Booking/scheduling | Event on booking completion | Yes — depends on booking system |
|
|
62
|
+
| Chat initiated | Event on chat widget open | Yes — event on widget |
|
|
63
|
+
|
|
64
|
+
**If conversions aren't set up:** Tell the user. GA4 doesn't track conversions automatically. Without configured events, you can only report traffic, not leads.
|
|
65
|
+
|
|
66
|
+
**What to look for:**
|
|
67
|
+
- Conversion rate per traffic source (organic vs paid vs direct vs referral)
|
|
68
|
+
- Conversion rate per location page
|
|
69
|
+
- Which pages generate the most conversions (not just traffic)
|
|
70
|
+
- Conversion trends over time (improving or declining?)
|
|
71
|
+
|
|
72
|
+
### GBP Traffic Attribution
|
|
73
|
+
|
|
74
|
+
**When:** User wants to know how much traffic comes specifically from their Google Business Profile.
|
|
75
|
+
|
|
76
|
+
**How it works:** GBP website links should include UTM parameters. Common patterns:
|
|
77
|
+
- `utm_source=google&utm_medium=organic&utm_campaign=gbp`
|
|
78
|
+
- `utm_source=gmb` (older convention)
|
|
79
|
+
|
|
80
|
+
**What to pull:**
|
|
81
|
+
1. Filter by source/medium matching GBP UTM parameters
|
|
82
|
+
2. Sessions, users, conversions from GBP specifically
|
|
83
|
+
3. Compare GBP traffic to overall organic traffic
|
|
84
|
+
|
|
85
|
+
**If no UTM tracking:** Most businesses don't set this up. Recommend adding UTM parameters to the GBP website URL so future data can be attributed.
|
|
86
|
+
|
|
87
|
+
### Geographic Traffic Analysis
|
|
88
|
+
|
|
89
|
+
**When:** User wants to know where their website visitors are located.
|
|
90
|
+
|
|
91
|
+
**What to pull:**
|
|
92
|
+
1. Geographic report by city/region
|
|
93
|
+
2. Filter to organic traffic only
|
|
94
|
+
3. Compare against service area
|
|
95
|
+
|
|
96
|
+
**How to interpret for local:**
|
|
97
|
+
- Traffic concentrated in one city but business serves a wider area: Need service area pages for other cities
|
|
98
|
+
- Traffic from cities outside service area: Content attracting non-local visitors (may or may not be useful)
|
|
99
|
+
- No traffic from a city in the service area: No content targeting that area, or not ranking there
|
|
100
|
+
|
|
101
|
+
### Traffic Source Comparison
|
|
102
|
+
|
|
103
|
+
**When:** User wants to understand their traffic mix.
|
|
104
|
+
|
|
105
|
+
**Pull traffic by source/medium:**
|
|
106
|
+
- Organic search (Google/Bing) → SEO working
|
|
107
|
+
- Direct → Brand awareness / repeat visitors
|
|
108
|
+
- Referral → Links from other sites sending traffic
|
|
109
|
+
- Paid search → Google Ads / PPC
|
|
110
|
+
- Social → Social media channels
|
|
111
|
+
|
|
112
|
+
**Healthy local business traffic mix:**
|
|
113
|
+
- Organic: 40-60% (should be the largest source)
|
|
114
|
+
- Direct: 20-30% (brand recognition)
|
|
115
|
+
- Referral: 5-15% (healthy backlink profile)
|
|
116
|
+
- Paid: varies by budget
|
|
117
|
+
- If organic is under 30%, SEO needs work
|
|
118
|
+
|
|
119
|
+
## Key Metrics and What They Mean
|
|
120
|
+
|
|
121
|
+
| Metric | What It Is | Local SEO Context |
|
|
122
|
+
|--------|-----------|-------------------|
|
|
123
|
+
| Sessions | Website visits | Total demand reaching your site |
|
|
124
|
+
| Engaged Sessions | Sessions with meaningful interaction | More important than raw sessions |
|
|
125
|
+
| Engagement Rate | Engaged sessions ÷ Total sessions | Below 50% on location pages = content problem |
|
|
126
|
+
| Conversions | Completed goal actions | THE metric — everything else is a means to this |
|
|
127
|
+
| Conversion Rate | Conversions ÷ Sessions | Benchmark: 3-5% for local service businesses |
|
|
128
|
+
| Bounce Rate | Sessions with no interaction | GA4 bounce = not engaged. High bounce on location pages = bad signal |
|
|
129
|
+
| Average Engagement Time | Time actively on page | Under 30 seconds = content isn't connecting |
|
|
130
|
+
|
|
131
|
+
## What to Do Next
|
|
132
|
+
|
|
133
|
+
| What You Found | Next Action | Skill |
|
|
134
|
+
|----------------|-------------|-------|
|
|
135
|
+
| Location pages with low traffic | Check GSC for indexing, then check keyword targeting | `google-search-console-tool`, `local-keyword-research` |
|
|
136
|
+
| Traffic but no conversions | Add/fix CTAs, forms, click-to-call | `local-landing-pages` |
|
|
137
|
+
| No conversion tracking set up | Configure GA4 events before anything else | Technical setup needed |
|
|
138
|
+
| GBP traffic not being tracked | Add UTM parameters to GBP website URL | `gbp-optimization` |
|
|
139
|
+
| Good traffic from organic but bad conversion rate | Landing page content/design issue | `local-landing-pages` |
|
|
140
|
+
| Geographic gaps in traffic | Build location pages for underserved cities | `local-landing-pages`, `service-area-seo` |
|
|
141
|
+
| Need this in a client report | Include traffic and conversion data in reports | `local-reporting` |
|
|
142
|
+
|
|
143
|
+
**Default next step:** Traffic without conversion tracking is vanity metrics. If GA4 events aren't configured, that's the first thing to fix — before any SEO work, you need to be able to measure results.
|