agent-seo-engine 0.1.0__py3-none-any.whl

agent_seo_engine/__init__.py

@@ -0,0 +1,13 @@
+"""Agent-first SEO analysis toolkit."""
+
+from .agent import build_agent_manifest, build_connection_status, build_privacy_audit
+from .intent import SearchIntentAnalyzer
+from .quality import score_markdown
+
+__all__ = [
+    "SearchIntentAnalyzer",
+    "build_agent_manifest",
+    "build_connection_status",
+    "build_privacy_audit",
+    "score_markdown",
+]

agent_seo_engine/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

agent_seo_engine/agent.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+SUPPORTED_CLIENTS = ["generic", "claude", "codex", "cursor", "windsurf", "hermes", "openclaw"]
+
+
+def _safe_client(client: str = "generic") -> str:
+    return client if client in SUPPORTED_CLIENTS else "generic"
+
+
+def _present(env: Mapping[str, str], key: str) -> bool:
+    return bool(str(env.get(key, "")).strip())
+
+
+def build_agent_manifest(client: str = "generic") -> dict:
+    return {
+        "project": "agent-seo-engine",
+        "mcp_name": "io.github.davidmosiah/agent-seo-engine",
+        "client": _safe_client(client),
+        "package": {
+            "pip": "pipx install agent-seo-engine[mcp]",
+            "cli": "agent-seo-engine",
+            "mcp": "agent-seo-mcp",
+        },
+        "supported_clients": SUPPORTED_CLIENTS,
+        "standard_tools": [
+            "agent_seo_manifest",
+            "agent_seo_connection_status",
+            "agent_seo_privacy_audit",
+            "agent_seo_detect_intent",
+            "agent_seo_score_content",
+            "agent_seo_prioritize_opportunity",
+        ],
+        "recommended_first_calls": ["agent_seo_connection_status", "agent_seo_privacy_audit"],
+        "default_mode": "local_offline",
+        "hermes": {
+            "config_path": "~/.hermes/config.yaml",
+            "tool_name_prefix": "mcp_agent_seo_",
+            "recommended_config": (
+                "mcp_servers:\n"
+                "  agent_seo:\n"
+                "    command: agent-seo-mcp\n"
+                "    args: []\n"
+                "    sampling:\n"
+                "      enabled: false"
+            ),
+        },
+        "agent_rules": [
+            "Start with connection status before content operations.",
+            "Use local content paths or explicit text from the user.",
+            "Do not send drafts to analytics providers unless the user asks.",
+            "Return exact checks and next actions, not generic SEO advice.",
+        ],
+    }
+
+
+def build_connection_status(env: Mapping[str, str] | None = None) -> dict:
+    env = env or {}
+    services = []
+    if _present(env, "GEMINI_API_KEY") or _present(env, "GOOGLE_API_KEY"):
+        services.append("gemini")
+    if _present(env, "GA4_PROPERTY_ID"):
+        services.append("ga4")
+    if _present(env, "GSC_SITE_URL"):
+        services.append("google_search_console")
+
+    return {
+        "ok": True,
+        "mode": "offline" if not services else "offline_plus_optional_integrations",
+        "external_services_configured": services,
+        "ready_for_content_scoring": True,
+        "ready_for_mcp": True,
+        "next_steps": [
+            "Run agent-seo-engine score --file <markdown> --primary-keyword <keyword>.",
+            "Use optional analytics environment only for reports that require it.",
+        ],
+    }
+
+
+def build_privacy_audit() -> dict:
+    return {
+        "project": "agent-seo-engine",
+        "secrets_returned_to_agent": False,
+        "local_files_ignored": [".env", "credentials/", "node_modules/", ".agent-data/", "coverage/"],
+        "external_services": ["optional: Gemini", "optional: GA4", "optional: Google Search Console"],
+        "data_boundary": "Content scoring, intent detection and opportunity scoring run locally by default.",
+        "safety_rules": [
+            "Keep drafts local unless an optional integration is explicitly requested.",
+            "Do not commit credentials, analytics exports or unpublished content plans.",
+            "Prefer structured JSON output for agents and markdown only for human review.",
+            "Treat generated recommendations as editorial suggestions, not automatic publishing approval.",
+        ],
+    }

