@serpstat/serpstat-mcp-server 1.0.9 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [1.1.1] - 2025-10-04
+
+### Added
+
+- **One-Page Audit Tools Enhancement**: Added seven additional methods for comprehensive one-page audit management and analysis
+    - `page_audit_rescan` - Rescan existing one-page audit project and create new audit report with updated settings (consumes 10 API credits per rescan)
+    - `page_audit_stop` - Stop active one-page audit scan and receive operation result status (does not consume API credits)
+    - `page_audit_delete` - Remove one-page audit project from customer project list permanently (does not consume API credits)
+    - `page_audit_get_report_by_categories` - Get audit results by categories for a specific report with error grouping by type and support for comparing with previous reports to track changes (does not consume API credits)
+    - `page_audit_report_drill_down` - Get detailed error rows for specific audit error type with filtering by mode (all/new/solved), pagination support, and affected URL list (does not consume API credits)
+    - `page_audit_get_scan_names` - Get list of all one-page audit project names with URLs and finished report counts for project discovery (does not consume API credits)
+    - `page_audit_scan_logs` - Get user log for audit report with chronological scan events, message types (info/warning/error), parameters, and timestamps for debugging and progress tracking (does not consume API credits)
+- Added comprehensive validation schemas and TypeScript types for all new one-page audit operations
+- Added test coverage for all new one-page audit methods (21 tests covering validation schemas and edge cases)
+- Updated documentation with enhanced one-page audit tools section and complete API reference
+
+## [1.1.1] - 2025-10-03
+
+### Added
+
+- **One-Page Audit Tools**: Added four methods for single-page audit analysis with JavaScript rendering support
+    - `page_audit_start_scan` - Scan a single webpage with JavaScript rendering and receive pageId and reportId for tracking progress (consumes 10 API credits per scan)
+    - `page_audit_get_last_scans` - Get list of all one-page audit projects with latest scan results, SDO scores, and settings information (does not consume API credits)
+    - `page_audit_get_reports_for_page` - Get history of all audit reports for a specific page with status, SDO scores, error counts by priority, and progress tracking (does not consume API credits)
+    - `page_audit_get_results_report` - Get detailed audit results for a page with error categories grouped by type (meta tags, headings, content, multimedia, etc.) and complete issue breakdown showing priority levels and error counts (does not consume API credits)
+- Added comprehensive validation schemas and TypeScript types for all one-page audit operations
+- Added test coverage for all one-page audit methods (12 tests covering validation schemas)
+- Updated documentation with one-page audit tools section and usage examples
+
+## [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
@@ -60,7 +111,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
@@ -229,6 +234,40 @@ 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 |
+
+### 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) |
+
 ### Search Engines (se parameter)
 
 Common search engine codes:

package/dist/handlers/one_page_audit_tools.d.ts

@@ -0,0 +1,91 @@
+import { BaseHandler } from './base.js';
+import { MCPToolCall, MCPToolResponse } from '../types/mcp.js';
+export declare class StartOnePageAuditScanHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetOnePageAuditsListHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetOnePageReportsListHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetOnePageAuditResultsHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class RescanOnePageAuditHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class StopOnePageAuditHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class RemoveOnePageAuditHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetOnePageAuditByCategoriesHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetOnePageAuditErrorRowsHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetOnePageAuditPageNamesHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+export declare class GetOnePageAuditUserLogHandler extends BaseHandler {
+    private onePageAuditService;
+    constructor();
+    getName(): string;
+    getDescription(): string;
+    getInputSchema(): object;
+    handle(call: MCPToolCall): Promise<MCPToolResponse>;
+}
+//# sourceMappingURL=one_page_audit_tools.d.ts.map

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

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