geo-content-optimizer

中文 | English

Feed enterprise documents → auto-produce high-quality original articles optimized for AI model vector databases (Doubao, Kimi, DeepSeek, Qwen, GPT), with AI-generation traces removed.

GEO (Generative Engine Optimization) content optimization agent — cross-platform, zero platform dependency. Unlike traditional SEO targeting search engine crawlers, GEO targets AI summarizers and answer engines: making AI models "readable, willing to cite, and traceable."

Features

Core Capabilities

6 Usage Modes

CLI Interactive Mode  →  Terminal chat, great for quick trials
Command-line Direct   →  --file/--text params, great for batch scripts
Streamlit Web UI      →  Browser-based, great for non-technical users
HTTP API              →  FastAPI service, great for system integration
MCP Server            →  Connect to Claude and other AI tools, conversational invocation
DSH Plugin            →  Native DeepSeek Harness tools (mcp__geo__*), see docs/dsh-integration.md

Architecture

Input Document → [Stage 0 Web Search (optional)] → [Stage 1 Clean & Slice] → [Stage 2 Keyword Extraction] → [Stage 3 Content Generation] → [Stage 4 AI Trace Removal] → [Stage 5 Quality Gate] → Final Article + Word Document

Quick Start

1. Install

# Clone the repo
git clone https://github.com/wangzhuo-coding/geo-content-optimizer.git
cd geo-content-optimizer

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate    # Windows

# Install core dependencies
pip install -e .

Optional features (install as needed):

pip install -e ".[mcp]"       # MCP Server (connect to Claude etc.)
pip install -e ".[webui]"     # Streamlit Web UI
pip install -e ".[postgres]"  # PostgreSQL persistence
pip install -e ".[s3]"        # S3 file storage
pip install -e ".[all]"       # All optional features

Windows users: Run setup.bat for one-click install. In China, use a mirror: pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

2. Configure API Key

cp .env.example .env  # Windows: copy .env.example .env

Edit .env and fill in your LLM API Key:

OPENAI_API_KEY=sk-xxx               # Your API Key (required)
OPENAI_BASE_URL=https://api.openai.com/v1   # API endpoint
OPENAI_MODEL_NAME=gpt-4o            # Model name

Compatible API providers:

3. Run

Mode 1: CLI Interactive Mode

python -m src          # Simplest
python src/cli.py      # Equivalent
run.bat                # Windows one-click

Mode 2: Command-line Direct Processing

# Input text, auto-save to output/ directory
python src/cli.py --text "Your document content..."

# Process file + brand info
python src/cli.py --file document.pdf --brand "Brand Name, Website URL"

# Enable web search + export Word document
python src/cli.py --file doc.pdf --search --docx

# Full features: file + brand + web search + Word export
python src/cli.py --file doc.pdf --brand "Huawei, https://www.huawei.com" --search --docx

Mode 3: Web UI

pip install -e ".[webui]"
streamlit run src/web_ui.py

Upload files, paste text, toggle web search and Word export, watch real-time progress in the browser.

Mode 4: HTTP API Service

python -m uvicorn src.main:app --host 127.0.0.1 --port 5000

Swagger docs: Visit http://127.0.0.1:5000/docs after launch.

Example call:

curl -X POST http://127.0.0.1:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Optimize this document..."}]}'

Mode 5: MCP Server (Connect to Claude and other AI tools)

pip install -e ".[mcp]"

# stdio mode (Claude Desktop / Claude Code / WorkBuddy)
python src/mcp_server.py

# SSE HTTP mode (Web clients)
python src/mcp_server.py --transport sse --port 5001

Configure Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

Important: Do NOT use the env field in MCP config to pass API Keys! Claude Code's env overrides the entire environment (including the essential Windows PATH), causing Python to fail loading system DLLs with error code -32000. Configure API Keys in the project .env file instead — MCP Server reads it automatically on startup.

{
  "mcpServers": {
    "geo-content-optimizer": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "cwd": "/path/to/geo-content-optimizer"
    }
  }
}