agent_seo_engine/cli.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+from .agent import build_agent_manifest, build_connection_status, build_privacy_audit
+from .intent import SearchIntentAnalyzer
+from .opportunity import prioritize_opportunity
+from .quality import score_markdown
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="agent-seo-engine")
+    parser.add_argument("--format", choices=["json", "markdown"], default="json")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    manifest = sub.add_parser("manifest")
+    manifest.add_argument("--client", default="generic")
+
+    sub.add_parser("doctor")
+    sub.add_parser("privacy-audit")
+
+    intent = sub.add_parser("intent")
+    intent.add_argument("keyword")
+
+    score = sub.add_parser("score")
+    score.add_argument("--file", required=True)
+    score.add_argument("--primary-keyword", default="")
+    score.add_argument("--min-words", type=int, default=900)
+
+    opp = sub.add_parser("opportunity")
+    opp.add_argument("--impressions", type=int, default=0)
+    opp.add_argument("--clicks", type=int, default=0)
+    opp.add_argument("--position", type=float, default=100.0)
+    opp.add_argument("--conversions", type=float, default=0.0)
+    opp.add_argument("--commercial-intent", type=float, default=0.5)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "manifest":
+      payload = build_agent_manifest(args.client)
+    elif args.command == "doctor":
+      payload = build_connection_status(os.environ)
+    elif args.command == "privacy-audit":
+      payload = build_privacy_audit()
+    elif args.command == "intent":
+      payload = SearchIntentAnalyzer().analyze(args.keyword)
+    elif args.command == "score":
+      payload = score_markdown(Path(args.file).read_text(encoding="utf-8"), args.primary_keyword, args.min_words)
+    elif args.command == "opportunity":
+      payload = prioritize_opportunity(args.impressions, args.clicks, args.position, args.conversions, args.commercial_intent)
+    else:
+      parser.error("unknown command")
+
+    print(_format(payload, args.format))
+    return 0
+
+
+def _format(payload: dict, response_format: str) -> str:
+    if response_format == "markdown":
+        return "# Agent SEO Engine\n\n```json\n" + json.dumps(payload, indent=2, ensure_ascii=False) + "\n```"
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_seo_engine/intent.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Any
+
+
+class SearchIntent(Enum):
+    INFORMATIONAL = "informational"
+    NAVIGATIONAL = "navigational"
+    TRANSACTIONAL = "transactional"
+    COMMERCIAL = "commercial_investigation"
+
+
+class SearchIntentAnalyzer:
+    INFORMATIONAL_SIGNALS = [
+        "what", "why", "how", "when", "where", "who", "guide", "tutorial",
+        "learn", "tips", "best practices", "explained", "definition", "meaning",
+    ]
+    NAVIGATIONAL_SIGNALS = [
+        "login", "sign in", "website", "official", "home page", "account",
+        "dashboard", "portal", "app",
+    ]
+    TRANSACTIONAL_SIGNALS = [
+        "buy", "purchase", "order", "download", "get", "pricing", "cost",
+        "free trial", "sign up", "subscribe", "install", "coupon", "deal",
+        "discount", "cheap", "affordable", "hire",
+    ]
+    COMMERCIAL_SIGNALS = [
+        "best", "top", "review", "vs", "versus", "compare", "comparison",
+        "alternative", "alternatives", "like", "similar", "better than",
+        "instead of", "option", "choice",
+    ]
+
+    def analyze(
+        self,
+        keyword: str,
+        serp_features: list[str] | None = None,
+        top_results: list[dict[str, str]] | None = None,
+    ) -> dict[str, Any]:
+        keyword_lower = keyword.lower()
+        scores = {intent: 0.0 for intent in SearchIntent}
+
+        for intent, score in self._keyword_scores(keyword_lower).items():
+            scores[intent] += score
+        for intent, score in self._serp_scores(serp_features or []).items():
+            scores[intent] += score
+        for intent, score in self._result_scores(top_results or []).items():
+            scores[intent] += score
+
+        total = sum(scores.values())
+        confidence = {
+            intent.value: round((score / total * 100), 2) if total else 25.0
+            for intent, score in scores.items()
+        }
+        primary = max(scores.items(), key=lambda item: item[1])[0] if total else SearchIntent.INFORMATIONAL
+        ordered = sorted(scores.items(), key=lambda item: item[1], reverse=True)
+        secondary = None
+        if total and len(ordered) > 1:
+            if confidence[ordered[0][0].value] - confidence[ordered[1][0].value] < 15:
+                secondary = ordered[1][0]
+
+        return {
+            "keyword": keyword,
+            "primary_intent": primary.value,
+            "secondary_intent": secondary.value if secondary else None,
+            "confidence": confidence,
+            "signals_detected": self._detected_signals(keyword_lower, serp_features or []),
+            "recommendations": self._recommendations(primary),
+        }
+
+    def _keyword_scores(self, keyword: str) -> dict[SearchIntent, float]:
+        scores = {intent: 0.0 for intent in SearchIntent}
+        for signal in self.INFORMATIONAL_SIGNALS:
+            if signal in keyword:
+                scores[SearchIntent.INFORMATIONAL] += 2
+        for signal in self.NAVIGATIONAL_SIGNALS:
+            if signal in keyword:
+                scores[SearchIntent.NAVIGATIONAL] += 3
+        for signal in self.TRANSACTIONAL_SIGNALS:
+            if signal in keyword:
+                scores[SearchIntent.TRANSACTIONAL] += 2
+        for signal in self.COMMERCIAL_SIGNALS:
+            if signal in keyword:
+                scores[SearchIntent.COMMERCIAL] += 2
+        if re.match(r"^(what|why|how|when|where|who|can|should|is|are|does)\b", keyword):
+            scores[SearchIntent.INFORMATIONAL] += 3
+        if re.search(r"\d+\s+(best|top)", keyword):
+            scores[SearchIntent.COMMERCIAL] += 3
+        return scores
+
+    def _serp_scores(self, features: list[str]) -> dict[SearchIntent, float]:
+        scores = {intent: 0.0 for intent in SearchIntent}
+        for feature in features:
+            value = feature.lower()
+            if "snippet" in value or "people" in value or "knowledge" in value:
+                scores[SearchIntent.INFORMATIONAL] += 2
+            if "shopping" in value or "product" in value or "ad" in value:
+                scores[SearchIntent.TRANSACTIONAL] += 2
+            if "carousel" in value:
+                scores[SearchIntent.COMMERCIAL] += 1
+        return scores
+
+    def _result_scores(self, results: list[dict[str, str]]) -> dict[SearchIntent, float]:
+        scores = {intent: 0.0 for intent in SearchIntent}
+        for result in results[:10]:
+            combined = f"{result.get('title', '')} {result.get('description', '')}".lower()
+            url = result.get("url", "").lower()
+            if any(term in combined for term in ["guide", "how to", "what is", "tutorial"]):
+                scores[SearchIntent.INFORMATIONAL] += 0.5
+            if any(term in combined for term in ["best", "top", "review", "vs", "compare"]):
+                scores[SearchIntent.COMMERCIAL] += 0.5
+            if any(term in combined for term in ["buy", "price", "shop", "order", "get"]):
+                scores[SearchIntent.TRANSACTIONAL] += 0.5
+            if any(term in url for term in ["/product/", "/pricing", "/buy", "/shop", "/checkout"]):
+                scores[SearchIntent.TRANSACTIONAL] += 0.5
+        return scores
+
+    def _detected_signals(self, keyword: str, serp_features: list[str]) -> dict[str, list[str]]:
+        return {
+            "keyword": [signal for signal in (
+                self.INFORMATIONAL_SIGNALS + self.NAVIGATIONAL_SIGNALS + self.TRANSACTIONAL_SIGNALS + self.COMMERCIAL_SIGNALS
+            ) if signal in keyword],
+            "serp_features": serp_features,
+        }
+
+    def _recommendations(self, intent: SearchIntent) -> list[str]:
+        if intent == SearchIntent.INFORMATIONAL:
+            return ["Lead with a direct answer, then expand into steps, examples and FAQs."]
+        if intent == SearchIntent.COMMERCIAL:
+            return ["Use comparison tables, alternatives, decision criteria and clear evaluation language."]
+        if intent == SearchIntent.TRANSACTIONAL:
+            return ["Make pricing, trust signals, proof and conversion path obvious above the fold."]
+        return ["Make brand/entity navigation unambiguous and link to the canonical destination early."]

