How use-novamira/novamira works
1. What this repository is
Novamira is a WordPress plugin that exposes a Model Context Protocol (MCP) server so AI agents can operate on a WordPress site. The core architectural boundary is between the AI agent / MCP client and the WordPress runtime, with Novamira translating agent requests into WordPress-aware operations.
2. Primary entry point
novamira.php is the plugin bootstrap. It likely wires together the major subsystems under includes/, registers WordPress hooks, and activates the MCP-facing capabilities. composer.json and composer.lock indicate PHP dependency management, while stubs/wordpress-constants.php supports development/static analysis against WordPress-specific globals/constants.
3. Capability/ability layer
The includes/abilities/ directory is the main execution surface. Each file corresponds to a discrete action such as reading/writing files, listing directories, editing or deleting files, enabling/disabling files, creating upload/admin links, running WP-CLI, and executing PHP. This is the most important subsystem for diagrams: it is the operation layer that bridges AI requests to privileged site actions.
4. Execution model and trust boundary
Several abilities are intentionally high-trust: execute-php.php, run-wp-cli.php, and file mutation abilities imply direct server-side execution. sandbox-loader.php, rest-shim.php, and the various link-generation helpers suggest the plugin supports controlled entry points and remote invocation paths, likely to separate browser/admin interactions from backend execution. The key diagram boundary is untrusted agent input → authenticated capability dispatch → WordPress/PHP/filesystem side effects.
5. Gutenberg editing workflow
includes/abilities/gutenberg/ is a specialized subsystem for content editing/finalization in the block editor domain. It includes pending batch/change management, content read/write, finalization URL/runtime lookup, and a rest.php endpoint. This indicates a multi-step content change pipeline rather than direct one-shot edits: changes are staged, reviewed/finalized, and then applied through a runtime helper.
6. Skills subsystem
includes/skills/ is a separate abstraction layer for reusable AI skills. It has:
- abilities/ wrappers for skill CRUD operations,
- built-in/ markdown skill definitions,
- catalog.php, parser.php, sources.php, and prompts.php for loading, parsing, and presenting skills,
- cpt.php and admin.php for WordPress-backed storage and UI,
- templates/ for editing/list/upload flows.
Architecturally, this is a content/catalog subsystem for organizing agent behaviors, distinct from the low-level action abilities.
7. Admin and onboarding surfaces
The plugin includes multiple administrative pages and helpers: admin-page.php, connect-page.php, instructions-admin.php, gutenberg-finalizer-admin.php, skills/admin.php, and pro-upsell.php. admin-access-link.php and upload-link.php imply link-based onboarding or remote access bootstrap flows. These components provide the human operator control plane for setup, permissions, and guidance.
8. Content storage and WordPress integration
skills/cpt.php suggests WordPress custom post type usage for persisting skill data, while the Gutenberg files interact with content editing state. The plugin is therefore not just an external server; it is deeply embedded in WordPress storage and admin APIs. Any architecture diagram should show WordPress database/content APIs as a central persistence layer for at least part of the plugin’s state.
9. UI assets
includes/assets/hub.css, hub.js, and sandbox.css, plus includes/skills/assets/admin.css, support the plugin’s admin experiences. These are not core logic, but they matter because the admin/setup flows are likely delivered through WordPress-rendered pages with custom interaction logic for connecting, uploading, sandboxing, and managing skills.
10. Update and release plumbing
includes/updater.php, build/, and build-ignore indicate release packaging and update support. This is a plugin-distribution concern rather than runtime behavior, but it matters for architecture because the codebase is intended to be installed and maintained as a WordPress plugin lifecycle artifact.
11. Overall data flow
The dominant flow is: AI agent/MCP client → Novamira MCP/ability dispatch → WordPress/PHP/filesystem/CLI/Gutenberg subsystems → persisted site state or file changes. A secondary flow exists for admin/operator setup → connect/upload/access links → plugin initialization and permissioned use. The Gutenberg and skills subsystems add staged workflows on top of that core execution path.
12. How to draw it
A good diagram would center on the WordPress plugin boundary, with separate boxes for:
- MCP/entry layer,
- ability execution layer,
- Gutenberg staging/finalization,
- skills catalog/admin/storage,
- admin/onboarding UI,
- filesystem/PHP/WP-CLI side effects.
Emphasize that this is an agent-control plugin for WordPress, not a conventional standalone web app.
Main entry points: novamira.php novamira.php · discover-abilities.php Discover abilities · gutenberg/bootstrap.php Gutenberg bootstrap · skills/bootstrap.php Skills bootstrap
Components 25
Plugin core
Bootstrap and shared plugin infrastructure.
- novamira.php · Plugin entry point that wires the runtime together.
novamira.php - Helpers · Common utility functions used across the plugin.
includes/helpers.php - REST shim · Bridges external requests into plugin execution paths.
includes/rest-shim.php - Sandbox loader · Loads the sandboxed execution environment.
includes/sandbox-loader.php
Ability layer
Agent-facing operations that act on files, PHP, and WordPress.
- Discover abilities · Finds and exposes available abilities to the MCP surface.
includes/abilities/discover-abilities.php - File ops · Read, write, edit, delete, list, enable, and disable file actions.
includes/abilities/read-file.php - Execute PHP · Runs server-side PHP code directly.
includes/abilities/execute-php.php - WP-CLI · Executes WordPress command-line operations.
includes/abilities/run-wp-cli.php
Gutenberg flow
Staged content-editing pipeline for block editor operations.
- Gutenberg bootstrap · Initializes the staged Gutenberg content workflow.
includes/abilities/gutenberg/bootstrap.php - Pending batches · Creates, lists, reads, and deletes staged content batches and changes.
includes/abilities/gutenberg/create-pending-batch.php - Content IO · Reads and writes block-editor content during the staged flow.
includes/abilities/gutenberg/get-content.php - Finalization · Builds finalization URLs and runtime helpers for applying changes.
includes/abilities/gutenberg/get-finalization-url.php - Gutenberg REST · REST endpoint for the Gutenberg editing pipeline.
includes/abilities/gutenberg/rest.php
Skills subsystem
Catalog, storage, prompts, and CRUD for reusable AI skills.
- Skills bootstrap · Initializes the skills subsystem.
includes/skills/bootstrap.php - Skills catalog · Loads, parses, and resolves skill sources and prompts.
includes/skills/catalog.php - Skills storage · Persists skills using WordPress-backed content structures.
includes/skills/cpt.php - Skills CRUD · Get, write, edit, and delete skill records.
includes/skills/abilities/skill-get.php - Skills UI · Admin pages and templates for listing, editing, and uploading skills.
includes/skills/admin.php
Admin surfaces
Operator pages, links, and onboarding flows.
- Access links · Creates admin-access and upload links for remote setup.
includes/abilities/create-admin-access-link.php - Admin pages · Plugin admin pages for connection, instructions, and finalizer setup.
includes/admin-page.php - Connect page · Setup flow for connecting the plugin to an operator or agent.
includes/connect-page.php - Gutenberg admin · Admin surface for configuring Gutenberg finalization.
includes/gutenberg-finalizer-admin.php
Release plumbing
Packaging, updates, and development support files.
- Updater · Plugin update and lifecycle support.
includes/updater.php - Build files · Packaged build outputs and ignore rules.
build/build - WP constants · Static-analysis stubs for WordPress globals and constants.
stubs/wordpress-constants.php
Connections 30
- novamira.php → Helpers: loads · Bootstrap shares utilities across subsystems.
- novamira.php → REST shim: routes · Registers external request entry points.
- novamira.php → Sandbox loader: loads · Initializes controlled execution context.
- novamira.php → Discover abilities: registers · Exposes capability catalog to the MCP layer.
- Discover abilities → File ops: includes · Publishes filesystem and mutation abilities.
- Discover abilities → Execute PHP: includes · Publishes high-trust code execution.
- Discover abilities → WP-CLI: includes · Publishes CLI automation.
- Discover abilities → Access links: includes · Publishes onboarding link-generation actions.
- File ops → Sandbox loader: uses · File actions may execute inside the sandboxed loader path.
- Execute PHP → Sandbox loader: uses · Direct PHP execution is mediated by the execution loader.
- WP-CLI → REST shim: invoked via · Remote/HTTP-facing requests can reach command execution through the shim.
- novamira.php → Gutenberg bootstrap: enables · Bootstraps the staged Gutenberg workflow.
- Gutenberg bootstrap → Pending batches: manages · Creates and tracks staged changes.
- Gutenberg bootstrap → Content IO: reads/writes · Handles editor content access and mutation.
- Gutenberg bootstrap → Finalization: finalizes · Produces URLs and runtime context for applying changes.
- Gutenberg bootstrap → Gutenberg REST: exposes · Provides REST entry point for the editing pipeline.
- novamira.php → Skills bootstrap: loads · Initializes the reusable skills subsystem.
- Skills bootstrap → Skills catalog: builds · Loads and resolves skill definitions and prompts.
- Skills bootstrap → Skills storage: persists · Stores skills in WordPress-backed content.
- Skills bootstrap → Skills CRUD: exposes · Provides agent-facing skill operations.
- Skills bootstrap → Skills UI: renders · Serves the admin editing/list/upload experience.
- Skills catalog → Skills storage: reads · Catalog resolves stored skills from WP content.
- Skills UI → Skills storage: manages · Admin screens edit and upload persisted skills.
- Skills UI → Admin pages: embedded in · Skills UI is part of the broader operator control plane.
- novamira.php → Admin pages: registers · Main plugin bootstrap wires admin surfaces.
- Admin pages → Connect page: includes · Connection onboarding is one of the main admin views.
- Admin pages → Gutenberg admin: includes · Finalizer configuration is exposed in admin.
- novamira.php → Updater: loads · Adds update and lifecycle support.
- novamira.php → Build files: packages · Release artifacts are part of distribution.
- novamira.php → WP constants: uses · Development stubs support WordPress-specific globals.