admin
6eeb8b9087
Wraps the site tool wpb_build_page: build or update a Word Page from {kind, html} sections. The page lands as a native Word Page (payload in post meta, builder-rendered), so it stays editable and undoable in the builder. Also documents the builder tools in the bundled skill and README.
116 lines
4.9 KiB
Markdown
116 lines
4.9 KiB
Markdown
# 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
|