agent-seo-engine 0.1.0__tar.gz

agent_seo_engine-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: python -m compileall -q src
+      - run: pytest

agent_seo_engine-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish package
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_seo_engine-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.env
+credentials/
+.agent-data/
+dist/
+build/
+*.egg-info/
+.DS_Store

agent_seo_engine-0.1.0/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.

agent_seo_engine-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,102 @@
+# 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/SECURITY.md

@@ -0,0 +1,3 @@
+# Security Policy
+
+Do not include unpublished drafts, analytics exports, credentials or customer data in issues. The engine runs locally by default; optional integrations should be treated as explicit user-approved data sharing.

agent_seo_engine-0.1.0/docs/pypi-publishing.md

@@ -0,0 +1,22 @@
+# PyPI publishing
+
+This package is configured for PyPI Trusted Publishing through GitHub Actions.
+No long-lived PyPI token is required in GitHub secrets or local config.
+
+## One-time PyPI setup
+
+Create a pending GitHub publisher in PyPI account settings:
+
+- PyPI project name: `agent-seo-engine`
+- Owner: `davidmosiah`
+- Repository name: `agent-seo-engine`
+- Workflow name: `pypi.yml`
+- Environment name: `pypi`
+
+PyPI docs:
+
+- Pending publishers: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
+- Publishing workflow: https://docs.pypi.org/trusted-publishers/using-a-publisher/
+
+After the pending publisher exists, run the `Publish to PyPI` GitHub Actions
+workflow manually or publish a GitHub release.

agent_seo_engine-0.1.0/examples/article.md

@@ -0,0 +1,22 @@
+---
+title: AI Agent Testing
+description: A practical checklist for testing AI agents before release.
+keywords:
+  - ai agent testing
+---
+
+# AI Agent Testing
+
+AI agent testing catches tool failures, missing context and unsafe writes before users depend on the workflow.
+
+## Readiness
+
+Start with deterministic checks for configuration, permissions and expected tool availability.
+
+## Behavior
+
+Run the same prompt against known fixtures and compare structured output.
+
+## Release
+
+Keep a short manual review step for destructive actions and account-level changes.

agent_seo_engine-0.1.0/examples/claude-desktop.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agent_seo": {
+      "command": "agent-seo-mcp",
+      "args": []
+    }
+  }
+}

agent_seo_engine-0.1.0/examples/hermes.yaml

@@ -0,0 +1,6 @@
+mcp_servers:
+  agent_seo:
+    command: agent-seo-mcp
+    args: []
+    sampling:
+      enabled: false

agent_seo_engine-0.1.0/llms.txt

@@ -0,0 +1,19 @@
+# Agent SEO Engine
+
+Agent-first SEO scoring, search-intent detection and opportunity prioritization with CLI and optional MCP server.
+
+Repository: https://github.com/davidmosiah/agent-seo-engine
+Install: pipx install "git+https://github.com/davidmosiah/agent-seo-engine.git"
+MCP command: agent-seo-mcp
+
+Core tools:
+- agent_seo_manifest
+- agent_seo_connection_status
+- agent_seo_privacy_audit
+- agent_seo_detect_intent
+- agent_seo_score_content
+- agent_seo_prioritize_opportunity
+
+Safety:
+- Runs locally by default.
+- Drafts and analytics exports should stay local unless explicitly shared.

agent_seo_engine-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-seo-engine"
+version = "0.1.0"
+description = "Agent-first SEO quality, intent and opportunity engine with CLI and optional MCP server."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "David Mosiah" }]
+keywords = ["ai-agents", "agent-tools", "agentic-workflows", "seo", "mcp", "mcp-server", "content-ops", "search-intent", "local-first", "cli"]
+dependencies = []
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+  "Topic :: Text Processing :: Markup :: Markdown",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.13.0"]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+agent-seo-engine = "agent_seo_engine.cli:main"
+agent-seo-mcp = "agent_seo_engine.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/davidmosiah/agent-seo-engine"
+Repository = "https://github.com/davidmosiah/agent-seo-engine"
+Issues = "https://github.com/davidmosiah/agent-seo-engine/issues"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

agent_seo_engine-0.1.0/server.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.davidmosiah/agent-seo-engine",
+  "description": "Agent-first local SEO quality, intent and opportunity engine with CLI and optional MCP server.",
+  "status": "active",
+  "repository": {
+    "url": "https://github.com/davidmosiah/agent-seo-engine",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "agent-seo-engine",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": []
+    }
+  ],
+  "remotes": [],
+  "websiteUrl": "https://github.com/davidmosiah/agent-seo-engine"
+}

agent_seo_engine-0.1.0/src/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-0.1.0/src/agent_seo_engine/__main__.py

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

agent_seo_engine-0.1.0/src/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.",
+        ],
+    }