@serpstat/serpstat-mcp-server 1.0.5 → 1.0.6

package/dist/handlers/backlinks_tools.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GetLostBacklinksHandler = exports.GetReferringDomainsHandler = exports.GetActiveBacklinksHandler = exports.GetAnchorsHandler = exports.BacklinksSummaryHandler = void 0;
+exports.GetThreatBacklinksHandler = exports.GetActiveOutlinkDomainsHandler = exports.GetActiveOutlinksHandler = exports.GetBacklinksIntersectionHandler = exports.GetTopPagesByBacklinksHandler = exports.GetTopAnchorsHandler = exports.GetLostBacklinksHandler = exports.GetReferringDomainsHandler = exports.GetActiveBacklinksHandler = exports.GetAnchorsHandler = exports.BacklinksSummaryHandler = void 0;
 const base_js_1 = require("./base.js");
 const backlinks_tools_js_1 = require("../services/backlinks_tools.js");
 const validation_js_1 = require("../utils/validation.js");
@@ -306,7 +306,7 @@ class GetLostBacklinksHandler extends base_js_1.BaseHandler {
         return 'get_lost_backlinks';
     }
     getDescription() {
-        return 'Get a list of lost backlinks showing linking pages, target pages, link attributes, and deletion dates for domain or URL analysis';
+        return 'Get a list of lost backlinks showing linking pages, target pages, link attributes, and deletion dates for domain or URL analysis, **use sort by check desc** to get recently lost backlinks';
     }
     getInputSchema() {
         return {
@@ -405,4 +405,654 @@ class GetLostBacklinksHandler extends base_js_1.BaseHandler {
     }
 }
 exports.GetLostBacklinksHandler = GetLostBacklinksHandler;
+class GetTopAnchorsHandler extends base_js_1.BaseHandler {
+    backlinksService;
+    constructor() {
+        super();
+        const config = (0, config_js_1.loadConfig)();
+        this.backlinksService = new backlinks_tools_js_1.BacklinksService(config);
+    }
+    getName() {
+        return 'get_top10_anchors';
+    }
+    getDescription() {
+        return 'Get TOP-10 anchors with the number of backlinks and referring domains for domain analysis, use this method is you need a fast brief way to get info about top 10 anchors';
+    }
+    getInputSchema() {
+        return {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    minLength: constants_js_1.MIN_DOMAIN_LENGTH,
+                    maxLength: constants_js_1.MAX_DOMAIN_LENGTH,
+                    description: "Domain name to analyze"
+                },
+                searchType: {
+                    type: "string",
+                    enum: constants_js_1.SEARCH_TYPES,
+                    default: "domain",
+                    description: "Type of search: domain or domain_with_subdomains"
+                }
+            },
+            required: ["query"],
+            additionalProperties: false
+        };
+    }
+    async handle(call) {
+        try {
+            const params = validation_js_1.getTopAnchorsSchema.parse(call.arguments);
+            const result = await this.backlinksService.getTopAnchors(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.GetTopAnchorsHandler = GetTopAnchorsHandler;
+class GetTopPagesByBacklinksHandler extends base_js_1.BaseHandler {
+    backlinksService;
+    constructor() {
+        super();
+        const config = (0, config_js_1.loadConfig)();
+        this.backlinksService = new backlinks_tools_js_1.BacklinksService(config);
+    }
+    getName() {
+        return 'get_top_pages_by_backlinks';
+    }
+    getDescription() {
+        return 'Get leading pages by backlinks using Serpstat API. Returns pages with the highest number of referring pages, domains, and IP addresses for comprehensive backlink analysis.';
+    }
+    getInputSchema() {
+        return {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    minLength: constants_js_1.MIN_DOMAIN_LENGTH,
+                    maxLength: constants_js_1.MAX_DOMAIN_LENGTH,
+                    description: "Domain name to analyze"
+                },
+                searchType: {
+                    type: "string",
+                    enum: constants_js_1.SEARCH_TYPES,
+                    default: "domain",
+                    description: "Type of search: domain or domain_with_subdomains"
+                },
+                sort: {
+                    type: "string",
+                    enum: constants_js_1.TOP_PAGES_SORT_FIELDS,
+                    default: "lastupdate",
+                    description: "Field to sort results by"
+                },
+                order: {
+                    type: "string",
+                    enum: constants_js_1.SORT_ORDER,
+                    description: "Sort order: asc or desc"
+                },
+                complexFilter: {
+                    type: "array",
+                    items: {
+                        type: "array",
+                        items: {
+                            oneOf: [
+                                {
+                                    type: "object",
+                                    properties: {
+                                        field: {
+                                            type: "string",
+                                            enum: constants_js_1.TOP_PAGES_COMPLEX_FILTER_FIELDS
+                                        },
+                                        compareType: {
+                                            type: "string",
+                                            enum: constants_js_1.COMPLEX_FILTER_COMPARE_TYPES
+                                        },
+                                        value: {
+                                            type: "array",
+                                            items: {
+                                                oneOf: [
+                                                    { type: "string" },
+                                                    { type: "number" }
+                                                ]
+                                            }
+                                        }
+                                    },
+                                    required: ["field", "compareType", "value"],
+                                    additionalProperties: false
+                                },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        additional_filters: {
+                                            type: "string",
+                                            enum: constants_js_1.ADDITIONAL_FILTERS
+                                        }
+                                    },
+                                    required: ["additional_filters"],
+                                    additionalProperties: false
+                                }
+                            ]
+                        }
+                    },
+                    description: "Complex filters for advanced filtering"
+                },
+                page: {
+                    type: "integer",
+                    minimum: constants_js_1.MIN_PAGE,
+                    default: 1,
+                    description: "Page number for pagination"
+                },
+                size: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: constants_js_1.MAX_PAGE_SIZE,
+                    default: constants_js_1.DEFAULT_PAGE_SIZE,
+                    description: "Number of results per page"
+                }
+            },
+            required: ["query"],
+            additionalProperties: false
+        };
+    }
+    async handle(call) {
+        try {
+            const params = validation_js_1.getTopPagesByBacklinksSchema.parse(call.arguments);
+            const result = await this.backlinksService.getTopPagesByBacklinks(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.GetTopPagesByBacklinksHandler = GetTopPagesByBacklinksHandler;
+class GetBacklinksIntersectionHandler extends base_js_1.BaseHandler {
+    backlinksService;
+    constructor() {
+        super();
+        const config = (0, config_js_1.loadConfig)();
+        this.backlinksService = new backlinks_tools_js_1.BacklinksService(config);
+    }
+    getName() {
+        return 'get_backlinks_intersection';
+    }
+    getDescription() {
+        return 'Get backlinks from domains that link to multiple analyzed sites simultaneously. This method reveals shared referring domains between your target domain and competitors, useful for competitive backlink analysis and identifying potential link sources. Returns intersection data showing which donors link to multiple domains in your analysis set, including link metrics, anchor texts, and domain authority scores.';
+    }
+    getInputSchema() {
+        return {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    minLength: constants_js_1.MIN_DOMAIN_LENGTH,
+                    maxLength: constants_js_1.MAX_DOMAIN_LENGTH,
+                    description: "Main domain to analyze for backlinks intersection"
+                },
+                intersect: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        minLength: constants_js_1.MIN_DOMAIN_LENGTH,
+                        maxLength: constants_js_1.MAX_DOMAIN_LENGTH
+                    },
+                    minItems: 1,
+                    maxItems: constants_js_1.MAX_INTERSECT_DOMAINS,
+                    description: "Array of competitor domains for intersection analysis"
+                },
+                sort: {
+                    type: "string",
+                    enum: constants_js_1.BACKLINKS_INTERSECTION_SORT_FIELDS,
+                    default: "domain_rank",
+                    description: "Field to sort results by (domain_rank, links_count1, links_count2, links_count3)"
+                },
+                order: {
+                    type: "string",
+                    enum: constants_js_1.SORT_ORDER,
+                    default: "desc",
+                    description: "Sort order: asc or desc"
+                },
+                complexFilter: {
+                    type: "array",
+                    items: {
+                        type: "array",
+                        items: {
+                            oneOf: [
+                                {
+                                    type: "object",
+                                    properties: {
+                                        field: {
+                                            type: "string",
+                                            enum: constants_js_1.BACKLINKS_INTERSECTION_COMPLEX_FILTER_FIELDS
+                                        },
+                                        compareType: {
+                                            type: "string",
+                                            enum: constants_js_1.COMPLEX_FILTER_COMPARE_TYPES
+                                        },
+                                        value: {
+                                            type: "array",
+                                            items: {
+                                                oneOf: [
+                                                    { type: "string" },
+                                                    { type: "number" }
+                                                ]
+                                            }
+                                        }
+                                    },
+                                    required: ["field", "compareType", "value"],
+                                    additionalProperties: false
+                                },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        additional_filters: {
+                                            type: "string",
+                                            enum: constants_js_1.ADDITIONAL_FILTERS
+                                        }
+                                    },
+                                    required: ["additional_filters"],
+                                    additionalProperties: false
+                                }
+                            ]
+                        }
+                    },
+                    description: "Complex filters for advanced filtering"
+                },
+                page: {
+                    type: "integer",
+                    minimum: constants_js_1.MIN_PAGE,
+                    default: 1,
+                    description: "Page number for pagination"
+                },
+                size: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: constants_js_1.MAX_PAGE_SIZE,
+                    default: constants_js_1.DEFAULT_PAGE_SIZE,
+                    description: "Number of results per page"
+                }
+            },
+            required: ["query", "intersect"],
+            additionalProperties: false
+        };
+    }
+    async handle(call) {
+        try {
+            const params = validation_js_1.getBacklinksIntersectionSchema.parse(call.arguments);
+            const result = await this.backlinksService.getBacklinksIntersection(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.GetBacklinksIntersectionHandler = GetBacklinksIntersectionHandler;
+class GetActiveOutlinksHandler extends base_js_1.BaseHandler {
+    backlinksService;
+    constructor() {
+        super();
+        const config = (0, config_js_1.loadConfig)();
+        this.backlinksService = new backlinks_tools_js_1.BacklinksService(config);
+    }
+    getName() {
+        return 'get_active_outlinks';
+    }
+    getDescription() {
+        return 'Get active outbound links from a domain or URL. Returns external links the site points to, including target URLs, anchor text, link attributes (nofollow/dofollow), link types, and discovery dates. Useful for analyzing linking strategies, finding partnership opportunities, and auditing outbound link profiles.';
+    }
+    getInputSchema() {
+        return {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    minLength: constants_js_1.MIN_DOMAIN_LENGTH,
+                    maxLength: constants_js_1.MAX_DOMAIN_LENGTH,
+                    description: "Domain name or URL to analyze for outbound links"
+                },
+                searchType: {
+                    type: "string",
+                    enum: constants_js_1.SEARCH_TYPES_URL,
+                    default: "domain",
+                    description: "Type of search: domain, domain_with_subdomains, url, or part_url"
+                },
+                sort: {
+                    type: "string",
+                    enum: constants_js_1.ACTIVE_OUTLINKS_SORT_FIELDS,
+                    default: "check",
+                    description: "Field to sort results by"
+                },
+                order: {
+                    type: "string",
+                    enum: constants_js_1.SORT_ORDER,
+                    default: "desc",
+                    description: "Sort order: asc or desc"
+                },
+                linkPerDomain: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "Maximum number of links to return per domain"
+                },
+                complexFilter: {
+                    type: "array",
+                    items: {
+                        type: "array",
+                        items: {
+                            oneOf: [
+                                {
+                                    type: "object",
+                                    properties: {
+                                        field: {
+                                            type: "string",
+                                            enum: constants_js_1.ACTIVE_OUTLINKS_COMPLEX_FILTER_FIELDS
+                                        },
+                                        compareType: {
+                                            type: "string",
+                                            enum: constants_js_1.COMPLEX_FILTER_COMPARE_TYPES
+                                        },
+                                        value: {
+                                            type: "array",
+                                            items: {
+                                                oneOf: [
+                                                    { type: "string" },
+                                                    { type: "number" }
+                                                ]
+                                            }
+                                        }
+                                    },
+                                    required: ["field", "compareType", "value"],
+                                    additionalProperties: false
+                                },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        additional_filters: {
+                                            type: "string",
+                                            enum: constants_js_1.ADDITIONAL_FILTERS
+                                        }
+                                    },
+                                    required: ["additional_filters"],
+                                    additionalProperties: false
+                                }
+                            ]
+                        }
+                    },
+                    description: "Complex filters for advanced filtering"
+                },
+                page: {
+                    type: "integer",
+                    minimum: constants_js_1.MIN_PAGE,
+                    default: 1,
+                    description: "Page number for pagination"
+                },
+                size: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: constants_js_1.MAX_PAGE_SIZE,
+                    default: constants_js_1.DEFAULT_PAGE_SIZE,
+                    description: "Number of results per page"
+                }
+            },
+            required: ["query", "searchType"],
+            additionalProperties: false
+        };
+    }
+    async handle(call) {
+        try {
+            const params = validation_js_1.getActiveOutlinksSchema.parse(call.arguments);
+            const result = await this.backlinksService.getActiveOutlinks(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.GetActiveOutlinksHandler = GetActiveOutlinksHandler;
+class GetActiveOutlinkDomainsHandler extends base_js_1.BaseHandler {
+    backlinksService;
+    constructor() {
+        super();
+        const config = (0, config_js_1.loadConfig)();
+        this.backlinksService = new backlinks_tools_js_1.BacklinksService(config);
+    }
+    getName() {
+        return 'get_active_outlink_domains';
+    }
+    getDescription() {
+        return 'Get external domains that receive outbound links from the analyzed domain. Returns target domains with total link counts, revealing partnership networks, referenced sources, and linking patterns. Helps identify collaboration opportunities by analyzing which domains competitors link to.';
+    }
+    getInputSchema() {
+        return {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Domain name to analyze outbound link destinations",
+                    minLength: constants_js_1.MIN_DOMAIN_LENGTH,
+                    maxLength: constants_js_1.MAX_DOMAIN_LENGTH
+                },
+                searchType: {
+                    type: "string",
+                    enum: constants_js_1.SEARCH_TYPES_URL,
+                    description: "Search type for analysis",
+                    default: "domain"
+                },
+                sort: {
+                    type: "string",
+                    enum: constants_js_1.ACTIVE_OUTLINK_DOMAINS_SORT_FIELDS,
+                    description: "Field to sort results by",
+                    default: "domain_rank"
+                },
+                order: {
+                    type: "string",
+                    enum: constants_js_1.SORT_ORDER,
+                    description: "Sort order",
+                    default: "desc"
+                },
+                complexFilter: {
+                    type: "array",
+                    description: "Complex filtering conditions",
+                    items: {
+                        type: "array",
+                        items: {
+                            anyOf: [
+                                {
+                                    type: "object",
+                                    properties: {
+                                        field: {
+                                            type: "string",
+                                            enum: constants_js_1.ACTIVE_OUTLINK_DOMAINS_COMPLEX_FILTER_FIELDS
+                                        },
+                                        compareType: {
+                                            type: "string",
+                                            enum: constants_js_1.COMPLEX_FILTER_COMPARE_TYPES
+                                        },
+                                        value: {
+                                            type: "array",
+                                            items: {
+                                                oneOf: [
+                                                    { type: "integer" },
+                                                    { type: "string" }
+                                                ]
+                                            }
+                                        }
+                                    },
+                                    required: ["field", "compareType", "value"]
+                                },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        additional_filters: {
+                                            type: "string",
+                                            enum: ["only_subdomains", "only_hosts", "last_week"]
+                                        }
+                                    },
+                                    required: ["additional_filters"]
+                                }
+                            ]
+                        }
+                    }
+                },
+                page: {
+                    type: "integer",
+                    description: "Page number for pagination",
+                    minimum: constants_js_1.MIN_PAGE,
+                    default: 1
+                },
+                size: {
+                    type: "integer",
+                    description: "Number of results per page",
+                    minimum: 1,
+                    maximum: constants_js_1.MAX_PAGE_SIZE,
+                    default: constants_js_1.DEFAULT_PAGE_SIZE
+                }
+            },
+            required: ["query", "searchType"],
+            additionalProperties: false
+        };
+    }
+    async handle(call) {
+        try {
+            const params = validation_js_1.getActiveOutlinkDomainsSchema.parse(call.arguments);
+            const result = await this.backlinksService.getActiveOutlinkDomains(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.GetActiveOutlinkDomainsHandler = GetActiveOutlinkDomainsHandler;
+class GetThreatBacklinksHandler extends base_js_1.BaseHandler {
+    backlinksService;
+    constructor() {
+        super();
+        const config = (0, config_js_1.loadConfig)();
+        this.backlinksService = new backlinks_tools_js_1.BacklinksService(config);
+    }
+    getName() {
+        return 'get_threat_backlinks';
+    }
+    getDescription() {
+        return 'Get malicious backlinks pointing to the analyzed domain. Returns links from sites flagged for threats like social engineering, malware, or unwanted software. Shows referring domain, source URL, target URL, platform type, threat type, and last update date. Essential for identifying and removing harmful backlinks that could damage domain reputation and SEO rankings.';
+    }
+    getInputSchema() {
+        return {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    pattern: constants_js_1.DOMAIN_NAME_REGEX,
+                    minLength: constants_js_1.MIN_DOMAIN_LENGTH,
+                    maxLength: constants_js_1.MAX_DOMAIN_LENGTH,
+                    description: "Domain to analyze for threat backlinks"
+                },
+                searchType: {
+                    type: "string",
+                    enum: constants_js_1.SEARCH_TYPES,
+                    default: "domain",
+                    description: "Search type: 'domain' (exact domain) or 'domain_with_subdomains' (includes subdomains)"
+                },
+                sort: {
+                    type: "string",
+                    enum: constants_js_1.BACKLINKS_THREAT_SORT_FIELDS,
+                    default: "lastupdate",
+                    description: "Field to sort by: lastupdate, url_from, url_to, platform_type, threat_type"
+                },
+                order: {
+                    type: "string",
+                    enum: constants_js_1.SORT_ORDER,
+                    default: "desc",
+                    description: "Sort order: asc or desc"
+                },
+                linkPerDomain: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "Maximum number of links per domain to return"
+                },
+                complexFilter: {
+                    type: "array",
+                    description: "Complex filtering conditions using field-value pairs with comparison operators",
+                    items: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                field: {
+                                    type: "string",
+                                    enum: constants_js_1.BACKLINKS_THREAT_COMPLEX_FILTER_FIELDS,
+                                    description: "Field to filter by"
+                                },
+                                compareType: {
+                                    type: "string",
+                                    enum: constants_js_1.COMPLEX_FILTER_COMPARE_TYPES,
+                                    description: "Comparison operator for filtering"
+                                },
+                                value: {
+                                    type: "array",
+                                    description: "Values to compare against",
+                                    items: {
+                                        oneOf: [
+                                            { type: "integer" },
+                                            { type: "string" }
+                                        ]
+                                    }
+                                }
+                            },
+                            required: ["field", "compareType", "value"],
+                            additionalProperties: false
+                        }
+                    }
+                },
+                page: {
+                    type: "integer",
+                    description: "Page number for pagination",
+                    minimum: constants_js_1.MIN_PAGE,
+                    default: 1
+                },
+                size: {
+                    type: "integer",
+                    description: "Number of results per page",
+                    minimum: 1,
+                    maximum: constants_js_1.MAX_PAGE_SIZE,
+                    default: constants_js_1.DEFAULT_PAGE_SIZE
+                }
+            },
+            required: ["query"],
+            additionalProperties: false
+        };
+    }
+    async handle(call) {
+        try {
+            const params = validation_js_1.getThreatBacklinksSchema.parse(call.arguments);
+            const result = await this.backlinksService.getThreatBacklinks(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.GetThreatBacklinksHandler = GetThreatBacklinksHandler;
 //# sourceMappingURL=backlinks_tools.js.map