agent_seo_engine/mcp_server.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .agent import build_agent_manifest, build_connection_status, build_privacy_audit
+from .intent import SearchIntentAnalyzer
+from .opportunity import prioritize_opportunity
+from .quality import score_markdown
+
+
+def create_mcp():
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:
+        raise RuntimeError("Install MCP support with: pip install 'agent-seo-engine[mcp]'") from exc
+
+    mcp = FastMCP("agent-seo-engine")
+
+    @mcp.tool()
+    def agent_seo_manifest(client: str = "generic") -> dict:
+        return build_agent_manifest(client)
+
+    @mcp.tool()
+    def agent_seo_connection_status() -> dict:
+        return build_connection_status(os.environ)
+
+    @mcp.tool()
+    def agent_seo_privacy_audit() -> dict:
+        return build_privacy_audit()
+
+    @mcp.tool()
+    def agent_seo_detect_intent(keyword: str) -> dict:
+        return SearchIntentAnalyzer().analyze(keyword)
+
+    @mcp.tool()
+    def agent_seo_score_content(markdown: str = "", file_path: str = "", primary_keyword: str = "") -> dict:
+        text = markdown or Path(file_path).read_text(encoding="utf-8")
+        return score_markdown(text, primary_keyword=primary_keyword)
+
+    @mcp.tool()
+    def agent_seo_prioritize_opportunity(
+        impressions: int = 0,
+        clicks: int = 0,
+        position: float = 100.0,
+        conversions: float = 0.0,
+        commercial_intent: float = 0.5,
+    ) -> dict:
+        return prioritize_opportunity(impressions, clicks, position, conversions, commercial_intent)
+
+    return mcp
+
+
+def main() -> None:
+    create_mcp().run()
+
+
+if __name__ == "__main__":
+    main()

