@rog0x/mcp-seo-tools 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# mcp-seo-tools
+
+An MCP (Model Context Protocol) server that gives AI agents a suite of SEO analysis tools. Analyze any public webpage for meta tags, heading structure, broken links, keyword density, page speed, and sitemap health — all without external API keys.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `seo_meta_analyze` | Audit meta tags, Open Graph, and Twitter Card tags with scoring |
+| `seo_heading_check` | Validate H1-H6 hierarchy, detect skipped levels and duplicates |
+| `seo_link_check` | Find broken links, redirects, and missing anchor text |
+| `seo_keyword_density` | Measure keyword frequency and check target keyword placement |
+| `seo_page_speed` | Measure TTFB, load time, HTML size, and resource counts |
+| `seo_sitemap_parse` | Parse sitemap.xml, check freshness, duplicates, and compliance |
+
+## Requirements
+
+- Node.js 18+
+- No API keys needed — all tools use direct HTTP requests and HTML parsing
+
+## Installation
+
+```bash
+git clone <repo-url>
+cd mcp-seo-tools
+npm install
+npm run build
+```
+
+## Usage with Claude Code
+
+Add to your Claude Code MCP configuration:
+
+```bash
+claude mcp add seo-tools node D:/products/mcp-servers/mcp-seo-tools/dist/index.js
+```
+
+## Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "seo-tools": {
+      "command": "node",
+      "args": ["D:/products/mcp-servers/mcp-seo-tools/dist/index.js"]
+    }
+  }
+}
+```
+
+## Tool Details
+
+### seo_meta_analyze
+
+Fetches a URL and inspects all meta-related elements. Checks title length (optimal: 30-60 chars), meta description length (optimal: 120-160 chars), canonical URL, viewport tag, language attribute, Open Graph completeness, and Twitter Card setup. Returns a 0-100 score.
+
+```
+Input: { "url": "https://example.com" }
+```
+
+### seo_heading_check
+
+Parses all headings on a page and builds a visual hierarchy tree. Flags: missing H1, multiple H1s, skipped heading levels, empty headings, overly long headings (>70 chars), and duplicate headings.
+
+```
+Input: { "url": "https://example.com" }
+```
+
+### seo_link_check
+
+Extracts all anchor tags from a page, resolves relative URLs, deduplicates, and probes each link with a HEAD request (falling back to GET when needed). Classifies links as ok, broken, redirect, timeout, or error. Reports internal vs. external link ratio.
+
+```
+Input: { "url": "https://example.com", "max_links": 100 }
+```
+
+### seo_keyword_density
+
+Strips scripts, styles, and navigation, then tokenizes the remaining body text. Computes frequency and density for single words, bigrams, and trigrams (filtering stop words). When a target keyword is provided, checks whether it appears in the title, H1, meta description, and first paragraph.
+
+```
+Input: { "url": "https://example.com", "target_keyword": "seo tools" }
+```
+
+### seo_page_speed
+
+Measures Time to First Byte and total download time from the server's perspective. Counts external scripts, stylesheets, images, and iframes. Detects render-blocking scripts (missing async/defer), images without alt text or dimensions, missing compression, and absence of lazy loading.
+
+```
+Input: { "url": "https://example.com" }
+```
+
+### seo_sitemap_parse
+
+Accepts a sitemap URL or any page URL (automatically appends `/sitemap.xml`). Falls back to checking `robots.txt` for a Sitemap directive. Handles both `<sitemapindex>` and `<urlset>` formats. Validates URL count limits, lastmod freshness, duplicate entries, protocol consistency, and trailing slash patterns.
+
+```
+Input: { "url": "https://example.com" }
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const meta_analyzer_js_1 = require("./tools/meta-analyzer.js");
+const heading_checker_js_1 = require("./tools/heading-checker.js");
+const link_checker_js_1 = require("./tools/link-checker.js");
+const keyword_density_js_1 = require("./tools/keyword-density.js");
+const page_speed_js_1 = require("./tools/page-speed.js");
+const sitemap_parser_js_1 = require("./tools/sitemap-parser.js");
+const server = new index_js_1.Server({
+    name: "mcp-seo-tools",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "seo_meta_analyze",
+            description: "Analyze a page's meta tags, Open Graph tags, and Twitter Card tags. Returns an SEO score with actionable recommendations for title, description, social sharing tags, and other meta elements.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "Full URL of the page to analyze (e.g. https://example.com)",
+                    },
+                },
+                required: ["url"],
+            },
+        },
+        {
+            name: "seo_heading_check",
+            description: "Audit the heading hierarchy (H1-H6) of a page. Detects missing H1, skipped heading levels, duplicate headings, empty headings, and provides a visual hierarchy tree.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "Full URL of the page to audit",
+                    },
+                },
+                required: ["url"],
+            },
+        },
+        {
+            name: "seo_link_check",
+            description: "Crawl a page and check all links for broken URLs, redirects, and missing anchor text. Tests up to 50 links by default with concurrent requests.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "Full URL of the page to scan for links",
+                    },
+                    max_links: {
+                        type: "number",
+                        description: "Maximum number of links to check (default: 50, max: 200)",
+                    },
+                },
+                required: ["url"],
+            },
+        },
+        {
+            name: "seo_keyword_density",
+            description: "Analyze keyword density and distribution across a page. Returns top single words, two-word and three-word phrases with density percentages. Optionally checks placement of a target keyword in title, H1, meta description, and first paragraph.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "Full URL of the page to analyze",
+                    },
+                    target_keyword: {
+                        type: "string",
+                        description: "Optional target keyword to check placement and density for",
+                    },
+                },
+                required: ["url"],
+            },
+        },
+        {
+            name: "seo_page_speed",
+            description: "Measure basic page speed metrics including Time to First Byte, total load time, HTML size, and resource counts (scripts, stylesheets, images). Identifies render-blocking resources and missing optimizations.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "Full URL of the page to measure",
+                    },
+                },
+                required: ["url"],
+            },
+        },
+        {
+            name: "seo_sitemap_parse",
+            description: "Parse and analyze a website's sitemap.xml. Handles both sitemap indexes and URL sets. Reports URL counts, lastmod freshness, duplicate URLs, protocol consistency, and sitemap compliance issues. Automatically tries /sitemap.xml and falls back to robots.txt.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "URL of the sitemap or any page on the site (will try /sitemap.xml automatically)",
+                    },
+                },
+                required: ["url"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "seo_meta_analyze": {
+                const result = await (0, meta_analyzer_js_1.analyzeMeta)(args?.url);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "seo_heading_check": {
+                const result = await (0, heading_checker_js_1.checkHeadings)(args?.url);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "seo_link_check": {
+                const maxLinks = Math.min(args?.max_links || 50, 200);
+                const result = await (0, link_checker_js_1.checkLinks)(args?.url, maxLinks);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "seo_keyword_density": {
+                const result = await (0, keyword_density_js_1.analyzeKeywordDensity)(args?.url, args?.target_keyword);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "seo_page_speed": {
+                const result = await (0, page_speed_js_1.analyzePageSpeed)(args?.url);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "seo_sitemap_parse": {
+                const result = await (0, sitemap_parser_js_1.parseSitemap)(args?.url);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP SEO Tools server running on stdio");
+}
+main().catch(console.error);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/tools/heading-checker.d.ts

@@ -0,0 +1,15 @@
+export interface HeadingInfo {
+    level: number;
+    text: string;
+    id: string | null;
+}
+export interface HeadingAnalysis {
+    url: string;
+    headings: HeadingInfo[];
+    hierarchy: string;
+    counts: Record<string, number>;
+    issues: string[];
+    score: number;
+}
+export declare function checkHeadings(url: string): Promise<HeadingAnalysis>;
+//# sourceMappingURL=heading-checker.d.ts.map

package/dist/tools/heading-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-checker.d.ts","sourceRoot":"","sources":["../../src/tools/heading-checker.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA2FzE"}

package/dist/tools/heading-checker.js

@@ -0,0 +1,123 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkHeadings = checkHeadings;
+const cheerio = __importStar(require("cheerio"));
+async function checkHeadings(url) {
+    const response = await fetch(url, {
+        headers: { "User-Agent": "MCPSEOTools/1.0 (SEO Analyzer)" },
+        redirect: "follow",
+        signal: AbortSignal.timeout(15000),
+    });
+    const html = await response.text();
+    const $ = cheerio.load(html);
+    const headings = [];
+    const counts = { h1: 0, h2: 0, h3: 0, h4: 0, h5: 0, h6: 0 };
+    $("h1, h2, h3, h4, h5, h6").each((_, el) => {
+        const tag = $(el).prop("tagName")?.toLowerCase() || "";
+        const level = parseInt(tag.replace("h", ""), 10);
+        const text = $(el).text().trim().replace(/\s+/g, " ");
+        const id = $(el).attr("id") || null;
+        headings.push({ level, text, id });
+        if (counts[tag] !== undefined)
+            counts[tag]++;
+    });
+    const issues = [];
+    // Check for missing H1
+    if (counts.h1 === 0) {
+        issues.push("No H1 tag found. Every page should have exactly one H1 as the main heading.");
+    }
+    else if (counts.h1 > 1) {
+        issues.push(`Found ${counts.h1} H1 tags. Use only one H1 per page for optimal SEO.`);
+    }
+    // Check if first heading is H1
+    if (headings.length > 0 && headings[0].level !== 1) {
+        issues.push(`First heading is H${headings[0].level} instead of H1. The first heading should be H1.`);
+    }
+    // Check for skipped levels
+    let previousLevel = 0;
+    for (const heading of headings) {
+        if (heading.level > previousLevel + 1 && previousLevel > 0) {
+            issues.push(`Heading level skipped: H${previousLevel} to H${heading.level} ("${heading.text.substring(0, 50)}"). Avoid skipping heading levels.`);
+        }
+        previousLevel = heading.level;
+    }
+    // Check for empty headings
+    const emptyHeadings = headings.filter((h) => h.text.length === 0);
+    if (emptyHeadings.length > 0) {
+        issues.push(`Found ${emptyHeadings.length} empty heading(s). All headings should contain descriptive text.`);
+    }
+    // Check for very long headings
+    const longHeadings = headings.filter((h) => h.text.length > 70);
+    for (const h of longHeadings) {
+        issues.push(`H${h.level} exceeds 70 characters (${h.text.length} chars): "${h.text.substring(0, 60)}..."`);
+    }
+    // Check for duplicate headings
+    const seen = new Map();
+    for (const h of headings) {
+        const key = `h${h.level}:${h.text.toLowerCase()}`;
+        seen.set(key, (seen.get(key) || 0) + 1);
+    }
+    for (const [key, count] of seen) {
+        if (count > 1) {
+            const [tag, ...textParts] = key.split(":");
+            issues.push(`Duplicate ${tag.toUpperCase()}: "${textParts.join(":")}" appears ${count} times.`);
+        }
+    }
+    // Build visual hierarchy
+    const hierarchy = headings
+        .map((h) => `${"  ".repeat(h.level - 1)}H${h.level}: ${h.text.substring(0, 80)}`)
+        .join("\n");
+    // Score calculation
+    let score = 100;
+    if (counts.h1 === 0)
+        score -= 25;
+    else if (counts.h1 > 1)
+        score -= 15;
+    if (headings.length > 0 && headings[0].level !== 1)
+        score -= 10;
+    score -= Math.min(issues.filter((i) => i.includes("skipped")).length * 10, 20);
+    score -= emptyHeadings.length * 5;
+    score -= longHeadings.length * 3;
+    return {
+        url,
+        headings,
+        hierarchy,
+        counts,
+        issues,
+        score: Math.max(0, score),
+    };
+}
+//# sourceMappingURL=heading-checker.js.map

package/dist/tools/heading-checker.js.map

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

package/dist/tools/keyword-density.d.ts

@@ -0,0 +1,22 @@
+export interface KeywordInfo {
+    keyword: string;
+    count: number;
+    density: number;
+    inTitle: boolean;
+    inH1: boolean;
+    inHeadings: boolean;
+    inMetaDescription: boolean;
+    inFirstParagraph: boolean;
+}
+export interface KeywordDensityAnalysis {
+    url: string;
+    totalWords: number;
+    topSingleWords: KeywordInfo[];
+    topTwoWordPhrases: KeywordInfo[];
+    topThreeWordPhrases: KeywordInfo[];
+    targetKeywordAnalysis: KeywordInfo | null;
+    issues: string[];
+    recommendations: string[];
+}
+export declare function analyzeKeywordDensity(url: string, targetKeyword?: string): Promise<KeywordDensityAnalysis>;
+//# sourceMappingURL=keyword-density.d.ts.map

package/dist/tools/keyword-density.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-density.d.ts","sourceRoot":"","sources":["../../src/tools/keyword-density.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,WAAW,EAAE,CAAC;IAC9B,iBAAiB,EAAE,WAAW,EAAE,CAAC;IACjC,mBAAmB,EAAE,WAAW,EAAE,CAAC;IACnC,qBAAqB,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AA6DD,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAgGhH"}

package/dist/tools/keyword-density.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeKeywordDensity = analyzeKeywordDensity;
+const cheerio = __importStar(require("cheerio"));
+const STOP_WORDS = new Set([
+    "a", "an", "the", "and", "or", "but", "is", "are", "was", "were", "be", "been",
+    "being", "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "shall", "can", "need", "dare", "ought", "used",
+    "to", "of", "in", "for", "on", "with", "at", "by", "from", "as", "into",
+    "through", "during", "before", "after", "above", "below", "between", "out",
+    "off", "over", "under", "again", "further", "then", "once", "here", "there",
+    "when", "where", "why", "how", "all", "each", "every", "both", "few", "more",
+    "most", "other", "some", "such", "no", "nor", "not", "only", "own", "same",
+    "so", "than", "too", "very", "just", "because", "about", "up", "its", "it",
+    "this", "that", "these", "those", "i", "me", "my", "we", "our", "you", "your",
+    "he", "him", "his", "she", "her", "they", "them", "their", "what", "which",
+    "who", "whom", "if", "also", "get", "got", "like", "make", "go", "new",
+]);
+function extractVisibleText($) {
+    $("script, style, noscript, nav, footer, header").remove();
+    return $("body").text().replace(/\s+/g, " ").trim().toLowerCase();
+}
+function tokenize(text) {
+    return text.match(/[a-z]{2,}/g) || [];
+}
+function getNgrams(words, n) {
+    const counts = new Map();
+    for (let i = 0; i <= words.length - n; i++) {
+        const chunk = words.slice(i, i + n);
+        // Skip ngrams that start or end with stop words
+        if (STOP_WORDS.has(chunk[0]) || STOP_WORDS.has(chunk[chunk.length - 1]))
+            continue;
+        const phrase = chunk.join(" ");
+        counts.set(phrase, (counts.get(phrase) || 0) + 1);
+    }
+    return counts;
+}
+function buildKeywordInfo(keyword, count, totalWords, title, h1Text, headingsText, metaDesc, firstParagraph) {
+    const kw = keyword.toLowerCase();
+    return {
+        keyword,
+        count,
+        density: parseFloat(((count / totalWords) * 100).toFixed(2)),
+        inTitle: title.includes(kw),
+        inH1: h1Text.includes(kw),
+        inHeadings: headingsText.includes(kw),
+        inMetaDescription: metaDesc.includes(kw),
+        inFirstParagraph: firstParagraph.includes(kw),
+    };
+}
+async function analyzeKeywordDensity(url, targetKeyword) {
+    const response = await fetch(url, {
+        headers: { "User-Agent": "MCPSEOTools/1.0 (SEO Analyzer)" },
+        redirect: "follow",
+        signal: AbortSignal.timeout(15000),
+    });
+    const html = await response.text();
+    const $ = cheerio.load(html);
+    const title = $("title").first().text().trim().toLowerCase();
+    const metaDesc = ($('meta[name="description"]').attr("content") || "").toLowerCase();
+    const h1Text = $("h1").text().trim().toLowerCase();
+    const headingsText = $("h1, h2, h3, h4, h5, h6").text().trim().toLowerCase();
+    const firstParagraph = $("p").first().text().trim().toLowerCase();
+    const bodyText = extractVisibleText($);
+    const allWords = tokenize(bodyText);
+    const contentWords = allWords.filter((w) => !STOP_WORDS.has(w));
+    const totalWords = allWords.length;
+    // Single words
+    const singleCounts = new Map();
+    for (const w of contentWords) {
+        singleCounts.set(w, (singleCounts.get(w) || 0) + 1);
+    }
+    const topSingle = [...singleCounts.entries()]
+        .filter(([, c]) => c >= 2)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 15)
+        .map(([kw, count]) => buildKeywordInfo(kw, count, totalWords, title, h1Text, headingsText, metaDesc, firstParagraph));
+    // Two-word phrases
+    const twoCounts = getNgrams(allWords, 2);
+    const topTwo = [...twoCounts.entries()]
+        .filter(([, c]) => c >= 2)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([kw, count]) => buildKeywordInfo(kw, count, totalWords, title, h1Text, headingsText, metaDesc, firstParagraph));
+    // Three-word phrases
+    const threeCounts = getNgrams(allWords, 3);
+    const topThree = [...threeCounts.entries()]
+        .filter(([, c]) => c >= 2)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([kw, count]) => buildKeywordInfo(kw, count, totalWords, title, h1Text, headingsText, metaDesc, firstParagraph));
+    // Target keyword analysis
+    let targetKeywordAnalysis = null;
+    if (targetKeyword) {
+        const tk = targetKeyword.toLowerCase().trim();
+        const regex = new RegExp(`\\b${tk.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "gi");
+        const matches = bodyText.match(regex);
+        const count = matches ? matches.length : 0;
+        targetKeywordAnalysis = buildKeywordInfo(tk, count, totalWords, title, h1Text, headingsText, metaDesc, firstParagraph);
+    }
+    const issues = [];
+    const recommendations = [];
+    if (totalWords < 300) {
+        issues.push(`Page has only ${totalWords} words. Search engines prefer pages with at least 300 words.`);
+        recommendations.push("Add more substantial content to improve topical authority.");
+    }
+    if (targetKeywordAnalysis) {
+        const tk = targetKeywordAnalysis;
+        if (tk.count === 0) {
+            issues.push(`Target keyword "${tk.keyword}" not found in page content.`);
+        }
+        else {
+            if (tk.density < 0.5)
+                recommendations.push(`Target keyword density is low (${tk.density}%). Aim for 1-2%.`);
+            if (tk.density > 3)
+                issues.push(`Target keyword density is too high (${tk.density}%). This may be seen as keyword stuffing.`);
+            if (!tk.inTitle)
+                recommendations.push("Include the target keyword in the page title.");
+            if (!tk.inH1)
+                recommendations.push("Include the target keyword in the H1 heading.");
+            if (!tk.inMetaDescription)
+                recommendations.push("Include the target keyword in the meta description.");
+            if (!tk.inFirstParagraph)
+                recommendations.push("Mention the target keyword within the first paragraph.");
+        }
+    }
+    // Check for potential keyword stuffing in top words
+    const stuffed = topSingle.filter((k) => k.density > 4);
+    for (const k of stuffed) {
+        issues.push(`"${k.keyword}" appears ${k.count} times (${k.density}% density). This may trigger keyword stuffing penalties.`);
+    }
+    return {
+        url,
+        totalWords,
+        topSingleWords: topSingle,
+        topTwoWordPhrases: topTwo,
+        topThreeWordPhrases: topThree,
+        targetKeywordAnalysis,
+        issues,
+        recommendations,
+    };
+}
+//# sourceMappingURL=keyword-density.js.map