@serpstat/serpstat-mcp-server 1.0.8 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [1.1.0] - 2025-10-01
+
+### Added
+
+- **Site Audit Tools**: Added thirteen methods for comprehensive site audit project management and analysis
+    - `get_site_audit_settings` - Retrieve audit settings for a specific project including scan parameters, scheduling options, email notifications, and error detection thresholds (does not consume API credits)
+    - `set_site_audit_settings` - Update audit settings for a project with comprehensive configuration options for scan speed, user agent, URL depth, folder depth, keywords filtering, HTTP authentication, scheduling, and custom error thresholds (does not consume API credits)
+    - `start_site_audit` - Start an audit session for a specified project and receive a reportId to track audit progress (consumes 1 API credit per successfully scanned page without JS rendering, 10 credits per page with JS rendering)
+    - `stop_site_audit` - Stop an active audit session for a project and receive operation result status (does not consume API credits)
+    - `get_site_audit_results_by_categories` - Get audit results statistics grouped by issue categories (pages status, meta tags, headings, content, multimedia, indexation, redirects, links, HTTPS, hreflang, AMP, markup, pagespeed) showing critical, medium, low, and informational issue counts per category (does not consume API credits)
+    - `get_site_audit_history` - Get historical error count data for a specific error type across multiple audit reports, useful for tracking improvements or regressions in specific SEO issues over time (does not consume API credits)
+    - `get_site_audits_list` - Get list of all audit reports for a project with summary statistics including SDO score, pages scanned, error counts, progress percentage, and completion status (does not consume API credits)
+    - `get_site_audit_scanned_urls_list` - Get list of URLs that will be scanned based on project scan settings (entire domain, specific URLs only, or imported list) useful for verifying audit scope before starting scans (does not consume API credits)
+    - `get_site_audit_project_default_settings` - Get default audit settings template with recommended values for creating new projects, including standard error thresholds, scan parameters, and scheduling options (does not consume API credits)
+    - `get_site_audit_bref_info` - Get essential summary information from the latest site audit including Serpstat Domain Optimization Score (SDO), total error counts by priority level (high/medium/low/information), virus count, scan progress percentage, stop status, scanned pages count, redirect count, and captcha detection status (does not consume API credits)
+    - `get_site_audit_deteailed_report` - Get the number of errors and issues categorized by issue type found in a specific audit report, with optional comparison to another report showing countAll (total errors), countNew (new errors since comparison), and countFixed (fixed errors since comparison) for tracking audit improvements over time (does not consume API credits)
+    - `get_site_audit_pages_spec_errors` - Get a comprehensive list of all pages where a specific audit error was detected, with support for filtering by error display mode (all errors, new errors, or solved errors) and pagination, returning detailed information including startUrl, HTTP status code, finishUrl, occurrence count, and startUrlCrc for each affected page (does not consume API credits)
+    - `get_site_audit_elements_with_issues` - Get a list of sub-elements (URLs) which contain specific errors or issues identified by CRC parameter from get_site_audit_pages_spec_errors response, with support for filtering by mode and pagination, useful for drilling down into specific error instances (does not consume API credits)
+- Added comprehensive validation schemas and TypeScript types for all site audit operations
+- Added test coverage for all site audit methods (51 tests covering validation schemas and service methods)
+- Updated documentation with complete site audit tools section and usage examples
+
+## [1.0.9] - 2025-10-01
+
+### Added
+
+- **URL Analysis Tools**: Added four new methods for analyzing website URLs and their search performance
+    - `get_url_summary_traff` - Get traffic and keyword statistics for website pages matching a specific URL mask, showing organic traffic and keyword counts for URLs matching the given pattern
+    - `get_url_competitors` - Get list of URL competitors showing domains and pages that compete for the same keywords in top-10 search results
+    - `get_url_keywords` - Get keywords for which specified URL ranks in top-100 Google and top-50 Bing search results, with comprehensive metrics including positions, traffic, difficulty, and keyword intents
+    - `get_url_missing_keywords` - Get keywords that competitors rank for but the given URL does not, helping identify keyword gaps and content optimization opportunities
+- Added comprehensive validation schemas and TypeScript types for URL analysis operations
+- Added test coverage for all URL analysis methods (24 tests)
+- Updated documentation with URL analysis tools section and usage examples
+
 ## [1.0.8] - 2025-09-30
 
 ### Added
@@ -47,7 +82,7 @@
 - Added `get_keyword_full_top` method to show Google's top-100 search results for analyzed keywords
 - Added `get_keywords_info` method to get keyword overview with volume, CPC, competition level, difficulty, and additional metrics for multiple keywords
 - Added `get_keyword_suggestions` method to show search suggestions for keywords found by full-text search with geographic names information
-- Added `get_keyword_top_urls` method to return website pages that rank for the largest amount of analyzed keyword variations with highest traffic
+- Added `get_keyword_top_urls` method to return website pages that rank for the largest amount of analyzed keyword variations with the highest traffic
 - Added `get_keyword_competitors` method to list domains that rank for the given keyword in Google top-20 results with detailed competitor analysis
 - Added `get_keyword_top` method to show Google's top-100 search results for analyzed keyword with position, URL, domain and SERP features (deprecated method)
 - Added `get_anchors` method to analyze anchor text distribution in backlinks with metrics on referring domains, total backlinks, and nofollow counts

package/README.md

@@ -153,6 +153,11 @@ After installation and configuration in Claude Desktop, you can ask Claude:
 - "List all my rank tracker projects"
 - "Check parsing status for project **12345** in region **2840**"
 
+### Site Audit
+- "Get audit settings for project **1113915**"
+- "Start site audit for project **1113915**"
+- "Stop site audit for project **1113915**"
+
 ## MCP Tools
 
 ### Domain Analysis Tools
@@ -179,6 +184,15 @@ After installation and configuration in Claude Desktop, you can ask Claude:
 | 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   |
+
 ### Backlinks Analysis Tools
 
 | Tool Name                  | Description                                                                                   | Key Parameters               |
@@ -220,6 +234,24 @@ After installation and configuration in Claude Desktop, you can ask Claude:
 | 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 |
+
 ### Search Engines (se parameter)
 
 Common search engine codes:

package/dist/handlers/site_audit_tools.d.ts

@@ -0,0 +1,107 @@
+import { BaseHandler } from './base.js';
+import { MCPToolCall, MCPToolResponse } from '../types/mcp.js';
+export declare class GetSiteAuditSettingsHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class SetSiteAuditSettingsHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class StartSiteAuditHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class StopSiteAuditHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetCategoriesStatisticHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetHistoryByCountErrorHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetSiteAuditsListHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetScanUserUrlListHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetDefaultSettingsHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetBasicInfoHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetReportWithoutDetailsHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetErrorElementsHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetSubElementsByCrcHandler extends BaseHandler {
+    private siteAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+//# sourceMappingURL=site_audit_tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"site_audit_tools.d.ts","sourceRoot":"","sources":["../../src/handlers/site_audit_tools.ts"],"names":[],"mappings":"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"}