agent_seo_engine/opportunity.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+
+def prioritize_opportunity(
+    impressions: int = 0,
+    clicks: int = 0,
+    position: float = 100.0,
+    conversions: float = 0.0,
+    commercial_intent: float = 0.5,
+) -> dict:
+    volume_score = min(100.0, max(0.0, impressions / 50))
+    position_score = _position_score(position)
+    ctr = clicks / impressions if impressions else 0.0
+    expected_ctr = _expected_ctr(position)
+    ctr_gap_score = min(100.0, max(0.0, (expected_ctr - ctr) / max(expected_ctr, 0.01) * 100))
+    conversion_score = min(100.0, conversions * 25)
+    intent_score = min(100.0, max(0.0, commercial_intent * 100))
+
+    final = round(
+        volume_score * 0.25
+        + position_score * 0.25
+        + ctr_gap_score * 0.20
+        + intent_score * 0.20
+        + conversion_score * 0.10,
+        2,
+    )
+    return {
+        "final_score": final,
+        "priority": "high" if final >= 75 else "medium" if final >= 50 else "low",
+        "score_breakdown": {
+            "volume": round(volume_score, 1),
+            "position": round(position_score, 1),
+            "ctr_gap": round(ctr_gap_score, 1),
+            "commercial_intent": round(intent_score, 1),
+            "conversions": round(conversion_score, 1),
+        },
+        "recommended_action": _action(position, ctr_gap_score),
+    }
+
+
+def _position_score(position: float) -> float:
+    if position <= 3:
+        return 70
+    if position <= 10:
+        return 85
+    if position <= 20:
+        return 100
+    if position <= 50:
+        return 60
+    return 25
+
+
+def _expected_ctr(position: float) -> float:
+    if position <= 1:
+        return 0.31
+    if position <= 3:
+        return 0.12
+    if position <= 10:
+        return 0.04
+    if position <= 20:
+        return 0.012
+    return 0.004
+
+
+def _action(position: float, ctr_gap_score: float) -> str:
+    if 8 < position <= 20:
+        return "Refresh content and internal links to push the URL onto page one."
+    if position <= 10 and ctr_gap_score > 40:
+        return "Rewrite title and meta description to improve CTR."
+    if position > 20:
+        return "Build a stronger article or hub page before expecting ranking movement."
+    return "Monitor and improve topical depth selectively."