Configure WorkBuddy (~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "geo-content-optimizer": {
      "command": "/path/to/geo-content-optimizer/.venv/Scripts/python.exe",
      "args": ["src/mcp_server.py"],
      "cwd": "/path/to/geo-content-optimizer"
    }
  }
}

MCP Tools:

After configuration, invoke by chatting directly in Claude/WorkBuddy:

User: Optimize this Huawei Cloud whitepaper for me
Claude: → Calls parse_document to parse the file
        → Calls run_geo_pipeline to execute 4-stage pipeline
        → Returns the final article

Mode 6: DSH Plugin (native DeepSeek Harness tools)

This project is also a dsh-plugin: the repo ships a dsh-plugin/ package; once installed into a DeepSeek Harness web profile via dsh plugin add, the harness spawns the project's FastMCP server and registers its 4 tools as native model tools mcp__geo__parse_document / run_geo_pipeline / web_search / search_and_enrich (auto-reconnect on crash; long-task timeout preset to 10 minutes).

# Prereqs: install deps and point the working instance at YOUR clone (see dsh-plugin/README.md)
#   python -m venv .venv && .venv\Scripts\python -m pip install -e ".[mcp]"
#   scripts\dsh-plugin-setup.ps1   (Linux/macOS: bash scripts/dsh-plugin-setup.sh)

# Install the plugin (mutually exclusive with a direct mcp-geo row in profiles/web/cordis.patch.yml;
# replace <your-clone> with the actual path)
dsh plugin --profile web add <your-clone>/dsh-plugin
dsh web restart   # after restart, mcp__geo__* tools appear in new sessions

The companion "GEO 创作" agent preset is vendored under dsh-plugin/preset/; install notes, portability, and acceptance checks live in docs/dsh-integration.md and docs/dsh-validation.md. The working instance is chosen by the GEO_PROJECT_ROOT / GEO_PYTHON environment variables (pointed at your clone; startup fails loudly when they are missing instead of silently registering zero tools); API keys are read from the instance's .env (mcp_server.py calls load_dotenv itself).

User Requirements & Dual Gate (Optional)

run_geo_pipeline accepts a user_requirements parameter (content direction / target audience / word count / style / keywords / platform, etc.). When supplied:

• Writing (Stage 3/4) reconciles user requirements via the three-tier priority: Tier 0 compliance/fact/black-hat red lines -> refuse and give a compliant alternative; Tier 1 GEO floor (EE-A-T/ACES/semantic entity density) -> seek win-win, preserve GEO when forced to choose; Tier 2 other requirements -> maximize satisfaction within constraints
• Scoring (Stage 5) adds an independent second axis "user-requirement satisfaction" (0-100%); together with the 100-point GEO baseline it forms a dual gate: GEO passes AND satisfaction >= 80% to be publishable; compliance-conflicting requirements are refused + given alternatives and excluded from the satisfaction rate (advisory by default; with run_geo_pipeline(strict=True) a sub-threshold article is explicitly flagged)

Omitting user_requirements leaves behavior unchanged (second axis inactive), consistent with the geo-writer / geo-scorer skills in the ecosystem.

Length Auto-calibration (R3)

LLMs have no stable sense of character counts — the same "≥1800字" request can produce 1200~4700 chars. The pipeline therefore does not trust the model's self-reported length and calibrates program-side instead:

1. Parse a length target from user_requirements: ≥1800字 (minimum) / 不超过2500字 (maximum) / 约1500字 (around) / 1800-2500字 (range);
2. After Stage 4 (de-AI rewriting), measure the output with len(text);
3. When it falls outside the tolerance band (default ±10%, PIPELINE_LENGTH_TOLERANCE), run a targeted expand/shrink pass, up to PIPELINE_MAX_LENGTH_ATTEMPTS (default 2) rounds, stopping as soon as it converges;
4. If it still misses after the cap, log honestly and accept the residual deviation — no infinite loop.

With no length requirement present, this step is skipped entirely (behavior identical to the previous version).

Runtime Tuning

