@serpstat/serpstat-mcp-server 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.1.3] - 2025-11-27
+
+### Added
+
+- **Market Research Tools**: Added two new methods for analyzing competitive landscape by market categories
+    - `get_market_categories` - Get complete list of available market research categories (1000+ hierarchical categories organized by industry verticals like Arts & Entertainment, Business & Industrial, E-commerce, Health & Fitness, etc.) with unique category IDs in format .X.Y.Z. for use in competitive analysis (does not consume API credits)
+    - `get_category_top_domains` - Get top-performing domains in a specific market category with comprehensive SEO metrics including traffic, visibility, keywords count, referring domains, backlinks, and Serpstat Domain Rank (SDR). Supports filtering by various metrics (traffic, visibility, keywords, backlinks, SDR) and sorting options (global rank, category rank, traffic, visibility). Useful for competitive landscape analysis and market leader identification (consumes 1 API credit per result row)
+- Added comprehensive validation schemas and TypeScript types for market research operations
+- Added test coverage for market research methods (6 new tests covering validation schemas and service methods)
+- Updated documentation with market research usage examples and tools reference in README.md
+- Domain Analysis Tools category now includes 8 tools (previously 6), bringing total tool count to 65 across all categories
+
+## [1.1.2] - 2025-10-24
+
+### Added
+
+- **Category Filtering**: Added support for filtering tools by categories via `SERPSTAT_ENABLED_CATEGORIES` environment variable
+    - Enable only specific tool categories to reduce context window usage in AI assistants
+    - Comma-separated list of categories: `domain`, `keywords`, `backlinks`, `url`, `projects`, `credits`, `rt`, `audit`, `page-audit`
+    - Default behavior (no filter): all 63 tools available across 9 categories
+    - Example: `SERPSTAT_ENABLED_CATEGORIES=keywords,domain` loads only keyword research (8 tools) and domain analysis (6 tools) tools
+    - Useful for creating specialized configurations focused on specific SEO analysis areas
+- Updated documentation with category filtering examples in README.md and CLAUDE.md
+- Added category-based handler organization in `src/server.ts` for maintainable tool management
+
+
 ## [1.1.1] - 2025-10-04
 
 ### Added

package/README.md