agent_seo_engine/quality.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+def split_frontmatter(markdown: str) -> tuple[dict[str, Any], str]:
+    if not markdown.startswith("---\n"):
+        return {}, markdown
+    parts = markdown.split("---\n", 2)
+    if len(parts) < 3:
+        return {}, markdown
+    return _parse_simple_yaml(parts[1]), parts[2]
+
+
+def score_markdown(markdown: str, primary_keyword: str = "", min_words: int = 900) -> dict[str, Any]:
+    frontmatter, body = split_frontmatter(markdown)
+    plain = _plain_text(body)
+    words = re.findall(r"\b[\w'-]+\b", plain)
+    word_count = len(words)
+    h1 = re.findall(r"^#\s+(.+)$", body, flags=re.MULTILINE)
+    h2 = re.findall(r"^##\s+(.+)$", body, flags=re.MULTILINE)
+    links = re.findall(r"(?<!!)\[[^\]]+\]\(([^)\s]+)", body)
+    internal_links = [link for link in links if link.startswith("/")]
+    external_links = [link for link in links if link.startswith(("http://", "https://"))]
+
+    title = str(frontmatter.get("title") or (h1[0] if h1 else "")).strip()
+    description = str(frontmatter.get("description") or "").strip()
+    keyword = primary_keyword.strip().lower()
+    lower_body = plain.lower()
+    keyword_count = lower_body.count(keyword) if keyword else 0
+    density = round((keyword_count / word_count * 100), 2) if keyword and word_count else 0.0
+
+    checks = {
+        "title": _check(bool(title), 10, "Add a title or H1."),
+        "title_length": _check(20 <= len(title) <= 70, 10, "Keep title between 20 and 70 characters."),
+        "meta_description": _check(120 <= len(description) <= 165, 15, "Rewrite description to 120-165 characters."),
+        "word_count": _check(word_count >= min_words, 15, f"Expand article to at least {min_words} words."),
+        "h1": _check(len(h1) == 1, 10, "Use exactly one H1."),
+        "h2_sections": _check(len(h2) >= 3, 10, "Add at least three H2 sections."),
+        "keyword_in_title": _check(not keyword or keyword in title.lower(), 10, "Place the primary keyword in the title."),
+        "keyword_in_first_100": _check(not keyword or keyword in " ".join(words[:100]).lower(), 10, "Use primary keyword in first 100 words."),
+        "keyword_density": _check(not keyword or 0.4 <= density <= 2.5, 10, "Adjust primary keyword density to roughly 0.4%-2.5%."),
+        "internal_links": _check(len(internal_links) >= 2, 5, "Add at least two internal links."),
+        "external_links": _check(len(external_links) >= 1, 5, "Add at least one authoritative external link."),
+    }
+
+    max_score = sum(item["weight"] for item in checks.values())
+    earned = sum(item["weight"] for item in checks.values() if item["passed"])
+    score = round((earned / max_score) * 100, 1) if max_score else 0.0
+    recommendations = [item["recommendation"] for item in checks.values() if not item["passed"]]
+
+    return {
+        "overall_score": score,
+        "grade": _grade(score),
+        "publishing_ready": score >= 85 and not any(
+            not checks[key]["passed"] for key in ["title", "meta_description", "h1", "keyword_in_title"]
+        ),
+        "checks": checks,
+        "metrics": {
+            "word_count": word_count,
+            "h1_count": len(h1),
+            "h2_count": len(h2),
+            "internal_link_count": len(internal_links),
+            "external_link_count": len(external_links),
+            "primary_keyword_occurrences": keyword_count,
+            "primary_keyword_density": density,
+        },
+        "recommendations": recommendations,
+    }
+
+
+def _check(passed: bool, weight: int, recommendation: str) -> dict[str, Any]:
+    return {"passed": passed, "weight": weight, "recommendation": recommendation}
+
+
+def _grade(score: float) -> str:
+    if score >= 90:
+        return "A"
+    if score >= 80:
+        return "B"
+    if score >= 70:
+        return "C"
+    if score >= 60:
+        return "D"
+    return "F"
+
+
+def _plain_text(markdown: str) -> str:
+    text = re.sub(r"```.*?```", "", markdown, flags=re.DOTALL)
+    text = re.sub(r"^#+\s+", "", text, flags=re.MULTILINE)
+    text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+    text = re.sub(r"[*_`>#-]", " ", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def _parse_simple_yaml(block: str) -> dict[str, Any]:
+    data: dict[str, Any] = {}
+    current_key: str | None = None
+    for raw in block.splitlines():
+        line = raw.rstrip()
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        if line.startswith("  - ") and current_key:
+            data.setdefault(current_key, []).append(line[4:].strip().strip("\"'"))
+            continue
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        key = key.strip()
+        value = value.strip().strip("\"'")
+        if value:
+            data[key] = value
+            current_key = None
+        else:
+            data[key] = []
+            current_key = key
+    return data

agent_seo_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: agent-seo-engine
+Version: 0.1.0
+Summary: Agent-first SEO quality, intent and opportunity engine with CLI and optional MCP server.
+Project-URL: Homepage, https://github.com/davidmosiah/agent-seo-engine
+Project-URL: Repository, https://github.com/davidmosiah/agent-seo-engine
+Project-URL: Issues, https://github.com/davidmosiah/agent-seo-engine/issues
+Author: David Mosiah
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-tools,agentic-workflows,ai-agents,cli,content-ops,local-first,mcp,mcp-server,search-intent,seo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.13.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Agent SEO Engine
+
+[![GitHub stars](https://img.shields.io/github/stars/davidmosiah/agent-seo-engine?style=flat-square&logo=github)](https://github.com/davidmosiah/agent-seo-engine/stargazers)
+[![CI](https://github.com/davidmosiah/agent-seo-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/davidmosiah/agent-seo-engine/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Agent-first](https://img.shields.io/badge/agent--first-MCP-0ea5a3?style=flat-square)](https://github.com/davidmosiah/agent-seo-engine)
+
+> If this agent-first tool helps your workflow, please star the repo. Stars make this agent-first tooling easier for other builders to discover and help Delx keep shipping open infrastructure.
+
+Agent-first SEO scoring, search-intent detection and opportunity prioritization. It packages the useful parts of a production content pipeline into a clean local CLI plus an optional MCP server for Codex, Claude, Cursor, Hermes, OpenClaw and other agent runtimes.
+
+Use it when an agent needs deterministic SEO checks before rewriting, refreshing or publishing content.
+
+## What It Does
+
+- Classifies search intent: informational, navigational, transactional and commercial investigation
+- Scores markdown articles for agent-readable SEO gaps
+- Prioritizes GSC-style opportunities by impressions, position, CTR gap, conversions and commercial value
+- Exposes `manifest`, `connection_status` and `privacy_audit` surfaces before content tools
+- Runs locally by default with no required API keys
+
+## Install
+
+```bash
+pipx install "git+https://github.com/davidmosiah/agent-seo-engine.git"
+```
+
+With MCP support:
+
+```bash
+pipx install "git+https://github.com/davidmosiah/agent-seo-engine.git#egg=agent-seo-engine[mcp]"
+```
+
+PyPI release automation is configured with Trusted Publishing. See [docs/pypi-publishing.md](docs/pypi-publishing.md) for the one-time PyPI pending-publisher setup.
+
+## CLI
+
+```bash
+agent-seo-engine manifest --client codex
+agent-seo-engine doctor
+agent-seo-engine privacy-audit
+agent-seo-engine intent "best ai agent framework"
+agent-seo-engine score --file examples/article.md --primary-keyword "ai agent testing"
+agent-seo-engine opportunity --impressions 4200 --clicks 80 --position 12.4 --commercial-intent 0.8
+```
+
+All commands return structured JSON by default. Use `--format markdown` for human review.
+
+## MCP
+
+```bash
+agent-seo-mcp
+```
+
+Hermes-style config:
+
+```yaml
+mcp_servers:
+  agent_seo:
+    command: agent-seo-mcp
+    args: []
+    sampling:
+      enabled: false
+```
+
+Recommended first calls:
+
+1. `agent_seo_connection_status`
+2. `agent_seo_privacy_audit`
+3. `agent_seo_score_content`
+
+## Agent Surfaces
+
+| Tool | Purpose |
+|---|---|
+| `agent_seo_manifest` | Install/runtime guidance for agent clients |
+| `agent_seo_connection_status` | Local/offline readiness and optional integration status |
+| `agent_seo_privacy_audit` | Draft, analytics and credential boundaries |
+| `agent_seo_detect_intent` | Search intent classification |
+| `agent_seo_score_content` | Markdown quality checks with exact recommendations |
+| `agent_seo_prioritize_opportunity` | GSC-style opportunity scoring |
+
+## Copy-Paste Agent Prompt
+
+```text
+Use agent-seo-engine. First call agent_seo_connection_status and agent_seo_privacy_audit.
+Score the draft, then propose only edits tied to failed checks or high-impact opportunities.
+```
+
+## Agent Contract
+
+Agents should not guess whether a draft is ready. They should call the scoring tool, read exact failed checks, then propose focused edits. The engine is intentionally deterministic and local so repeated agent runs can compare output over time.
+
+## Development
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python -m compileall -q src
+```

agent_seo_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+agent_seo_engine/__init__.py,sha256=Qalo0dVBQngGmlNAzPE-MKfkGxWouB-Tf63zca-R9-U,355
+agent_seo_engine/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+agent_seo_engine/agent.py,sha256=ZEmWF7bxB16k9psu50AiRLMqE7zfDLErRQZBXHYiRzM,3687
+agent_seo_engine/cli.py,sha256=xjfjojuOR7vLnclGNU0dR9lHVgpPiI0ZWbSTJUtUfz4,2488
+agent_seo_engine/intent.py,sha256=ThRRk4rpqc8XSBlxPSh47nRI8ecNpZAuZQjOEyBa44s,6152
+agent_seo_engine/mcp_server.py,sha256=RiL-NvqIS90EYM2hkWoFRwgLMsrRfSki3SxLJtfUlZM,1695
+agent_seo_engine/opportunity.py,sha256=v-RkkLnJRb5XAUiTBsk-mv3d0VOKxKoEuABEuL9pEOU,2236
+agent_seo_engine/quality.py,sha256=ktXY-L6VXBrg6WRxwQv8oZhdeXHiiavxj7mjDllJxYI,4918
+agent_seo_engine-0.1.0.dist-info/METADATA,sha256=6WiuiySsYsAQcwa5tbRVvkL5u2kcVbG1Hhq-v_XEwxY,4919
+agent_seo_engine-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agent_seo_engine-0.1.0.dist-info/entry_points.txt,sha256=5MgmiYxwWd-M_5KO3yq6x7cszhAW632GgXDLzTZsxw0,112
+agent_seo_engine-0.1.0.dist-info/licenses/LICENSE,sha256=t5uYxHxwOj3qpKJUR7CAiyIhwHwm5SAeDNWuBtbs8yY,1069
+agent_seo_engine-0.1.0.dist-info/RECORD,,

agent_seo_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_seo_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agent-seo-engine = agent_seo_engine.cli:main
+agent-seo-mcp = agent_seo_engine.mcp_server:main

agent_seo_engine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Mosiah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.