Idea2Post Agent Mode

Adding an autonomous Hermes-orchestrated "Agent" layer to a production content SaaS — without breaking a single existing feature.

Submitted to the Hermes Agent Challenge.

---

What this is

Idea2Post is a live SaaS that turns one idea into multi-format content (blog, Facebook, Twitter, email, etc.). The existing product is a one-shot generator: paste idea → get posts.

This repo adds Agent Mode as a parallel route. The user gives a high-level goal in English — "What should I post on Facebook this week?" — and a Hermes Agent autonomously:

1. Calls the existing system's MCP tools to fetch real DB state and crawled competitor posts
2. Reasons about themes, gaps, and engagement signal
3. Optionally invokes the in-house generator for concrete drafts
4. Streams tool progress + content tokens back over SSE in real time

Existing one-shot generator, cron-driven auto-pipelines, and 7 background workers are untouched.

Architecture

Browser ──SSE──▶ PHP proxy ──HTTP──▶ Hermes Agent
                                    (gateway @ 127.0.0.1:8642)
                                           │
                                           ├─ web search (built-in)
                                           └─ idea2post MCP (stdio)
                                                  │
                                                  └─▶ PHP CLI ─▶ MySQL
                                                              └─▶ content engine

Files

Path	Purpose
opt/idea2post-mcp/server.py	Python MCP server exposing 7 idea2post tools
engine/i2p_agent_cli.php	PHP CLI bridge — MySQL queries + content engine wrapper
pages/i2p-agent.php	Chat UI (vanilla JS, Tailwind, SSE consumer)
pages/i2p-agent-api-stream.php	SSE proxy: browser ↔ Hermes Agent
pages/i2p-agent-api.php	Non-streaming fallback (POST → JSON)

MCP tools exposed

Tool	What it does
status_report	Snapshot: queued/done/failed jobs, content count, competitor count
list_competitors	Tracked competitor accounts (YouTube, RSS, sites)
recent_competitor_posts	Most recently crawled posts — the trend signal
list_publish_accounts	Connected FB/LinkedIn/WordPress for queueing
list_pipelines	Active autonomous content loops
generate_content	Multi-format viral content via existing engine
queue_publish	Enqueue a content row for publishing (gated on explicit consent)

Install (Linux VPS, root)

# 1. Install Hermes Agent
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup

# 2. Configure model — Llama / GPT-OSS / DeepSeek via OpenRouter free tier
cat >> ~/.hermes/.env << 'EOF'
OPENROUTER_API_KEY=sk-or-v1-XXXX
API_SERVER_ENABLED=true
API_SERVER_KEY=<generate-with-openssl-rand-hex-32>
EOF

# Edit ~/.hermes/config.yaml — set:
#   model:
#     default: "openai/gpt-oss-120b:free"
#     provider: "openrouter"

# 3. Trim builtin toolsets to fit context budget
for t in browser terminal file code_execution vision image_gen tts \
         session_search delegation cronjob messaging computer_use skills; do
    hermes tools disable $t
done

# 4. Deploy idea2post MCP server
mkdir -p /opt/idea2post-mcp
cp opt/idea2post-mcp/server.py /opt/idea2post-mcp/
chmod +x /opt/idea2post-mcp/server.py
echo y | hermes mcp add idea2post --command /opt/idea2post-mcp/server.py

# 5. Drop PHP files into your idea2post install
cp engine/i2p_agent_cli.php   /var/www/idea2post.app/engine/
cp pages/i2p-agent*.php       /var/www/cp.mycoach.ing/pages/

# 6. Make Hermes API key readable by PHP
mkdir -p /etc/idea2post
grep API_SERVER_KEY ~/.hermes/.env | awk -F= '{print "API_KEY="$2}' \
    > /etc/idea2post/hermes-key.txt
chown root:www-data /etc/idea2post/hermes-key.txt
chmod 640 /etc/idea2post/hermes-key.txt

# 7. Install + start Hermes gateway as a user systemd service
printf "y\ny\n" | hermes gateway install

Hit https://your-app.example.com/?page=i2p-agent after logging in.

Stack

• Hermes Agent v0.14.0
• LLM: openai/gpt-oss-120b:free via OpenRouter (tool-calling on free tier)
• MCP: official mcp Python SDK (FastMCP) over stdio
• Backend: PHP 8.3, MySQL/MariaDB
• Frontend: vanilla JS, Tailwind CDN, Server-Sent Events
• Infra: Caddy → Apache, systemd user service for the agent gateway

Why Hermes was the right fit

• The agent loop (reason → call tool → observe → reason) is solved internally. I POST a goal; Hermes handles the whole loop.
• MCP gave me a clean tool surface. Adding a new capability = one Python function in server.py — no prompt engineering.
• hermes.tool.progress SSE events let the UI visibly show each tool firing in real time. This is the difference between "loading spinner" and "the agent is thinking on screen".

The existing one-shot generator is now one of many tools the agent can choose to call. Same SaaS, agentic UX.

License

Inherits the parent project license. The agent layer itself is yours to copy.