A single run = 5 sequential LLM stages + optional LLM judge + optional web search. To make runs faster:

• PIPELINE_QUALITY_JUDGE=false: skip the LLM judge (deterministic lint only, saves one LLM round-trip);
• PIPELINE_SEARCH_MAX_QUERIES=1: extract only 1 search keyword for web enrichment (default 3);
• PIPELINE_MAX_LENGTH_ATTEMPTS=1: cap length calibration at 1 correction pass (default 2).

Structured-Output Degradation

If the log shows with_structured_output failed ... response_format type is unavailable now, your model/endpoint does not support native JSON-Schema structured output. The pipeline automatically degrades to "free-form text + Pydantic repair parsing" (functional, but Stage 1/2 schema enforcement is weaker). Prefer a model or OpenAI-compatible endpoint that supports response_format=json_schema.

Long-running Deployment & Self-Healing (R7 B6)

By default the MCP server is spawned per-session by the client (Claude Code, stdio) — no daemon needed. For long-running deployment (servers/dev boxes), use a process supervisor for auto-restart on crash:

• PM2 (cross-platform): npm i -g pm2 && pm2 start scripts/mcp_pm2.config.js (config: autorestart + exponential backoff + memory-limit restart; pm2 save && pm2 startup for boot persistence). Windows uses .venv/Scripts/python.exe, Linux/macOS change to .venv/bin/python (see comments in the config file).
• systemd (Linux): sudo cp scripts/mcp_mcp_server.service /etc/systemd/system/ && sudo systemctl enable --now geo-mcp-server (Restart=always, restarts 3s after crash).

Note: after a -32000 Connection closed, auto-reconnect is a client-side behavior (Claude Code retries); server-side responsiveness during long tasks is handled in code via async + asyncio.to_thread (event loop never blocks).

Environment Variables

Development Quality Gates

Install dev tooling with pip install -e ".[dev]", then:

These three steps run automatically on every push / PR via GitHub Actions (.github/workflows/ci.yml).

Project Structure

geo-content-optimizer/
├── config/
│   └── agent_llm_config.json      # Agent System Prompt + model config
├── scripts/                        # Run scripts (Linux/macOS)
├── src/
│   ├── __main__.py                 # python -m src entry
│   ├── main.py                     # FastAPI HTTP service
│   ├── cli.py                      # CLI interactive mode
│   ├── mcp_server.py               # MCP Server (connect to Claude etc.)
│   ├── web_ui.py                   # Streamlit Web UI
│   ├── agents/
│   │   └── agent.py                # Agent build (LangGraph) + AgentState
│   ├── tools/
│   │   ├── geo_pipeline.py         # Core: 4-stage pipeline + smart chunking + Word export
│   │   └── web_search.py           # Web search (Tavily/Bing/DuckDuckGo)
│   ├── utils/
│   │   ├── file/
│   │   │   └── file.py             # File parsing (PDF/Word/Excel/PPT/TXT)
│   │   └── docx_export.py          # Markdown → Word document conversion
│   └── storage/
│       ├── memory/                 # In-memory persistence (default)
│       ├── database/               # PostgreSQL (optional)
│       └── s3/                     # S3 storage (optional)
├── run.bat                         # Windows one-click launch
├── setup.bat                       # Windows one-click install
├── dsh-plugin/                     # DSH plugin package (dsh plugin add; includes preset/ copy)
├── docs/                           # Docs: dsh-integration.md (integration) / dsh-validation.md (validation flow)
├── scripts/                        # incl. sync_dsh_instance.ps1 (DSH working-instance sync)
├── .env.example                    # Environment variable template
├── pyproject.toml                  # Dependency config
├── LICENSE                         # MIT License
└── README.md

Tech Stack

Contributing

Contributions welcome!

1. Fork this repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

Dev environment setup:

python -m venv .venv
pip install -e ".[all]"
pip install pytest pytest-asyncio

Changelog

See CHANGELOG.md for the full release history.

License

MIT License — Free to use, modify, and distribute.