# 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

```bash
# 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`):

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

Serve several sites instead — `WORDVIBE_MCP_SITES` takes precedence:

```env
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):

```bash
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 |
| `wordvibe_build_page` | Build/update a **Word Page Builder** page from `{kind, html}` sections (native in the builder) |

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