@@ -1,6 +1,7 @@
 # Serpstat MCP Server
 
 [![npm version](https://badge.fury.io/js/@serpstat%2Fserpstat-mcp-server.svg)](https://badge.fury.io/js/@serpstat%2Fserpstat-mcp-server)
+[![MCP Badge](https://lobehub.com/badge/mcp/serpstatglobal-serpstat-mcp-server-js)](https://lobehub.com/mcp/serpstatglobal-serpstat-mcp-server-js)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A TypeScript server that integrates Serpstat SEO API with Anthropic's Model Context Protocol (MCP), enabling AI assistants like Claude to access comprehensive SEO data and analysis tools.
@@ -66,6 +67,7 @@ Set the following environment variables (can be in .env file):
 - `SERPSTAT_API_TOKEN` — Your Serpstat API token (required)
 - `SERPSTAT_API_URL` — Serpstat API URL (default: https://api.serpstat.com/v4)
 - `LOG_LEVEL` — Logging level: error, warn, info, debug (default: info)
+- `SERPSTAT_ENABLED_CATEGORIES` — Filter tools by categories (optional, comma-separated, default: all categories enabled)
 
 ### Claude Desktop & Gemini CLI Configuration
 
@@ -104,13 +106,69 @@ For local development, use the full path:
       "command": "node",
       "args": ["/path/to/node_modules/serpstat-mcp-server/dist/index.js"],
       "env": {
-        "SERPSTAT_API_TOKEN": "your_serpstat_api_token_here"
+        "SERPSTAT_API_TOKEN": "YOUR_SERPSTAT_API_TOKEN_HERE"
       }
     }
   }
 }
 ```
 
+### Filtering Tools by Category
+
+You can limit which tools are available by specifying `SERPSTAT_ENABLED_CATEGORIES` environment variable. This is useful for:
+- Reducing context window usage in AI assistants
+- Focusing on specific SEO analysis areas
+- Creating specialized configurations for different use cases
+
+**Available categories:**
+- `domain` - Domain analysis tools (domain info, competitors, domain keywords, etc.)
+- `keywords` - Keyword research tools (keyword suggestions, search volume, difficulty, etc.)
+- `backlinks` - Backlink analysis tools (backlink summary, anchors, referring domains, etc.)
+- `url` - URL analysis tools (URL traffic, competitors, keywords, etc.)
+- `projects` - Project management tools (create, list, delete projects)
+- `credits` - Credits and usage monitoring tools
+- `rt` - Rank tracking tools (rank history, SERP tracking, etc.)
+- `audit` - Site audit tools (full site SEO audit, error reports, etc.)
+- `page-audit` - One-page audit tools (single page analysis, on-page SEO, etc.)
+
+**Example: Enable only keyword and domain tools**
+
+```json
+{
+  "mcpServers": {
+    "serpstat": {
+      "command": "npx",
+      "args": ["-y", "@serpstat/serpstat-mcp-server"],
+      "env": {
+        "SERPSTAT_API_TOKEN": "YOUR_SERPSTAT_API_TOKEN_HERE",
+        "SERPSTAT_ENABLED_CATEGORIES": "keywords,domain"
+      }
+    }
+  }
+}
+```
+
+**Example: Enable only backlink analysis**
+
+```json
+{
+  "mcpServers": {
+    "serpstat": {
+      "command": "npx",
+      "args": ["-y", "@serpstat/serpstat-mcp-server"],
+      "env": {
+        "SERPSTAT_API_TOKEN": "YOUR_SERPSTAT_API_TOKEN_HERE",
+        "SERPSTAT_ENABLED_CATEGORIES": "backlinks"
+      }
+    }
+  }
+}
+```
+
+**Default behavior (all tools enabled):**
+
+If `SERPSTAT_ENABLED_CATEGORIES` is not specified or is empty, all tools are available (65 total tools across all categories).
+
 ## Usage Examples
 
 After installation and configuration in Claude Desktop, you can ask Claude:
@@ -120,6 +178,13 @@ After installation and configuration in Claude Desktop, you can ask Claude:
 - "Find competitors for **my-site.com** in Google US"
 - "Get top 50 keywords that **example.com** ranks for"
 
+### Market Research
+- "Show me all available market research categories"
+- "Find top domains in **'E-commerce'** category for Google US"
+- "Get top 20 domains in **'/Arts & Entertainment/TV & Video'** category sorted by traffic"
+- "Analyze competitive landscape in **'Business & Industrial'** category with domains that have SDR above 50"
+- "Find leading players in **'Health & Fitness'** market with minimum 100k monthly traffic"
+
 ### Keyword Research
 - "Find related keywords to **'digital marketing'**"
 - "Get keyword suggestions for **'iphone 15'** excluding **'rent'** keywords"
@@ -162,111 +227,113 @@ After installation and configuration in Claude Desktop, you can ask Claude:
 
 ### Domain Analysis Tools
 
-| Tool Name                | Description                                                              | Key Parameters           |
-|--------------------------|--------------------------------------------------------------------------|--------------------------|
-| get_domains_info         | Get SEO information for multiple domains                                 | domains, se, filters     |
-| get_domain_competitors   | Get list of competitor domains                                           | domain, se, size, filters|
-| get_domain_keywords      | Get keywords that domain ranks for                                       | domain, se, page, size   |
-| get_domain_urls          | Get URLs within a domain and their keyword counts                        | domain, se, page, size   |
-| get_domain_regions_count | Get keyword count by region for a domain                                 | domain, sort, order      |
-| get_domain_uniq_keywords | Get unique keywords for two domains not ranked by a third domain         | se, domains, minusDomain |
+| Tool Name                | Description                                                               | Key Parameters                             |
+|--------------------------|---------------------------------------------------------------------------|--------------------------------------------|
+| get_domains_info         | Get SEO information for multiple domains                                  | domains, se, filters                       |
+| get_domain_competitors   | Get list of competitor domains                                            | domain, se, size, filters                  |
+| get_domain_keywords      | Get keywords that domain ranks for                                        | domain, se, page, size                     |
+| get_domain_urls          | Get URLs within a domain and their keyword counts                         | domain, se, page, size                     |
+| get_domain_regions_count | Get keyword count by region for a domain                                  | domain, sort, order                        |
+| get_domain_uniq_keywords | Get unique keywords for two domains not ranked by a third domain          | se, domains, minusDomain                   |
+| get_market_categories    | Get complete list of 1000+ market research categories                     | none                                       |
+| get_category_top_domains | Get top-performing domains in a specific market category with SEO metrics | category_id, se, filters, sort, page, size |
 
 ### Keyword Research Tools
 
-| Tool Name               | Description                                                                                      | Key Parameters             |
-|-------------------------|--------------------------------------------------------------------------------------------------|----------------------------|
-| get_keywords            | Get related organic keywords for a given keyword                                                 | keyword, se, filters       |
-| get_related_keywords    | Get semantically related keywords with frequency, CPC, competition, and difficulty data          | keyword, se, filters, sort |
-| get_keyword_suggestions | Get search suggestions for a keyword using full-text search with geographic names info           | keyword, se, filters       |
-| get_keywords_info       | Get keyword overview with volume, CPC, competition, difficulty, and SERP features                | keywords, se, withIntents  |
-| get_keyword_full_top    | Get Google's top-100 search results for analyzed keywords                                        | keyword, se, size          |
-| get_keyword_top_urls    | Get website pages that rank for the largest amount of analyzed keyword variations                | keyword, se, page, page_size|
-| get_keyword_competitors | Get domains that rank for the given keyword in Google top-20 results with competitor analysis    | keyword, se, filters, sort |
-| get_keyword_top         | Get Google's top-100 search results for the analyzed keyword with position, URL, and SERP features| keyword, se, filters, size |
+| Tool Name               | Description                                                                                        | Key Parameters               |
+|-------------------------|----------------------------------------------------------------------------------------------------|------------------------------|
+| get_keywords            | Get related organic keywords for a given keyword                                                   | keyword, se, filters         |
+| get_related_keywords    | Get semantically related keywords with frequency, CPC, competition, and difficulty data            | keyword, se, filters, sort   |
+| get_keyword_suggestions | Get search suggestions for a keyword using full-text search with geographic names info             | keyword, se, filters         |
+| get_keywords_info       | Get keyword overview with volume, CPC, competition, difficulty, and SERP features                  | keywords, se, withIntents    |
+| get_keyword_full_top    | Get Google's top-100 search results for analyzed keywords                                          | keyword, se, size            |
+| get_keyword_top_urls    | Get website pages that rank for the largest amount of analyzed keyword variations                  | keyword, se, page, page_size |
+| get_keyword_competitors | Get domains that rank for the given keyword in Google top-20 results with competitor analysis      | keyword, se, filters, sort   |
+| get_keyword_top         | Get Google's top-100 search results for the analyzed keyword with position, URL, and SERP features | keyword, se, filters, size   |
 
 ### URL Analysis Tools
 
-| Tool Name                 | Description                                                                                        | Key Parameters           |
-|---------------------------|---------------------------------------------------------------------------------------------------|--------------------------|
-| get_url_summary_traff     | Get traffic and keyword statistics for website pages matching a specific URL mask                | se, domain, urlContains  |
-| get_url_competitors       | Get list of URL competitors showing domains competing for same keywords in top-10 results        | se, url, sort, page      |
-| get_url_keywords          | Get keywords for which specified URL ranks in top-100 Google and top-50 Bing search results     | se, url, filters, sort   |
-| get_url_missing_keywords  | Get keywords that competitors rank for but the given URL does not, identifying keyword gaps      | url, se, filters, sort   |
+| Tool Name                | Description                                                                                 | Key Parameters          |
+|--------------------------|---------------------------------------------------------------------------------------------|-------------------------|
+| get_url_summary_traff    | Get traffic and keyword statistics for website pages matching a specific URL mask           | se, domain, urlContains |
+| get_url_competitors      | Get list of URL competitors showing domains competing for same keywords in top-10 results   | se, url, sort, page     |
+| get_url_keywords         | Get keywords for which specified URL ranks in top-100 Google and top-50 Bing search results | se, url, filters, sort  |
+| get_url_missing_keywords | Get keywords that competitors rank for but the given URL does not, identifying keyword gaps | url, se, filters, sort  |
 
 ### Backlinks Analysis Tools
 
-| Tool Name                  | Description                                                                                   | Key Parameters               |
-|----------------------------|-----------------------------------------------------------------------------------------------|------------------------------|
-| get_backlinks_summary      | Get comprehensive backlinks summary with referring domains, quality metrics, and changes      | domain, subdomain            |
-| get_anchors                | Get anchor text analysis for backlinks with metrics on referring domains and backlinks        | query, searchType, anchor, sort|
-| get_active_backlinks       | Get a list of active backlinks showing linking pages, target pages, and link attributes       | query, searchType, sort, page|
-| get_referring_domains      | Get a list of referring domains with domain rank metrics and referring pages count            | query, searchType, sort, page|
-| get_lost_backlinks         | Get a list of lost backlinks showing linking pages, target pages, and deletion dates          | query, searchType, sort, page|
-| get_top_pages_by_backlinks | Get a list of top pages by backlinks with various filtering and sorting parameters            | query, searchType, sort, size|
-| get_top10_anchors          | Get TOP-10 anchors with the number of backlinks and referring domains                         | query, searchType            |
-| get_backlinks_intersection | Get backlinks from domains that link to multiple analyzed sites for competitive analysis      | query, intersect, sort, page |
-| get_active_outlinks        | Get active outbound links from a domain or URL with target URLs and anchor text               | query, searchType, sort, filters|
-| get_active_outlink_domains | Get external domains that receive outbound links from analyzed domain                         | query, searchType, sort, filters|
-| get_threat_backlinks       | Get malicious backlinks pointing to analyzed domain from sites flagged for security threats   | query, searchType, sort, filters|
+| Tool Name                  | Description                                                                                 | Key Parameters                   |
+|----------------------------|---------------------------------------------------------------------------------------------|----------------------------------|
+| get_backlinks_summary      | Get comprehensive backlinks summary with referring domains, quality metrics, and changes    | domain, subdomain                |
+| get_anchors                | Get anchor text analysis for backlinks with metrics on referring domains and backlinks      | query, searchType, anchor, sort  |
+| get_active_backlinks       | Get a list of active backlinks showing linking pages, target pages, and link attributes     | query, searchType, sort, page    |
+| get_referring_domains      | Get a list of referring domains with domain rank metrics and referring pages count          | query, searchType, sort, page    |
+| get_lost_backlinks         | Get a list of lost backlinks showing linking pages, target pages, and deletion dates        | query, searchType, sort, page    |
+| get_top_pages_by_backlinks | Get a list of top pages by backlinks with various filtering and sorting parameters          | query, searchType, sort, size    |
+| get_top10_anchors          | Get TOP-10 anchors with the number of backlinks and referring domains                       | query, searchType                |
+| get_backlinks_intersection | Get backlinks from domains that link to multiple analyzed sites for competitive analysis    | query, intersect, sort, page     |
+| get_active_outlinks        | Get active outbound links from a domain or URL with target URLs and anchor text             | query, searchType, sort, filters |
+| get_active_outlink_domains | Get external domains that receive outbound links from analyzed domain                       | query, searchType, sort, filters |
+| get_threat_backlinks       | Get malicious backlinks pointing to analyzed domain from sites flagged for security threats | query, searchType, sort, filters |
 
 ### Project Management Tools
 
-| Tool Name      | Description                                                                    | Key Parameters       |
-|----------------|--------------------------------------------------------------------------------|----------------------|
-| create_project | Create a new project in Serpstat for tracking SEO metrics and site audits     | domain, name, groups |
-| delete_project | Delete an existing project from Serpstat by project ID                        | project_id           |
-| list_projects  | Retrieve a list of projects associated with the account with pagination       | page, size           |
+| Tool Name      | Description                                                               | Key Parameters       |
+|----------------|---------------------------------------------------------------------------|----------------------|
+| create_project | Create a new project in Serpstat for tracking SEO metrics and site audits | domain, name, groups |
+| delete_project | Delete an existing project from Serpstat by project ID                    | project_id           |
+| list_projects  | Retrieve a list of projects associated with the account with pagination   | page, size           |
 
 ### Credits & Usage Monitoring Tools
 
-| Tool Name                   | Description                                                                                  | Key Parameters |
-|-----------------------------|----------------------------------------------------------------------------------------------|----------------|
+| Tool Name                   | Description                                                                                 | Key Parameters |
+|-----------------------------|---------------------------------------------------------------------------------------------|----------------|
 | get_credits_for_audit_stats | Check available audit credits (one-page audit, JavaScript scanning, crawl limits) *No cost* | none           |
 | get_credits_stats           | Check API credits usage, account info, and browser plugin limits *No cost*                  | none           |
 
 ### Rank Tracking Tools
 
-| Tool Name                           | Description                                                                                      | Key Parameters                |
-|-------------------------------------|--------------------------------------------------------------------------------------------------|-------------------------------|
-| get_rt_projects_list                | Get rank tracker projects with ID, name, domain, creation date, and tracking status *No cost*   | page, pageSize                |
-| get_rt_project_status               | Check if rank tracker project is parsing (true=processing, false=ready) *No cost*               | projectId, regionId           |
-| get_rt_project_regions_list         | Get list of regions for a rank tracker project with status, SERP type, device, and location *No cost* | projectId                    |
-| get_rt_project_keyword_serp_history | Get Google's top-100 SERP history for rank tracker keywords with positions and URLs *No cost*   | projectId, projectRegionId, page|
-| get_rt_project_url_serp_history     | Get ranking history of URLs for rank tracker keywords with historical position data *No cost*   | projectId, projectRegionId, page|
+| Tool Name                           | Description                                                                                           | Key Parameters                   |
+|-------------------------------------|-------------------------------------------------------------------------------------------------------|----------------------------------|
+| get_rt_projects_list                | Get rank tracker projects with ID, name, domain, creation date, and tracking status *No cost*         | page, pageSize                   |
+| get_rt_project_status               | Check if rank tracker project is parsing (true=processing, false=ready) *No cost*                     | projectId, regionId              |
+| get_rt_project_regions_list         | Get list of regions for a rank tracker project with status, SERP type, device, and location *No cost* | projectId                        |
+| get_rt_project_keyword_serp_history | Get Google's top-100 SERP history for rank tracker keywords with positions and URLs *No cost*         | projectId, projectRegionId, page |
+| get_rt_project_url_serp_history     | Get ranking history of URLs for rank tracker keywords with historical position data *No cost*         | projectId, projectRegionId, page |
 
 ### Site Audit Tools
 
-| Tool Name                   | Description                                                                                                                      | Key Parameters              |
-|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
-| get_site_audit_settings                 | Get audit settings for a project including scan parameters, scheduling, and error thresholds *No cost*                          | projectId                        |
-| set_site_audit_settings                 | Update audit settings for a project with scan configuration, scheduling, and notifications *No cost*                            | projectId, mainSettings, ...     |
-| start_site_audit                        | Start audit session for a project and receive reportId for tracking progress (1 credit/page, 10 credits/page with JS rendering) | projectId                        |
-| stop_site_audit                         | Stop active audit session for a project *No cost*                                                                               | projectId                        |
-| get_site_audit_results_by_categories    | Get audit results statistics grouped by issue categories (pages status, meta tags, links, etc.) *No cost*                       | reportId                         |
-| get_site_audit_history                  | Get historical error count data for a specific error type across multiple audit reports *No cost*                               | projectId, errorName, limit, offset |
-| get_site_audits_list                    | Get list of all audit reports for a project with summary statistics and progress information *No cost*                          | projectId, limit, offset         |
-| get_site_audit_scanned_urls_list        | Get list of URLs that will be scanned based on project scan settings *No cost*                                                  | projectId                        |
-| get_site_audit_project_default_settings | Get default audit settings template to use when creating new projects *No cost*                                                 | -                                |
-| get_site_audit_bref_info                | Get essential summary information from latest audit including SDO score, issue counts by priority, scan progress, and completion status *No cost* | reportId                         |
-| get_site_audit_deteailed_report         | Get number of errors categorized by type with comparison to previous report showing countAll, countNew, and countFixed *No cost* | reportId, compareReportId (optional) |
-| get_site_audit_pages_spec_errors        | Get list of all pages where a specific error was detected with filtering by mode (all/new/solved) and pagination support *No cost* | reportId, compareReportId, projectId, errorName, mode, limit, offset |
-| get_site_audit_elements_with_issues     | Get list of sub-elements (URLs) containing specific errors using CRC from get_site_audit_pages_spec_errors response *No cost*  | reportId, projectId, errorName, crc, compareReportId (optional), mode, limit, offset |
+| Tool Name                               | Description                                                                                                                                       | Key Parameters                                                                       |
+|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
+| get_site_audit_settings                 | Get audit settings for a project including scan parameters, scheduling, and error thresholds *No cost*                                            | projectId                                                                            |
+| set_site_audit_settings                 | Update audit settings for a project with scan configuration, scheduling, and notifications *No cost*                                              | projectId, mainSettings, ...                                                         |
+| start_site_audit                        | Start audit session for a project and receive reportId for tracking progress (1 credit/page, 10 credits/page with JS rendering)                   | projectId                                                                            |
+| stop_site_audit                         | Stop active audit session for a project *No cost*                                                                                                 | projectId                                                                            |
+| get_site_audit_results_by_categories    | Get audit results statistics grouped by issue categories (pages status, meta tags, links, etc.) *No cost*                                         | reportId                                                                             |
+| get_site_audit_history                  | Get historical error count data for a specific error type across multiple audit reports *No cost*                                                 | projectId, errorName, limit, offset                                                  |
+| get_site_audits_list                    | Get list of all audit reports for a project with summary statistics and progress information *No cost*                                            | projectId, limit, offset                                                             |
+| get_site_audit_scanned_urls_list        | Get list of URLs that will be scanned based on project scan settings *No cost*                                                                    | projectId                                                                            |
+| get_site_audit_project_default_settings | Get default audit settings template to use when creating new projects *No cost*                                                                   | -                                                                                    |
+| get_site_audit_bref_info                | Get essential summary information from latest audit including SDO score, issue counts by priority, scan progress, and completion status *No cost* | reportId                                                                             |
+| get_site_audit_deteailed_report         | Get number of errors categorized by type with comparison to previous report showing countAll, countNew, and countFixed *No cost*                  | reportId, compareReportId (optional)                                                 |
+| get_site_audit_pages_spec_errors        | Get list of all pages where a specific error was detected with filtering by mode (all/new/solved) and pagination support *No cost*                | reportId, compareReportId, projectId, errorName, mode, limit, offset                 |
+| get_site_audit_elements_with_issues     | Get list of sub-elements (URLs) containing specific errors using CRC from get_site_audit_pages_spec_errors response *No cost*                     | reportId, projectId, errorName, crc, compareReportId (optional), mode, limit, offset |
 
 ### One Page Audit Tools
 
-| Tool Name                      | Description                                                                                                                      | Key Parameters              |
-|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
-| page_audit_start_scan          | Scan a single webpage with JavaScript rendering. Returns pageId and reportId for tracking. Use page_audit_get_reports_for_page to check progress via status and progress fields (10 credits per scan) | name, url, userAgent (recommended: 0 for Chrome), httpAuthLogin (optional), httpAuthPass (optional) |
-| page_audit_get_last_scans      | Get list of all one-page audit projects with pageId, url, name, status, lastActiveReport (latest scan results with SDO score), finishedReportCount, settings *No cost* | limit (optional, default 30), offset (optional, default 0), teamMemberId (optional) |
-| page_audit_get_reports_for_page | Get history of all audit reports for a specific page with reportId, auditDate, status (1=in progress, 3=finalizing, 4=completed), SDO score (0-100), error counts, progress (0-100) *No cost* | pageId, limit (optional), offset (optional) |
-| page_audit_get_results_report  | Get detailed audit results with categories array (errors grouped by meta_tags, headings, content, multimedia, https, pagespeed_desktop/mobile, etc), hasAdditionRows flag for drill-down availability *No cost* | pageId (from page_audit_get_last_scans or page_audit_start_scan) |
-| page_audit_rescan              | Rescan existing one-page audit project and create new audit report. Returns reportId. Track progress via page_audit_get_reports_for_page (10 credits per rescan) | pageId, name, userAgent (recommended: 0 for Chrome), httpAuthLogin (optional), httpAuthPass (optional) |
-| page_audit_stop                | Stop active one-page audit scan. Returns boolean indicating success *No cost*                                                   | pageId                      |
-| page_audit_delete              | Remove one-page audit project from customer project list permanently. Returns boolean *No cost*                                 | pageId                      |
-| page_audit_get_report_by_categories | Get audit results by categories for specific report. Use compareReportId to see countNew (errors added) and countFixed (errors resolved) *No cost* | reportId, compareReportId (optional, enables change tracking) |
-| page_audit_report_drill_down   | Get detailed problematic elements list. ONLY works for errors with hasAdditionRows=true. Response varies by error type (e.g., image URLs for multimedia errors) *No cost* | reportId, error (must match error.key), mode (all/new/solved, optional), compareReportId (optional), page (optional), size (optional, max 1000) |
-| page_audit_get_scan_names      | Get list of all one-page audit project names with pageId, name, url, finishedReportCount for project discovery *No cost*       | teamMemberId (optional)     |
-| page_audit_scan_logs           | Get chronological log of scan events with message (event name), type (info/warning/error), params (event-specific data or []), created_at timestamp for debugging *No cost* | reportId (optional, all scans if not specified), page (optional, default 0), pageSize (optional, default 100) |
+| Tool Name                           | Description                                                                                                                                                                                                     | Key Parameters                                                                                                                                  |
+|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| page_audit_start_scan               | Scan a single webpage with JavaScript rendering. Returns pageId and reportId for tracking. Use page_audit_get_reports_for_page to check progress via status and progress fields (10 credits per scan)           | name, url, userAgent (recommended: 0 for Chrome), httpAuthLogin (optional), httpAuthPass (optional)                                             |
+| page_audit_get_last_scans           | Get list of all one-page audit projects with pageId, url, name, status, lastActiveReport (latest scan results with SDO score), finishedReportCount, settings *No cost*                                          | limit (optional, default 30), offset (optional, default 0), teamMemberId (optional)                                                             |
+| page_audit_get_reports_for_page     | Get history of all audit reports for a specific page with reportId, auditDate, status (1=in progress, 3=finalizing, 4=completed), SDO score (0-100), error counts, progress (0-100) *No cost*                   | pageId, limit (optional), offset (optional)                                                                                                     |
+| page_audit_get_results_report       | Get detailed audit results with categories array (errors grouped by meta_tags, headings, content, multimedia, https, pagespeed_desktop/mobile, etc), hasAdditionRows flag for drill-down availability *No cost* | pageId (from page_audit_get_last_scans or page_audit_start_scan)                                                                                |
+| page_audit_rescan                   | Rescan existing one-page audit project and create new audit report. Returns reportId. Track progress via page_audit_get_reports_for_page (10 credits per rescan)                                                | pageId, name, userAgent (recommended: 0 for Chrome), httpAuthLogin (optional), httpAuthPass (optional)                                          |
+| page_audit_stop                     | Stop active one-page audit scan. Returns boolean indicating success *No cost*                                                                                                                                   | pageId                                                                                                                                          |
+| page_audit_delete                   | Remove one-page audit project from customer project list permanently. Returns boolean *No cost*                                                                                                                 | pageId                                                                                                                                          |
+| page_audit_get_report_by_categories | Get audit results by categories for specific report. Use compareReportId to see countNew (errors added) and countFixed (errors resolved) *No cost*                                                              | reportId, compareReportId (optional, enables change tracking)                                                                                   |
+| page_audit_report_drill_down        | Get detailed problematic elements list. ONLY works for errors with hasAdditionRows=true. Response varies by error type (e.g., image URLs for multimedia errors) *No cost*                                       | reportId, error (must match error.key), mode (all/new/solved, optional), compareReportId (optional), page (optional), size (optional, max 1000) |
+| page_audit_get_scan_names           | Get list of all one-page audit project names with pageId, name, url, finishedReportCount for project discovery *No cost*                                                                                        | teamMemberId (optional)                                                                                                                         |
+| page_audit_scan_logs                | Get chronological log of scan events with message (event name), type (info/warning/error), params (event-specific data or []), created_at timestamp for debugging *No cost*                                     | reportId (optional, all scans if not specified), page (optional, default 0), pageSize (optional, default 100)                                   |
 
 ### Search Engines (se parameter)
 

package/dist/handlers/domain_tools.d.ts

@@ -48,4 +48,20 @@ export declare class GetDomainUniqKeywordsHandler extends BaseHandler {
     getInputSchema(): object;
     handle(call: MCPToolCall): Promise<MCPToolResponse>;
 }
+export declare class GetMarketCategoriesHandler extends BaseHandler {
+    private domainService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetCategoryTopDomainsHandler extends BaseHandler {
+    private domainService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
 //# sourceMappingURL=domain_tools.d.ts.map

package/dist/handlers/domain_tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domain_tools.d.ts","sourceRoot":"","sources":["../../src/handlers/domain_tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAwC/D,qBAAa,kBAAmB,SAAQ,WAAW;IAC/C,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAwClB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAY5D;AAED,qBAAa,kBAAmB,SAAQ,WAAW;IAC/C,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAiDlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAgB5D;AAED,qBAAa,qBAAsB,SAAQ,WAAW;IAClD,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAyFlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAe5D;AAED,qBAAa,iBAAkB,SAAQ,WAAW;IAC9C,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IA2ClB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAe5D;AAED,qBAAa,yBAA0B,SAAQ,WAAW;IACtD,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAKxB,cAAc,IAAI,MAAM;IA6BlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAY5D;AAED,qBAAa,4BAA6B,SAAQ,WAAW;IACzD,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAiGlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAe5D"}
+{"version":3,"file":"domain_tools.d.ts","sourceRoot":"","sources":["../../src/handlers/domain_tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA2C/D,qBAAa,kBAAmB,SAAQ,WAAW;IAC/C,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAwClB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAY5D;AAED,qBAAa,kBAAmB,SAAQ,WAAW;IAC/C,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAiDlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAgB5D;AAED,qBAAa,qBAAsB,SAAQ,WAAW;IAClD,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAyFlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAe5D;AAED,qBAAa,iBAAkB,SAAQ,WAAW;IAC9C,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IA2ClB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAe5D;AAED,qBAAa,yBAA0B,SAAQ,WAAW;IACtD,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAKxB,cAAc,IAAI,MAAM;IA6BlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAY5D;AAED,qBAAa,4BAA6B,SAAQ,WAAW;IACzD,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAiGlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAe5D;AAED,qBAAa,0BAA2B,SAAQ,WAAW;IACvD,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IASlB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAY5D;AAED,qBAAa,4BAA6B,SAAQ,WAAW;IACzD,OAAO,CAAC,aAAa,CAAgB;;IAQrC,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,MAAM;IAqElB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAY5D"}

package/dist/handlers/domain_tools.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GetDomainUniqKeywordsHandler = exports.DomainRegionsCountHandler = exports.DomainUrlsHandler = exports.DomainKeywordsHandler = exports.CompetitorsHandler = exports.DomainsInfoHandler = void 0;
+exports.GetCategoryTopDomainsHandler = exports.GetMarketCategoriesHandler = exports.GetDomainUniqKeywordsHandler = exports.DomainRegionsCountHandler = exports.DomainUrlsHandler = exports.DomainKeywordsHandler = exports.CompetitorsHandler = exports.DomainsInfoHandler = void 0;
 const base_js_1 = require("./base.js");
 const domain_tools_js_1 = require("../services/domain_tools.js");
 const validation_js_1 = require("../utils/validation.js");
@@ -529,4 +529,136 @@ class GetDomainUniqKeywordsHandler extends base_js_1.BaseHandler {
     }
 }
 exports.GetDomainUniqKeywordsHandler = GetDomainUniqKeywordsHandler;
+class GetMarketCategoriesHandler extends base_js_1.BaseHandler {
+    domainService;
+    constructor() {
+        super();
+        const config = (0, config_js_1.loadConfig)();
+        this.domainService = new domain_tools_js_1.DomainService(config);
+    }
+    getName() {
+        return 'get_market_categories';
+    }
+    getDescription() {
+        return 'Get complete list of available market research categories (1000+ categories). Use this method first to find the appropriate category_id for your analysis. Returns hierarchical categories like \'/Arts & Entertainment/TV & Video/Online Video\' with their IDs (e.g., \'.2.13.1.\'). The category_id is required for get_category_top_domains method.';
+    }
+    getInputSchema() {
+        return {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+            description: "No parameters required - returns all available market categories"
+        };
+    }
+    async handle(call) {
+        try {
+            const params = validation_js_1.getMarketCategoriesSchema.parse(call.arguments);
+            const result = await this.domainService.getMarketCategories(params);
+            return this.createSuccessResponse(result);
+        }
+        catch (error) {
+            if (error instanceof zod_1.z.ZodError) {
+                return this.createErrorResponse(new Error(`Invalid parameters: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`));
+            }
+            return this.createErrorResponse(error);
+        }
+    }
+}
+exports.GetMarketCategoriesHandler = GetMarketCategoriesHandler;
+class GetCategoryTopDomainsHandler extends base_js_1.BaseHandler {
+    domainService;
+    constructor() {
+        super();
+        const config = (0, config_js_1.loadConfig)();
+        this.domainService = new domain_tools_js_1.DomainService(config);
+    }
+    getName() {
+        return 'get_category_top_domains';
+    }
+    getDescription() {
+        return 'Get top-performing domains in a specific market category with SEO metrics (traffic, visibility, keywords, backlinks, SDR). Requires category_id from get_market_categories - call that method first to find the right category. Returns ranked domains for competitive landscape analysis with filtering and sorting options.';
+    }
+    getInputSchema() {
+        return {
+            type: "object",
+            properties: {
+                category_id: {
+                    type: "string",
+                    pattern: constants_js_1.CATEGORY_ID_REGEX,
+                    description: "Category identifier in format .X.Y.Z. (e.g., '.2.' for Arts & Entertainment or '.2.13.1.' for Arts & Entertainment/TV & Video/Online Video). Get this from get_market_categories method."
+                },
+                se: {
+                    type: "string",
+                    enum: constants_js_1.MAIN_SEARCH_ENGINES,
+                    description: "Search engine database (e.g., g_us for Google US)"
+                },
+                filters: {
+                    type: "object",
+                    properties: {
+                        visibility: { type: "number", description: "Exact visibility score" },
+                        visibility_min: { type: "number", description: "Minimum visibility score" },
+                        visibility_max: { type: "number", description: "Maximum visibility score" },
+                        traffic: { type: "integer", description: "Exact traffic value" },
+                        traffic_min: { type: "integer", description: "Minimum traffic" },
+                        traffic_max: { type: "integer", description: "Maximum traffic" },
+                        keywords: { type: "integer", description: "Exact number of keywords" },
+                        keywords_min: { type: "integer", description: "Minimum number of keywords" },
+                        keywords_max: { type: "integer", description: "Maximum number of keywords" },
+                        referring_domains: { type: "integer", description: "Exact number of referring domains" },
+                        referring_domains_min: { type: "integer", description: "Minimum number of referring domains" },
+                        referring_domains_max: { type: "integer", description: "Maximum number of referring domains" },
+                        backlinks: { type: "integer", description: "Exact number of backlinks" },
+                        backlinks_min: { type: "integer", description: "Minimum number of backlinks" },
+                        backlinks_max: { type: "integer", description: "Maximum number of backlinks" },
+                        sdr: { type: "integer", minimum: 0, maximum: 100, description: "Exact Serpstat Domain Rank (0-100)" },
+                        sdr_min: { type: "integer", minimum: 0, maximum: 100, description: "Minimum Serpstat Domain Rank" },
+                        sdr_max: { type: "integer", minimum: 0, maximum: 100, description: "Maximum Serpstat Domain Rank" }
+                    },
+                    additionalProperties: false,
+                    description: "Filter conditions. All filters support exact value, min threshold, and max threshold."
+                },
+                sort: {
+                    type: "string",
+                    enum: constants_js_1.MARKET_CATEGORY_SORT_FIELDS,
+                    description: "Sort field (global_rank, category_rank, traffic, visibility, keywords, referring_domains, backlinks, sdr)",
+                    default: "global_rank"
+                },
+                order: {
+                    type: "string",
+                    enum: constants_js_1.SORT_ORDER,
+                    description: "Sort order (asc or desc)",
+                    default: "asc"
+                },
+                page: {
+                    type: "integer",
+                    minimum: constants_js_1.MIN_PAGE,
+                    description: "Page number",
+                    default: 1
+                },
+                size: {
+                    type: "integer",
+                    enum: constants_js_1.PROJECT_ALLOWED_PAGE_SIZES,
+                    description: "Number of results per page (allowed values: 20, 50, 100, 200, 500)",
+                    default: 100
+                }
+            },
+            required: ["category_id", "se"],
+            additionalProperties: false
+        };
+    }
+    async handle(call) {
+        try {
+            const params = validation_js_1.getCategoryTopDomainsSchema.parse(call.arguments);
+            const result = await this.domainService.getCategoryTopDomains(params);
+            return this.createSuccessResponse(result);
+        }
+        catch (error) {
+            if (error instanceof zod_1.z.ZodError) {
+                return this.createErrorResponse(new Error(`Invalid parameters: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`));
+            }
+            return this.createErrorResponse(error);
+        }
+    }
+}
+exports.GetCategoryTopDomainsHandler = GetCategoryTopDomainsHandler;
 //# sourceMappingURL=domain_tools.js.map