wordvibe-hermes/README.md

wordvibe-hermes

A Hermes Agent plugin that lets your agent drive WordPress sites running the WordVibe plugin — read and write files, make targeted code edits, search the codebase, query the database, manage posts/plugins/themes, run WP-CLI and more — from any Hermes surface (CLI, Telegram, cron, subagents).

It talks to the MCP server that ships inside the WordVibe WordPress plugin, so there is nothing extra to install on the site:

Endpoint	POST {site}/wp-json/wp-ide/v1/mcp (Streamable HTTP, JSON-RPC 2.0)
Auth	Authorization: Bearer <wv_mcp_server_key> (or a WP Application Password)
Gate	WordVibe → Settings → MCP → enable MCP Server Mode, copy the key
Tools	the plugin's own agent tool registry (wv_ai_tools()), minus php_eval and db_mutate, which the site blocks remotely
Protocol	MCP 2024-11-05; methods initialize, initialized, tools/list, tools/call, ping

Install

# from a git URL
hermes plugins install https://github.com/<you>/wordvibe-hermes

# or drop the folder in place
git clone https://github.com/<you>/wordvibe-hermes ~/.hermes/plugins/wordvibe-hermes

Then add the credentials to your Hermes .env (same dir as config.yaml — hermes config env-path):

WORDVIBE_SITE_URL=https://mysite.com
WORDVIBE_MCP_KEY=the-key-from-settings-mcp

Serve several sites instead — WORDVIBE_MCP_SITES takes precedence:

WORDVIBE_MCP_SITES=[{"name":"client-a","url":"https://a.com","key":"..."},{"name":"client-b","url":"https://b.com","key":"..."}]

Enable the plugin and restart Hermes (plugins are opt-in; tool changes need a fresh session):

hermes plugins enable wordvibe-hermes
hermes plugins list          # expect: wordvibe-hermes  1.0.0  8 tools
hermes                        # then: /wordvibe sites

Debug a plugin that won't load with HERMES_PLUGINS_DEBUG=1 hermes plugins list.

Tools

Tool	What it does
wordvibe_sites	List configured sites (optionally probe reachability of each MCP endpoint)
wordvibe_site_info	MCP server identity (plugin version) + WordPress name/version/theme/plugin count
wordvibe_tools	The catalogue of tools the site exposes (filterable)
wordvibe_call	Escape hatch — call any site tool by name with its own arguments
wordvibe_read_file	Read any file in the WP install (optional lines="10-60")
wordvibe_write_file	Overwrite a file (the site snapshots the previous version first)
wordvibe_edit_file	Targeted search → replace edit (safer than a full write)
wordvibe_search	Codebase search across themes/plugins/core, plain text or regex

Slash command for when you don't want to spend a model turn:

/wordvibe sites
/wordvibe info flexi
/wordvibe tools
/wordvibe call post_list '{"post_type":"post","limit":5}'

Why only 8 tools

The site exposes ~100 tools over MCP. Registering all of them would put ~100 schemas on every API call (Hermes sends the whole tool schema set each turn), so this plugin registers a lean wrapper set and routes everything else through wordvibe_call — the agent asks wordvibe_tools what exists, then calls it. If you'd rather have a specific tool as first-class, add it to schemas.py + tools.py.

Using it well

• Always wordvibe_read_file before wordvibe_write_file. Prefer wordvibe_edit_file for small changes.
• db_query is read-only by design; db_mutate and php_eval are blocked from MCP — use the site's own UI or a snapshot-backed file edit instead.
• Writes are real. The site keeps a snapshot of the previous version (wp-content/wv-safety/snapshots/) so rollback_list / rollback_restore can undo a mistake — mention it to the user when you change code.
• Handy pass-throughs: post_list, plugin_list, theme_list, list_directory, file_search, security_scan_installed, cli_exec, create_post, update_option, fetch_url.

Layout

wordvibe-hermes/
├── plugin.yaml        # manifest (tools + required env)
├── __init__.py        # register(ctx): tools, /wordvibe command, hook
├── schemas.py         # what the LLM reads
├── tools.py           # handlers (JSON in, JSON out, never raise)
├── mcp_client.py      # stdlib JSON-RPC client for the site MCP endpoint
└── skills/
    └── wordvibe-sites/SKILL.md

No third-party dependencies — urllib only.

Security

• The bearer key grants the full remote tool surface of the site (minus the two blocked tools). Treat it like an admin password: keep it in .env, never in the repo, rotate it from Settings → MCP.
• Per-site: disabling MCP Server Mode immediately makes the endpoint return 403.
• Hermes's secret redaction applies to tool output, but the key itself should still only live in .env.

License

MIT