diff --git a/tools/REGISTRY.md b/tools/REGISTRY.md index cc79f68..80d3669 100644 --- a/tools/REGISTRY.md +++ b/tools/REGISTRY.md @@ -23,6 +23,8 @@ Quick reference for AI agents to discover tool capabilities and integration meth | google-search-console | SEO | ✓ | - | [✓](clis/google-search-console.js) | ✓ | [google-search-console.md](integrations/google-search-console.md) | | semrush | SEO | ✓ | - | [✓](clis/semrush.js) | - | [semrush.md](integrations/semrush.md) | | ahrefs | SEO | ✓ | - | [✓](clis/ahrefs.js) | - | [ahrefs.md](integrations/ahrefs.md) | +| dataforseo | SEO | ✓ | - | [✓](clis/dataforseo.js) | ✓ | [dataforseo.md](integrations/dataforseo.md) | +| keywords-everywhere | SEO | ✓ | - | [✓](clis/keywords-everywhere.js) | - | [keywords-everywhere.md](integrations/keywords-everywhere.md) | | hubspot | CRM | ✓ | - | ✓ | ✓ | [hubspot.md](integrations/hubspot.md) | | salesforce | CRM | ✓ | - | ✓ | ✓ | [salesforce.md](integrations/salesforce.md) | | stripe | Payments | ✓ | ✓ | ✓ | ✓ | [stripe.md](integrations/stripe.md) | @@ -72,8 +74,10 @@ Search engine optimization tools for keyword research, rank tracking, and site a | **google-search-console** | Free, authoritative search data | Direct from Google | | **semrush** | Competitive analysis, keyword research | Comprehensive | | **ahrefs** | Backlink analysis, content research | Best for links | +| **dataforseo** | SERP tracking, backlinks, on-page audits | Comprehensive API | +| **keywords-everywhere** | Quick keyword research, traffic estimates | Credit-based | -**Agent recommendation**: Google Search Console is essential (free). Add Semrush or Ahrefs for competitive research. +**Agent recommendation**: Google Search Console is essential (free). Add Semrush or Ahrefs for competitive research. DataForSEO for programmatic SERP data. Keywords Everywhere for quick keyword lookups. ### CRM diff --git a/tools/clis/README.md b/tools/clis/README.md index 0d14dce..4b6cc1a 100644 --- a/tools/clis/README.md +++ b/tools/clis/README.md @@ -40,10 +40,12 @@ Every CLI reads credentials from environment variables: | `adobe-analytics` | `ADOBE_CLIENT_ID`, `ADOBE_ACCESS_TOKEN` | | `amplitude` | `AMPLITUDE_API_KEY`, `AMPLITUDE_SECRET_KEY` | | `customer-io` | `CUSTOMERIO_APP_KEY` (App API), `CUSTOMERIO_SITE_ID` + `CUSTOMERIO_API_KEY` (Track API) | +| `dataforseo` | `DATAFORSEO_LOGIN`, `DATAFORSEO_PASSWORD` | | `dub` | `DUB_API_KEY` | | `ga4` | `GA4_ACCESS_TOKEN` | | `google-ads` | `GOOGLE_ADS_TOKEN`, `GOOGLE_ADS_DEVELOPER_TOKEN` | | `google-search-console` | `GSC_ACCESS_TOKEN` | +| `keywords-everywhere` | `KEYWORDS_EVERYWHERE_API_KEY` | | `kit` | `KIT_API_KEY`, `KIT_API_SECRET` | | `linkedin-ads` | `LINKEDIN_ACCESS_TOKEN` | | `mailchimp` | `MAILCHIMP_API_KEY` | @@ -104,6 +106,8 @@ DOMAINS=$(rewardful affiliates list | jq -r '.data[].email') | `ahrefs.js` | SEO | [Ahrefs](https://ahrefs.com) | | `semrush.js` | SEO | [SEMrush](https://semrush.com) | | `google-search-console.js` | SEO | [Google Search Console](https://search.google.com/search-console) | +| `dataforseo.js` | SEO | [DataForSEO](https://dataforseo.com) | +| `keywords-everywhere.js` | SEO | [Keywords Everywhere](https://keywordseverywhere.com) | | `ga4.js` | Analytics | [Google Analytics 4](https://analytics.google.com) | | `mixpanel.js` | Analytics | [Mixpanel](https://mixpanel.com) | | `amplitude.js` | Analytics | [Amplitude](https://amplitude.com) | diff --git a/tools/clis/dataforseo.js b/tools/clis/dataforseo.js new file mode 100755 index 0000000..9bf0fdb --- /dev/null +++ b/tools/clis/dataforseo.js @@ -0,0 +1,254 @@ +#!/usr/bin/env node + +const LOGIN = process.env.DATAFORSEO_LOGIN +const PASSWORD = process.env.DATAFORSEO_PASSWORD +const BASE_URL = 'https://api.dataforseo.com/v3' + +if (!LOGIN || !PASSWORD) { + console.error(JSON.stringify({ error: 'DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD environment variables required' })) + process.exit(1) +} + +const AUTH = 'Basic ' + Buffer.from(`${LOGIN}:${PASSWORD}`).toString('base64') + +async function api(method, path, body) { + const res = await fetch(`${BASE_URL}${path}`, { + method, + headers: { + 'Authorization': AUTH, + 'Content-Type': 'application/json', + }, + body: body ? JSON.stringify(body) : undefined, + }) + const text = await res.text() + try { + return JSON.parse(text) + } catch { + return { status: res.status, body: text } + } +} + +function parseArgs(args) { + const result = { _: [] } + for (let i = 0; i < args.length; i++) { + const arg = args[i] + if (arg.startsWith('--')) { + const key = arg.slice(2) + const next = args[i + 1] + if (next && !next.startsWith('--')) { + result[key] = next + i++ + } else { + result[key] = true + } + } else { + result._.push(arg) + } + } + return result +} + +const args = parseArgs(process.argv.slice(2)) +const [cmd, sub, ...rest] = args._ + +async function main() { + let result + const location = args.location || 'United States' + const locationCode = args['location-code'] ? Number(args['location-code']) : 2840 + const language = args.language || 'English' + const languageCode = args['language-code'] || 'en' + const limit = args.limit ? Number(args.limit) : 100 + + switch (cmd) { + case 'serp': + switch (sub) { + case 'google': { + const keyword = args.keyword + if (!keyword) { result = { error: '--keyword required' }; break } + result = await api('POST', '/serp/google/organic/live/regular', [{ + keyword, + location_name: location, + language_name: language, + }]) + break + } + case 'locations': + result = await api('GET', '/serp/google/locations') + break + case 'languages': + result = await api('GET', '/serp/google/languages') + break + default: + result = { error: 'Unknown serp subcommand. Use: google, locations, languages' } + } + break + + case 'keywords': + switch (sub) { + case 'volume': { + const keywords = args.keywords?.split(',') + if (!keywords) { result = { error: '--keywords required (comma-separated)' }; break } + result = await api('POST', '/keywords_data/google_ads/search_volume/live', [{ + keywords, + location_code: locationCode, + language_code: languageCode, + }]) + break + } + case 'for-site': { + const target = args.target + if (!target) { result = { error: '--target required (domain)' }; break } + result = await api('POST', '/keywords_data/google_ads/keywords_for_site/live', [{ + target, + location_code: locationCode, + language_code: languageCode, + }]) + break + } + case 'for-keywords': { + const keywords = args.keywords?.split(',') + if (!keywords) { result = { error: '--keywords required (comma-separated)' }; break } + result = await api('POST', '/keywords_data/google_ads/keywords_for_keywords/live', [{ + keywords, + location_code: locationCode, + language_code: languageCode, + }]) + break + } + case 'trends': { + const keywords = args.keywords?.split(',') + if (!keywords) { result = { error: '--keywords required (comma-separated)' }; break } + result = await api('POST', '/keywords_data/google_trends/explore/live', [{ + keywords, + location_code: locationCode, + language_code: languageCode, + }]) + break + } + default: + result = { error: 'Unknown keywords subcommand. Use: volume, for-site, for-keywords, trends' } + } + break + + case 'backlinks': + switch (sub) { + case 'summary': { + const target = args.target + if (!target) { result = { error: '--target required' }; break } + result = await api('POST', '/backlinks/summary/live', [{ + target, + backlinks_status_type: 'live', + }]) + break + } + case 'list': { + const target = args.target + if (!target) { result = { error: '--target required' }; break } + result = await api('POST', '/backlinks/backlinks/live', [{ + target, + mode: args.mode || 'as_is', + limit, + backlinks_status_type: 'live', + }]) + break + } + case 'refdomains': { + const target = args.target + if (!target) { result = { error: '--target required' }; break } + result = await api('POST', '/backlinks/referring_domains/live', [{ + target, + limit, + }]) + break + } + case 'anchors': { + const target = args.target + if (!target) { result = { error: '--target required' }; break } + result = await api('POST', '/backlinks/anchors/live', [{ + target, + limit, + }]) + break + } + case 'index': + result = await api('GET', '/backlinks/index') + break + default: + result = { error: 'Unknown backlinks subcommand. Use: summary, list, refdomains, anchors, index' } + } + break + + case 'onpage': + switch (sub) { + case 'audit': { + const url = args.url + if (!url) { result = { error: '--url required' }; break } + result = await api('POST', '/on_page/instant_pages', [{ + url, + enable_javascript: args['no-js'] ? false : true, + }]) + break + } + default: + result = { error: 'Unknown onpage subcommand. Use: audit' } + } + break + + case 'labs': + switch (sub) { + case 'competitors': { + const target = args.target + if (!target) { result = { error: '--target required' }; break } + result = await api('POST', '/dataforseo_labs/google/competitors_domain/live', [{ + target, + location_code: locationCode, + language_code: languageCode, + limit, + }]) + break + } + case 'ranked-keywords': { + const target = args.target + if (!target) { result = { error: '--target required' }; break } + result = await api('POST', '/dataforseo_labs/google/ranked_keywords/live', [{ + target, + location_code: locationCode, + language_code: languageCode, + limit, + }]) + break + } + case 'domain-intersection': { + const targets = args.targets?.split(',') + if (!targets || targets.length < 2) { result = { error: '--targets required (comma-separated, at least 2 domains)' }; break } + const payload = { location_code: locationCode, language_code: languageCode, limit } + targets.forEach((t, i) => { payload[`target${i + 1}`] = t }) + result = await api('POST', '/dataforseo_labs/google/domain_intersection/live', [payload]) + break + } + default: + result = { error: 'Unknown labs subcommand. Use: competitors, ranked-keywords, domain-intersection' } + } + break + + default: + result = { + error: 'Unknown command', + usage: { + serp: 'serp [google --keyword | locations | languages]', + keywords: 'keywords [volume --keywords | for-site --target | for-keywords --keywords | trends --keywords ]', + backlinks: 'backlinks [summary --target | list --target | refdomains --target | anchors --target | index]', + onpage: 'onpage [audit --url ]', + labs: 'labs [competitors --target | ranked-keywords --target | domain-intersection --targets ]', + options: '--location-code --language-code --limit ', + } + } + } + + console.log(JSON.stringify(result, null, 2)) +} + +main().catch(err => { + console.error(JSON.stringify({ error: err.message })) + process.exit(1) +}) diff --git a/tools/clis/keywords-everywhere.js b/tools/clis/keywords-everywhere.js new file mode 100755 index 0000000..18809c8 --- /dev/null +++ b/tools/clis/keywords-everywhere.js @@ -0,0 +1,181 @@ +#!/usr/bin/env node + +const API_KEY = process.env.KEYWORDS_EVERYWHERE_API_KEY +const BASE_URL = 'https://api.keywordseverywhere.com/v1' + +if (!API_KEY) { + console.error(JSON.stringify({ error: 'KEYWORDS_EVERYWHERE_API_KEY environment variable required' })) + process.exit(1) +} + +async function api(method, path, body) { + const res = await fetch(`${BASE_URL}${path}`, { + method, + headers: { + 'Authorization': `Bearer ${API_KEY}`, + 'Content-Type': 'application/json', + 'Accept': 'application/json', + }, + body: body ? JSON.stringify(body) : undefined, + }) + const text = await res.text() + try { + return JSON.parse(text) + } catch { + return { status: res.status, body: text } + } +} + +function parseArgs(args) { + const result = { _: [] } + for (let i = 0; i < args.length; i++) { + const arg = args[i] + if (arg.startsWith('--')) { + const key = arg.slice(2) + const next = args[i + 1] + if (next && !next.startsWith('--')) { + result[key] = next + i++ + } else { + result[key] = true + } + } else { + result._.push(arg) + } + } + return result +} + +const args = parseArgs(process.argv.slice(2)) +const [cmd, sub, ...rest] = args._ + +async function main() { + let result + const country = args.country || 'us' + const currency = args.currency || 'USD' + const dataSource = args['data-source'] || 'gkp' + + switch (cmd) { + case 'keywords': + switch (sub) { + case 'data': { + const kw = args.kw?.split(',') + if (!kw) { result = { error: '--kw required (comma-separated keywords, max 100)' }; break } + result = await api('POST', '/get_keyword_data', { country, currency, dataSource, kw }) + break + } + case 'related': { + const kw = args.kw?.split(',') + if (!kw) { result = { error: '--kw required (comma-separated keywords)' }; break } + result = await api('POST', '/get_related_keywords', { country, currency, dataSource, kw }) + break + } + case 'pasf': { + const kw = args.kw?.split(',') + if (!kw) { result = { error: '--kw required (comma-separated keywords)' }; break } + result = await api('POST', '/get_pasf_keywords', { country, currency, dataSource, kw }) + break + } + default: + result = { error: 'Unknown keywords subcommand. Use: data, related, pasf' } + } + break + + case 'domain': + switch (sub) { + case 'keywords': { + const domain = args.domain + if (!domain) { result = { error: '--domain required' }; break } + result = await api('POST', '/get_domain_keywords', { country, currency, domain }) + break + } + case 'traffic': { + const domain = args.domain + if (!domain) { result = { error: '--domain required' }; break } + result = await api('POST', '/get_domain_traffic', { country, domain }) + break + } + case 'backlinks': { + const domain = args.domain + if (!domain) { result = { error: '--domain required' }; break } + result = await api('POST', '/get_domain_backlinks', { domain }) + break + } + case 'unique-backlinks': { + const domain = args.domain + if (!domain) { result = { error: '--domain required' }; break } + result = await api('POST', '/get_unique_domain_backlinks', { domain }) + break + } + default: + result = { error: 'Unknown domain subcommand. Use: keywords, traffic, backlinks, unique-backlinks' } + } + break + + case 'url': + switch (sub) { + case 'keywords': { + const url = args.url + if (!url) { result = { error: '--url required' }; break } + result = await api('POST', '/get_url_keywords', { country, currency, url }) + break + } + case 'traffic': { + const url = args.url + if (!url) { result = { error: '--url required' }; break } + result = await api('POST', '/get_url_traffic', { country, url }) + break + } + case 'backlinks': { + const url = args.url + if (!url) { result = { error: '--url required' }; break } + result = await api('POST', '/get_page_backlinks', { url }) + break + } + case 'unique-backlinks': { + const url = args.url + if (!url) { result = { error: '--url required' }; break } + result = await api('POST', '/get_unique_page_backlinks', { url }) + break + } + default: + result = { error: 'Unknown url subcommand. Use: keywords, traffic, backlinks, unique-backlinks' } + } + break + + case 'account': + switch (sub) { + case 'credits': + result = await api('GET', '/get_credits') + break + case 'countries': + result = await api('GET', '/get_countries') + break + case 'currencies': + result = await api('GET', '/get_currencies') + break + default: + result = { error: 'Unknown account subcommand. Use: credits, countries, currencies' } + } + break + + default: + result = { + error: 'Unknown command', + usage: { + keywords: 'keywords [data|related|pasf] --kw ', + domain: 'domain [keywords|traffic|backlinks|unique-backlinks] --domain ', + url: 'url [keywords|traffic|backlinks|unique-backlinks] --url ', + account: 'account [credits|countries|currencies]', + options: '--country --currency --data-source ', + } + } + } + + console.log(JSON.stringify(result, null, 2)) +} + +main().catch(err => { + console.error(JSON.stringify({ error: err.message })) + process.exit(1) +}) diff --git a/tools/integrations/dataforseo.md b/tools/integrations/dataforseo.md new file mode 100644 index 0000000..a1155af --- /dev/null +++ b/tools/integrations/dataforseo.md @@ -0,0 +1,165 @@ +# DataForSEO + +Comprehensive SEO data API for SERP results, keyword research, backlinks, and on-page analysis. + +## Capabilities + +| Integration | Available | Notes | +|-------------|-----------|-------| +| API | ✓ | SERP, Keywords Data, Backlinks, On-Page, Labs | +| MCP | - | Not available | +| CLI | ✓ | [dataforseo.js](../clis/dataforseo.js) | +| SDK | ✓ | Python, TypeScript, PHP, Java, C# | + +## Authentication + +- **Type**: Basic Auth +- **Header**: `Authorization: Basic {base64(login:password)}` +- **Get credentials**: API Access tab at https://app.dataforseo.com/api-access +- **Note**: API password is auto-generated, different from account password + +## Common Agent Operations + +### SERP - Google organic (live) + +```bash +POST https://api.dataforseo.com/v3/serp/google/organic/live/regular + +[{ + "keyword": "marketing automation", + "location_name": "United States", + "language_name": "English" +}] +``` + +### Keywords - Search volume (live) + +```bash +POST https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/live + +[{ + "keywords": ["email marketing", "marketing automation", "crm software"], + "location_code": 2840, + "language_code": "en" +}] +``` + +### Keywords - Keywords for site (live) + +```bash +POST https://api.dataforseo.com/v3/keywords_data/google_ads/keywords_for_site/live + +[{ + "target": "example.com", + "location_code": 2840, + "language_code": "en" +}] +``` + +### Backlinks - Summary + +```bash +POST https://api.dataforseo.com/v3/backlinks/summary/live + +[{ + "target": "example.com", + "internal_list_limit": 10, + "backlinks_status_type": "live" +}] +``` + +### Backlinks - List + +```bash +POST https://api.dataforseo.com/v3/backlinks/backlinks/live + +[{ + "target": "example.com", + "mode": "as_is", + "limit": 100, + "backlinks_status_type": "live" +}] +``` + +### Backlinks - Referring domains + +```bash +POST https://api.dataforseo.com/v3/backlinks/referring_domains/live + +[{ + "target": "example.com", + "limit": 100 +}] +``` + +### Backlinks - Index (database stats) + +```bash +GET https://api.dataforseo.com/v3/backlinks/index +``` + +### On-Page - Instant pages audit + +```bash +POST https://api.dataforseo.com/v3/on_page/instant_pages + +[{ + "url": "https://example.com/page", + "enable_javascript": true +}] +``` + +### SERP - Locations list + +```bash +GET https://api.dataforseo.com/v3/serp/google/locations +``` + +### SERP - Languages list + +```bash +GET https://api.dataforseo.com/v3/serp/google/languages +``` + +## API Pattern + +DataForSEO uses two methods for most endpoints: +- **Live** (`/live`) - Synchronous, results in same response +- **Task-based** (`/task_post` + `/task_get/$id`) - Async for large requests + +Request bodies are always JSON arrays (even for single requests). + +## Key Metrics + +### Keyword Metrics +- `search_volume` - Monthly search volume +- `competition` - Competition level (0-1) +- `cpc` - Cost per click +- `monthly_searches` - Monthly breakdown array + +### Backlink Metrics +- `total_backlinks` - Total backlink count +- `referring_domains` - Unique referring domains +- `domain_rank` - Domain authority score +- `backlinks_spam_score` - Spam score + +## When to Use + +- Programmatic SERP tracking at scale +- Keyword research with search volume data +- Backlink analysis and monitoring +- On-page SEO audits +- Competitor analysis + +## Rate Limits + +- Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining` +- Backlinks API: 2000 requests/minute, 30 simultaneous +- Varies by endpoint and plan + +## Relevant Skills + +- seo-audit +- programmatic-seo +- content-strategy +- competitor-alternatives diff --git a/tools/integrations/keywords-everywhere.md b/tools/integrations/keywords-everywhere.md new file mode 100644 index 0000000..fa5bb02 --- /dev/null +++ b/tools/integrations/keywords-everywhere.md @@ -0,0 +1,207 @@ +# Keywords Everywhere + +Keyword research API for search volume, CPC, competition, related keywords, and traffic data. + +## Capabilities + +| Integration | Available | Notes | +|-------------|-----------|-------| +| API | ✓ | REST API for keyword data, related keywords, traffic | +| MCP | - | Community MCP server available | +| CLI | ✓ | [keywords-everywhere.js](../clis/keywords-everywhere.js) | +| SDK | - | API-only | + +## Authentication + +- **Type**: API Key (Bearer token) +- **Header**: `Authorization: Bearer {api_key}` +- **Get key**: https://keywordseverywhere.com/first-install-addon.html +- **Limit**: 100 keywords per request + +## Common Agent Operations + +### Get keyword data (volume, CPC, competition) + +```bash +POST https://api.keywordseverywhere.com/v1/get_keyword_data + +Authorization: Bearer {api_key} + +{ + "country": "us", + "currency": "USD", + "dataSource": "gkp", + "kw": ["email marketing", "marketing automation", "crm software"] +} +``` + +### Get related keywords + +```bash +POST https://api.keywordseverywhere.com/v1/get_related_keywords + +Authorization: Bearer {api_key} + +{ + "country": "us", + "currency": "USD", + "dataSource": "gkp", + "kw": ["email marketing"] +} +``` + +### Get "People Also Search For" keywords + +```bash +POST https://api.keywordseverywhere.com/v1/get_pasf_keywords + +Authorization: Bearer {api_key} + +{ + "country": "us", + "currency": "USD", + "dataSource": "gkp", + "kw": ["email marketing"] +} +``` + +### Get domain keywords (what a domain ranks for) + +```bash +POST https://api.keywordseverywhere.com/v1/get_domain_keywords + +Authorization: Bearer {api_key} + +{ + "country": "us", + "currency": "USD", + "domain": "example.com" +} +``` + +### Get URL keywords (what a specific URL ranks for) + +```bash +POST https://api.keywordseverywhere.com/v1/get_url_keywords + +Authorization: Bearer {api_key} + +{ + "country": "us", + "currency": "USD", + "url": "https://example.com/page" +} +``` + +### Get domain traffic + +```bash +POST https://api.keywordseverywhere.com/v1/get_domain_traffic + +Authorization: Bearer {api_key} + +{ + "country": "us", + "domain": "example.com" +} +``` + +### Get URL traffic + +```bash +POST https://api.keywordseverywhere.com/v1/get_url_traffic + +Authorization: Bearer {api_key} + +{ + "country": "us", + "url": "https://example.com/page" +} +``` + +### Get domain backlinks + +```bash +POST https://api.keywordseverywhere.com/v1/get_domain_backlinks + +Authorization: Bearer {api_key} + +{ + "domain": "example.com" +} +``` + +### Get page backlinks + +```bash +POST https://api.keywordseverywhere.com/v1/get_page_backlinks + +Authorization: Bearer {api_key} + +{ + "url": "https://example.com/page" +} +``` + +### Check credits + +```bash +GET https://api.keywordseverywhere.com/v1/get_credits + +Authorization: Bearer {api_key} +``` + +### Get supported countries + +```bash +GET https://api.keywordseverywhere.com/v1/get_countries + +Authorization: Bearer {api_key} +``` + +### Get supported currencies + +```bash +GET https://api.keywordseverywhere.com/v1/get_currencies + +Authorization: Bearer {api_key} +``` + +## Key Metrics + +### Keyword Data +- `vol` - Monthly search volume +- `cpc.value` - Cost per click +- `competition` - Competition score +- `trend` - 12-month trend data + +### Traffic Data +- `estimated_traffic` - Estimated monthly traffic +- `keywords_count` - Number of ranking keywords + +## Parameters + +- `country` - Country code (us, uk, de, fr, etc.) +- `currency` - Currency code (USD, GBP, EUR, etc.) +- `dataSource` - Data source, default `gkp` (Google Keyword Planner) +- `kw` - Array of keywords (max 100 per request) + +## When to Use + +- Quick keyword research with volume and CPC +- Finding related keywords and PASF suggestions +- Analyzing domain/URL keyword rankings +- Traffic estimation for domains and pages +- Backlink discovery + +## Rate Limits + +- 100 keywords per request +- Credit-based pricing (1 credit per keyword) + +## Relevant Skills + +- seo-audit +- content-strategy +- programmatic-seo +- competitor-alternatives