@serpstat/serpstat-mcp-server 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [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
+
+- **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

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": "9184b2aa2328fd93bf002ed4c59e4e8e"
       }
     }
   }
 }
 ```
 
+### 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 (63 total tools across all categories).
+
 ## Usage Examples
 
 After installation and configuration in Claude Desktop, you can ask Claude:
@@ -252,6 +310,22 @@ After installation and configuration in Claude Desktop, you can ask Claude:
 | 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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"}