NV oOS Plugin — Docker/WSL2 Setup & Operational Guide
Complete operational skill for the NV Digital Open Operator System (oOS) WordPress plugin running in Docker on Windows/WSL2. Covers the full lifecycle: startup, assistant creation, credential tokens, MCP tool calling, API key auto-detection, and tool assignment.
When to use this skill
- Setting up the plugin in a Docker Compose stack for the first time
- Plugin produces
file_put_contents/mkdirPHP warnings on startup - Docker volume mount fails with "invalid volume specification"
- Need to create an assistant programmatically (not via admin UI)
- Need to generate a
cred_xxxxx.SECRETtoken for the MCP bridge - Calling MCP tools via
curl/ HTTP JSON-RPC - API keys not being picked up from Docker environment variables
- Troubleshooting 0 tools returned from
tools/list(or HTTP 403wp_mcp_ai_assistant_scope_required— strict-scope toggle, v1.1.90+) - Configuring the plugin for IGCSE study (which tools to assign)
- WordPress.org submission prep — Plugin Check (PCP) runs, wp.org listing
screenshots, packaging exclusions, and the compliance checklist are covered
by the
.agents/skills/mcp-ai-wpoos-wporg-submissionskill instead of this one (see that skill for Docker PCP recipes and the CI gate anatomy)
Architecture
Zed / Claude Desktop / Cursor
│
│ MCP JSON-RPC over HTTP
▼
┌─────────────────────────────────┐
│ WordPress REST API │
│ /wp-json/mcp-ai/v1/mcp │ ← MCP endpoint
│ Auth: Bearer cred_xxxxx.SECRET │
└──────────────┬──────────────────┘
│
┌─────────┴──────────┐
│ WP_MCP_AI_* │
│ Tool Registry │ ~355 base / ~1,732 full tools
│ Credentials │ Token validation
│ Assistant (CPT) │ Post type: mcp_ai_assistant
└────────────────────┘
Plugin Distribution & Dependency Headers
- The base plugin ships under three folder slugs depending on distribution:
mcp-ai-wpoos(dev checkout),nvdigital-open-operator-system-oos(wp.org base),nvdigital-open-operator-system-oos-complete(complete bundle). - Never declare
Requires Plugins: mcp-ai-wpoosin an addon. WordPress core matches dependency entries against the installed plugin's folder slug (dirname()of the plugin file) with AND semantics — not the slug the dependency declares in its own header — so one static header can only ever satisfy one of the three distributions and blocks the other two at activation ("requires 1 plugin to be installed and activated"). The Schedule Anything platform shipped exactly this header and was blocked on complete-bundle sites — fixed by #7132 (header dropped with a comment; the slug-agnostic runtime guardsa_platform_base_is_active()→wp_mcp_ai_core_loaded()already detects all three flavors).addons/page-agentstill carries the header — tracked in issue #7140. - Repo-specific deviations from curated skills belong in internal
(project-owned) skills, never in the curated copies. The
wp-*skills under.agents/skills/+includes/bundled-skills/are curated from the upstreamLonsdale201/wp-agent-skillscatalogue and are refreshed through the curation flow — an edit made directly in a curated SKILL.md is lost on the next re-curation/update. This section is the persistent home for the folder-slug lesson the upstreamwp-plugin-bootstrapskill does not carry; future repo-specific WP lessons should land here (or in another project-owned skill) for the same reason.
Quick Start (Docker)
1. Environment Setup
The docker-compose.yml uses relative paths (.) for volume mounts,
which Docker Desktop translates automatically for WSL2 — no manual path
fix needed.
cp .env.example .env
# Edit .env: set BASE_URL=http://localhost:8000 and add API keys
wsl docker compose up -d
# Wait for wp-plugin-seed to exit (installs WP + activates plugin)
wsl docker compose logs -f wp-plugin-seed
WordPress is at http://localhost:8000, admin at /wp-admin
(admin / password).
Design Stack deployment (F:\GITHUB\design-stack)
The environment actually operated day-to-day uses different ports and credentials than this repo's dev compose (verified on the live stack, 2026-09 session):
| Service | Address |
|---|---|
| WordPress | http://localhost:8092 — admin at /wp-admin (admin / design_admin_2026) |
| Media worker | http://localhost:3100 |
| MySQL | localhost:3308 |
- The stack mounts the plugin from
design-stack/plugins/mcp-ai-wpoos— an NTFS junction to the plugin repo — so code edits land in this repo. design-stack/.agents/skills/design-*andmcp-ai-wpoos-pluginare junctions into this repo's.agents/skills/(creation script:bin/create-skill-junctions.ps1), so skill edits ship in the same PR as plugin code.wpinside the Design Stack WP container requires--allow-root.- Production console:
https://console.nvoos.cloud/is the live NV oOS site (verified 2026-10:/wp-json/mcp-ai/v1/status= operational,/wp-json/mcp-ai/v1/assistantsreturns 401 without a Bearer credential). The dictation desktop app points here for its Stage-2 polish / archive backend; credentials must be issued on that site (see the provisioning recipe above) and stored via the app's Settings → NV oOS tab.
2. API Key Auto-Detection (v1.1.47+)
On activation, the plugin now automatically reads well-known environment variables and populates settings. No manual bridging script needed.
| Environment Variable | Plugin Setting |
|---|---|
OPENAI_API_KEY |
openai_api_key |
GEMINI_API_KEY / GOOGLE_API_KEY |
gemini_api_key |
ANTHROPIC_API_KEY |
anthropic_api_key |
DEEPSEEK_API_KEY |
deepseek_api_key |
BRAVE_API_KEY / BRAVE_SEARCH_API_KEY |
brave_search_api_key |
TAVILY_API_KEY |
tavily_api_key |
PERPLEXITY_API_KEY |
perplexity_api_key |
LM_STUDIO_API_KEY |
lm_studio_api_key |
NVIDIA_API_KEY |
nvidia_api_key |
HUGGINGFACE_API_KEY / HF_API_KEY |
huggingface_api_key |
CLOUDFLARE_API_TOKEN |
cloudflare_api_token |
KIMI_API_KEY |
kimi_api_key |
DIGITALOCEAN_API_KEY |
digitalocean_api_key |
STABILITY_API_KEY |
stability_api_key |
MUBERT_API_KEY |
mubert_api_key |
EXA_API_KEY |
exa_api_key |
CRAWL4AI_API_KEY |
crawl4ai_api_key |
REMOVEBG_API_KEY |
removebg_api_key |
GOOGLE_MAPS_API_KEY |
google_maps_api_key |
ITA_TARIFF_API_KEY |
ita_tariff_api_key |
Set them before starting Docker:
export OPENAI_API_KEY="sk-..."
export BRAVE_API_KEY="BSA..."
wsl docker compose up -d
Guard rails:
- Runs once per site (flag:
wp_mcp_ai_env_keys_checked) - Never overwrites existing manually-configured keys
- Stores in both
wp_mcp_ai_settingsarray AND standalonewp_mcp_ai_*options - Plaintext values are auto-migrated to AES-256-GCM encrypted on first read
Implementation: includes/bootstrap/activation.php →
wp_mcp_ai_auto_detect_env_keys(), called from wp_mcp_ai_activate_single_site().
3. Fix Uploads Directory Warnings (v1.1.47+)
The plugin now uses wp_mkdir_p() (WordPress core, since WP 2.0) with
is_dir() guards before all file_put_contents() calls in:
includes/integrations/class-wp-mcp-ai-custom-tool-loader.phpincludes/paper-store/class-wp-mcp-ai-paper-store-manager.php
If you still see warnings on older versions, pre-create the directories:
docker compose exec -T wordpress sh -c "
mkdir -p /var/www/html/wp-content/uploads/wp-mcp-ai-custom-tools
mkdir -p /var/www/html/wp-content/uploads/mcp-ai-wpoos/paper-store
chown -R www-data:www-data /var/www/html/wp-content/uploads
"
4. WSL2 Docker Path Compatibility
The current docker-compose.yml uses relative paths (.) which Docker Desktop
translates automatically. No action needed. If you encounter path issues with
custom setups, use WSL paths (/mnt/c/..., /mnt/f/...) rather than Windows
drive letters (C:/..., /F:/...). See Docker Compose header comment for details.
5. Symlinks on WSL2 / Windows
ln -s silently creates copies on NTFS drives. When you run ln -s from
WSL targeting a path on a Windows-mounted drive (e.g. /mnt/f/...), it does
NOT error — but it creates a real directory copy instead of a symlink. You
need Windows Developer Mode enabled OR admin privileges for true symlinks.
Workaround: use NTFS junctions. Junctions are directory-only reparse points that work without admin and are transparent to both Windows and WSL:
# PowerShell (from WSL):
Remove-Item "F:\path\to\link" -Recurse -Force
New-Item -Path "F:\path\to\link" -ItemType Junction -Target "F:\path\to\target"
# Or via cmd.exe (no admin needed for junctions):
cmd.exe /c "mklink /J F:\path\to\link F:\path\to\target"
Batch creation is best done via a PowerShell .ps1 script, not a shell
loop — each cmd.exe /c spawns a new process with the copyright banner.
When to use which:
| Type | Command | Admin | Scope |
|---|---|---|---|
| Junction | mklink /J |
No | Directories only, same volume |
| Symlink (file) | mklink |
Usually | Files, cross-volume OK |
| Symlink (dir) | mklink /D |
Yes | Directories, cross-volume OK |
| WSL symlink | ln -s |
Dev Mode | Only on WSL-native filesystems |
Design Stack:
.agents/skills/design-*andmcp-ai-wpoos-pluginuse junctions pointing toplugins/mcp-ai-wpoos/.agents/skills/. The creation script is atbin/create-skill-junctions.ps1.
Creating an Assistant Programmatically
Assistants are WordPress custom post types (mcp_ai_assistant). Create one
via PHP in the container:
<?php
define( 'WP_USE_THEMES', false );
require_once '/var/www/html/wp-load.php';
// 1. Create the assistant post
$post_id = wp_insert_post( array(
'post_type' => 'mcp_ai_assistant',
'post_title' => 'My Assistant',
'post_content' => 'Description of what this assistant does',
'post_status' => 'publish',
), true );
if ( is_wp_error( $post_id ) ) {
die( 'Failed to create assistant: ' . $post_id->get_error_message() );
}
// 2. Assign tools (required — otherwise tools/list returns [])
$tools = array(
'search_content', 'web_search', 'create_post',
'save_post', 'get_recent_posts', 'create_chart',
'get_site_health', 'get_environment_status',
// ... add more from the IGCSE list below
);
update_post_meta( $post_id, '_wp_mcp_ai_tools', $tools );
// 3. Generate a credential token
$result = WP_MCP_AI_Credentials::issue_credential( $post_id, 1 );
if ( is_wp_error( $result ) ) {
die( 'Failed to issue credential: ' . $result->get_error_message() );
}
$token = $result['token']; // format: cred_XXXXX.SECRET
echo "Assistant ID: $post_id\n";
echo "Token: $token\n";
Key insight: If _wp_mcp_ai_tools post meta is empty, the MCP tools/list
returns [] even though hundreds of tools are registered at the system level.
Always assign tools after creating an assistant.
WP-CLI provisioning (preferred — verified end-to-end)
The PHP path above works, but the WP-CLI path is shorter and idempotent. Verified on the Design Stack (2026-09):
# 0. In the Design Stack WP container, wp requires --allow-root.
# (In this repo's own compose: docker compose run --rm wp-cli ...)
# 1. Discover valid tool slugs before assigning.
wp mcp-ai tool list # base registry: slug + enabled + capability
wp mcp-ai toolkit list # Pro toolkit settings keys
wp mcp-ai tool call <slug> --args='{...}' --assistant-id=<id> --format=json
wp mcp-ai security posture --format=json # v1.1.93+ (audit, purge-audit, gate, keys)
wp mcp-ai model list|suggestions|discover # v1.1.93+
wp mcp-ai crm lead list # v1.1.93+ Pro entity trees: crm, incident,
wp mcp-ai schedule list # maintenance, schedule, workflow, vault
wp mcp-ai workflow list # (metadata-only), remote-site, communication,
wp mcp-ai media-studio status # media-studio — all manage_options-gated.
# Full operator reference: docs/operations/wp-cli.md (WP-CLI 2.9+ minimum).
# Canonical namespaces are mcp-ai calendar/place + mcp-ai ezuite/flowhub/
# shopify-sync/profession; legacy top-level names remain as aliases.
# 2. Create the assistant record.
wp mcp-ai assistant create --title="Brand Assistant" --status=publish --porcelain
# → prints the new assistant ID
# 3. Set runtime meta (v1.1.93+, PR #6852): assistant create/update/get and
# assistant tools list/add/remove now write/read the canonical
# _wp_mcp_ai_* keys directly — --provider / --model / --system-prompt /
# --tools flags are supported, so the post-meta workaround below is only
# needed on pre-1.1.93 installs.
wp mcp-ai assistant update <id> --provider=openai --model=gpt-4o-mini \
--system-prompt="$(cat assistant-system-prompt.md)"
wp mcp-ai assistant tools add <id> web_search deep_research create_post
# Pre-1.1.93 fallback: the legacy create/update wrote mcp_ai_model /
# mcp_ai_system_prompt keys the runtime did NOT read.
wp post meta update <id> _wp_mcp_ai_provider openai
wp post meta update <id> _wp_mcp_ai_model gpt-4o-mini
wp post meta update <id> _wp_mcp_ai_temperature 0.7
wp post meta update <id> _wp_mcp_ai_system_prompt "$(cat assistant-system-prompt.md)"
wp post meta update <id> _wp_mcp_ai_classification internal
wp post meta update <id> mcp_ai_required_capability manage_options
# Tools is a serialized PHP array; wp post meta update would store a string,
# so use wp eval for that one key:
wp eval 'update_post_meta(<id>, "_wp_mcp_ai_tools", array("web_search", "deep_research", "create_post"));'
# 4. Issue the credential (prints cred_xxxxx.SECRET exactly once).
wp mcp-ai credential issue <id> --porcelain
# 5. Smoke test (chat REST is the reliable verification path).
curl -s -X POST http://localhost:8092/wp-json/mcp-ai/v1/chat \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"assistant_id": <id>, "messages": [{"role":"user","content":"Reply with exactly: OK"}]}'
MCP Token & Authentication
Generating a Token
Tokens follow the format cred_XXXXX.SECRET (32-char secret, bcrypt hashed):
$result = WP_MCP_AI_Credentials::issue_credential( $assistant_id, $user_id );
$token = $result['token']; // Already includes "cred_" prefix
The parse_token() method validates the format:
- Must be a non-empty string
- Must contain a
.separator (exactly 2 parts) - First part must start with
cred_ - Both parts must be non-empty
Default credential lifetime is 90 days (configurable via
credential_lifetime_days setting; 0 = no expiry).
Using the Token
# JSON-RPC via curl
curl -s -X POST http://localhost:8000/wp-json/mcp-ai/v1/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer cred_xxxxx.SECRET" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
# MCP Bridge (stdio ↔ HTTP relay)
node bin/mcp-bridge.js
# Requires env: MCP_AI_BASE_URL + MCP_AI_TOKEN
Auth Methods (in order of preference)
- Bearer token (
cred_xxxxx.SECRET) — recommended for MCP clients - Raw credential (
Authorization: cred_xxxxx.SECRETwithoutBearer) — accepted since v1.1.55 for agent configs that forward the header verbatim (e.g. Cloudways Agent); disable via filterwp_mcp_ai_accept_raw_credential_header - OAuth 2.0 (authorization_code grant) — browser-based MCP app flow
- Mesh Key (
X-WP-MCP-AI-Mesh-Keyheader) — mesh federation - WordPress nonce (
X-WP-Nonceheader + auth cookie) — browser admin
Application passwords (Basic auth) are not supported on the MCP endpoint. Use Bearer tokens instead.
MCP JSON-RPC Protocol
The endpoint is at /wp-json/mcp-ai/v1/mcp. Standard JSON-RPC 2.0.
Initialize
{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "my-client", "version": "1.0"}
},
"id": 1
}
Response includes serverInfo.name (the assistant title) and server
capabilities (tools, resources, etc.).
List Tools
{"jsonrpc": "2.0", "method": "tools/list", "id": 1}
Returns only tools assigned to the authenticated assistant via
_wp_mcp_ai_tools post meta. Each tool includes name, description,
and inputSchema (JSON Schema).
Call a Tool
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "tool_slug",
"arguments": {"param1": "value1"}
},
"id": 1
}
Response is in result.content[0].text as a JSON string. Canonical envelope:
success returns an array; errors return a WP_Error object serialized as
{"code":"...", "message":"...", "data":{...}}.
HTTP status semantics (v1.1.55+)
JSON-RPC error envelopes are returned with HTTP 200 so client SDKs that
drop non-2xx bodies (e.g. the TypeScript SDK bundled with mcp-remote)
still relay errors to the agent. Pre-1.1.55, errors were returned as
400/404/500 and such SDKs silently discarded them — tool calls appeared
to return nothing. Auth failures (401/403) and pre-dispatch guards (429)
keep their HTTP statuses. Revert via filter wp_mcp_ai_mcp_error_http_status.
Since v1.1.90 the opt-in mcp_require_assistant_scope setting adds one more
403: tools/list/tools/call fail closed (wp_mcp_ai_assistant_scope_required)
when no assistant resolves — see Troubleshooting.
Testing Tools Through the Chat REST Endpoint (no MCP client needed)
The chat UI executes tools through POST /wp-json/mcp-ai/v1/tools — the
fastest way to verify a tool end-to-end with curl instead of spinning up
an MCP client or a chat session.
{
"assistant_id": 9,
"tool": "search_upwork_jobs",
"arguments": { "query": "wordpress developer", "limit": 5 }
}
Auth:
X-WP-Nonce+ the logged-in cookie (same origin), or a Bearer credential. The nonce must be bound to a real session — generate one from a probe script, not from a bare CLIwp_create_nonce():$expiration = time() + 3600; $token = WP_Session_Tokens::get_instance( $uid )->create( $expiration ); $cookie = wp_generate_auth_cookie( $uid, $expiration, 'logged_in', $token ); $_COOKIE[ LOGGED_IN_COOKIE ] = $cookie; // nonce binds to this session wp_set_current_user( $uid ); $nonce = wp_create_nonce( 'wp_rest' ); // use with curl -H "X-WP-Nonce: ..."Gate 1 — assistant allowlist: every assistant scopes tool access via the
_wp_mcp_ai_toolspost meta. A tool not in that list returns403 wp_mcp_ai_tool_forbidden("This assistant is not allowed to execute the requested tool"). Grant access withupdate_post_meta( $assistant_id, '_wp_mcp_ai_tools', $tools_with_slug ).Gate 2 — availability:
search_upwork_jobs(and the other Upwork CRM tools) also needenable_crm_toolkitinwp_mcp_ai_settings.DuckDuckGo returns no real SERPs. The default
web_search_provider(duckduckgo) hits the free Instant Answer API, which returns emptyRelatedTopicsfor ordinary queries — so fallback-mode tools that depend onweb_search(search_upwork_jobswithout an Upwork connection,research_company, etc.) come back with 0 results even though outbound internet works. Configure a Brave (BRAVE_API_KEYenv) or Tavily key and setweb_search_providerto it — Brave also suppliespublished_date, which the Upwork fallback maps ontopublished.MSYS path gotcha:
docker exec <ctr> php /tmp/probe.phpmangles/tmp/...into a Windows path unless prefixed withMSYS_NO_PATHCONV=1. CLIphpinside the WP container also defaults to 128M — usephp -d memory_limit=512Mwhen bootstrapping WordPress with Elementor.
MCP Transports & Client Compatibility
The /wp-json/mcp-ai/v1/mcp endpoint supports two transports, chosen by
the request shape:
| Transport | How it connects | Response channel |
|---|---|---|
| Streamable HTTP (default) | POST /mcp JSON-RPC, Accept includes application/json |
JSON body on the POST response, HTTP 200/202 |
Legacy HTTP+SSE (v1.1.55+, flag WP_MCP_AI_LEGACY_SSE_ENABLED) |
GET /mcp with SSE-only Accept: text/event-stream (or ?stream=true) → event: endpoint with session_id; then POST /mcp?session_id=... |
POST returns 202; responses arrive on the GET stream as event: message frames |
Discriminator rule: Accept containing text/event-stream and not
application/json → legacy SSE handshake. Mixed Accept headers
(application/json, text/event-stream) always get JSON — that is deliberate,
because Zed, Cursor, LM Studio and mcp-remote all send the mixed header but
expect JSON responses.
Session model (legacy SSE): sessions are owned by the credential that
opened them (SHA-256 hash of the Authorization header); message POSTs with
a different credential get 404. Caps: 5 sessions/credential, 20 global,
30-min TTL (wp_mcp_ai_sse_session_ttl / wp_mcp_ai_sse_max_per_credential /
wp_mcp_ai_sse_max_total). Store: WP_MCP_AI_SSE_Session_Store
(includes/rest/class-wp-mcp-ai-sse-session-store.php).
GET /sse is NOT a message channel — it streams the assistant directory
(event: directory). Legacy SSE clients cannot complete a session there.
GET /no-sse returns the directory as JSON.
Client compatibility quick reference
| Client | What works |
|---|---|
| Zed / Cursor / LM Studio / new SDKs | Native Streamable HTTP (url = /mcp) |
| Python MCP SDK | streamable_http_client(url, headers=...) works; sse_client(url) requires v1.1.55+ for the handshake |
npx nvoos-mcp-bridge (v1.1.96+) |
The first-party package — npx -y @nvdigitalsolutions/nvoos-mcp-bridge nvoos-mcp <url> --token <cred> relays stdio ↔ Streamable HTTP for Zed / Claude Desktop / Cursor / Codex; nvoos-mcp-ssh adds the SSH port-forward for no-public-route sites (byte-identical to bin/mcp-bridge*.js via CI) |
| mcp-remote bridge (Claude Desktop, older agents) | npx -y mcp-remote@latest <url> --header "Authorization: Bearer <token>" — connects via Streamable HTTP, needs Node 24+ |
| Cloudways Agent 0.19.0 / Codex-style agents | A bare url: is treated as SSE transport — use the npx bridge package or the mcp-remote stdio bridge, or point at the /mcp endpoint on v1.1.55+ |
mcp-remote stdio bridge pattern (verified)
For agents whose MCP client only speaks legacy SSE over a configured URL
(Cloudways Agent, Claude Desktop). On v1.1.96+ sites, prefer the first-party
npx -y @nvdigitalsolutions/nvoos-mcp-bridge nvoos-mcp <url> --token <cred>
package — same stdio relay, zero third-party dependency, byte-synced from
this repo's bin/:
mcp_servers:
nv-oos-sophie-agent:
command: npx
args:
- "-y"
- "mcp-remote@latest"
- "https://<site>/wp-json/mcp-ai/v1/mcp"
- "--header"
- "Authorization: Bearer cred_xxxxx.SECRET"
enabled: true
mcp-remote auto-detects the transport (http-first strategy) and exposes the
remote tools over local stdio. Note: mcp-remote opens a GET SSE stream
for server-initiated messages and retries it on failure — on pre-1.1.55
servers that GET hits the request rate limiter, and the retry loop can burn
the whole hourly quota (see Rate Limiting below).
SSH-only sites — nvoos-mcp-ssh / bin/mcp-bridge-ssh.js (Zed stdio over SSH)
For sites with no public web route (SSH is the only way in), use the
repo's own bridge, which owns the SSH port-forward and delegates to
bin/mcp-bridge.js (newline-delimited stdio ↔ Streamable HTTP relay). No
manual tunnel, no mcp-remote, no npm dependencies — Zed spawns it as a stdio
context server. Since v1.1.96 the same bridge ships as an npm package:
npx -y @nvdigitalsolutions/nvoos-mcp-bridge nvoos-mcp-ssh (identical env
vars below, byte-synced from bin/); the Fleet Operator addon's
generate_zed_json() emits the ready-to-paste context_servers block.
Prerequisite: SSH key auth (ssh <user>@<host> -p <port> must succeed
non-interactively). Password prompts are impossible for a spawned process
with no TTY.
Zed context_servers entry (Settings → AI → MCP Servers → Add Local Server):
{
"command": "node",
"args": ["bin/mcp-bridge-ssh.js"],
"env": {
"MCP_AI_SSH_USER": "user",
"MCP_AI_SSH_HOST": "203.0.113.10",
"MCP_AI_SSH_PORT": "2222",
"MCP_AI_SSH_REMOTE_PORT": "80",
"MCP_AI_TOKEN": "op_xxxx.SECRET"
}
}
Key env vars: MCP_AI_SSH_REMOTE_HOST/MCP_AI_SSH_REMOTE_PORT (web server
from the server's perspective; probe with curl over SSH — Cloudways Apache
may sit on 8080), MCP_AI_HOST_HEADER (canonical host override when the
web server 301-redirects on Host), MCP_AI_SSH_EXTRA_ARGS (e.g.
"-i C:/keys/id_ed25519 -o ProxyJump=bastion"), MCP_AI_ENV_FILE (default
~/.nvoos-bridge.env — keep the token out of settings.json).
Operator-credential audience binding is checked against home_url() from
the database, not the request Host header, so http://127.0.0.1:<port>
requests through the tunnel validate normally.
Orphan-proofing: the bridge holds ssh's stdin open so a hard-killed bridge
closes the pipe and ssh exits — no stray tunnels. Tests:
node bin/test-mcp-bridge-ssh.js.
For driving a Hermes Agent (Nous Research) itself rather than the NV oOS
console — its WebUI API over public HTTPS — see bin/hermes-mcp-server.js
(tools: hermes_chat, hermes_list_sessions, hermes_session_detail,
hermes_sync_skills; runbook: docs/operations/fleet/hermes-operator-setup.md
§7). The server also auto-syncs .agents/skills/ to the agent on startup
(HERMES_SYNC_SKILLS_ON_START=1, default); the standalone CLI
bin/sync-skills-to-hermes.js does the same from cron or a git post-merge hook.
Verifying a bridge from inside a Zed session: once any of these bridges
is connected, the remote tools appear as plain functions in the session tool
list (never under the server name), and list_agents_and_models will NOT
list the NV oOS assistant — detect enablement by tool-surface signature plus
a live probe, and re-probe rather than trusting earlier checks. See
design-ai-assistant-admin → "Detecting NV oOS agent enablement from a
coding-agent session (Zed)".
Rate Limiting & Agent Traffic
Two independent limiters apply to MCP traffic:
- General request limiter —
rate_limit_requestsperrate_limit_windowseconds per user/IP (oOS → Security → Network & Headers). GET/HEAD requests are exempt since v1.1.55 (discovery/SSE probes must not consume the budget aimed at state-changing traffic). For AI-agent workloads setrate_limit_requeststo 1000 — the default 300 is for chat usage, and client retry loops burn requests fast. - Tool execution limiter — v1.1.55+ settings under oOS → Security →
Tool Rate Limiting:
tool_rate_limit_max(default 300, 0 = unlimited),tool_rate_limit_window(default 60s),tool_rate_limit_exempt_tokens(default on — credential-token/agent traffic is exempt because an assistant credential is already an explicit grant of its tool set). Pre-1.1.55 this was a hardcoded 60 calls/60s with no UI — agents burst through it routinely. - Nefarious usage monitor — a third counter, deliberately namespaced
(
wp_mcp_ai_nefarious_rate_limit_transient) away from the chat REST limiter (wp_mcp_ai_rate_limit_): a shared counter would halve the configured chat budget and entangle the two enforcement paths. Rate-limit classification uses the dispatching request's real HTTP verb (internal dispatches likerest_do_request/WP-CLI are classified correctly instead of by the ambient request); GET/HEAD stay exempt. Custom emitters ofwp_mcp_ai_before_chat_requestmay fire the legacy 2-arg( $messages, $request_data )shape — core subscribers tolerate both it and the canonical( $assistant_id, $messages, $options, $request ).
Symptom of a tripped tool limiter on pre-1.1.55 servers: tools/call
returns HTTP 500 with a -32603 "Tool rate limit exceeded" error body —
which mcp-remote-style SDKs silently drop, so the agent sees no response
at all. With v1.1.55+ the same condition returns a visible JSON-RPC error
(and is unlikely to trip for agent tokens).
Restricted Users & Chat Rate Limits (v1.1.60+)
The plugin converts ephemeral rate-limit and token-budget blocks into
persistent restriction records (WP_MCP_AI_Restriction_Registry) so
admins can review, lift, or add them.
- Chat rate limit — the hardcoded 60 req/min chat cap is now filterable:
wp_mcp_ai_chat_rate_limitandwp_mcp_ai_chat_rate_limit_window(WordPress bridge →ChatOrchestrator::setChatRateLimit()). - Enforcement hooks —
wp_mcp_ai_tool_token_limit_exceeded,wp_mcp_ai_per_session_limit_exceeded, and the newwp_mcp_ai_rate_limit_exceeded(fired by the OOSRateLimiteradapter) feed the registry; records auto-expire on a daily cleanup cron and are audit-logged. - Admin surfaces — Token Manager "Restricted Users" panel (Base) with
one-click lift; Pro Command Center Restrictions tab (KPI cards, live
table, lift actions); dismissible notices toggled from Settings →
Orchestration → Restriction Notifications (
enable_restriction_admin_notices). - WP-CLI —
wp mcp-ai restrictions list|lift|add. - REST —
GET /mcp-ai/v1/restrictions,GET|POST /mcp-ai/v1/users/{id}/restrictions,DELETE /mcp-ai/v1/users/{id}/restrictions/{type}; rate-limited responses carry IETF headers (RateLimit-Policy,RateLimit,Retry-After). - Full reference:
docs/features/security/user-restrictions.md.
Conversation Import (v1.1.60+, JetEngine)
Import external AI conversation exports into the JetEngine
ai_chat_transcripts CCT (one row per conversation):
- Formats — ChatGPT
conversations.json(incl. ZIP), Google Takeout Gemini activity, Claudeconversations.jsonl, ShareGPT, OpenAI fine-tuning JSONL. - Tools —
conversation_import_detect|run|status|delete(requiremanage_options; JetEngine must be active). - WP-CLI —
wp mcp-ai conversation-import detect|import|status|delete(--dry-run,--policy=skip|refresh,--resume-token=). - Admin — upload/preview page with progress reporting; GDPR
export/erase + retention coverage; optional memory mining via
mine_agent_memory. Guide:docs/user-guides/conversation-import.md.
Agent Identity Bridging & OKF Bundle (v1.1.61+)
- Agent identity bridging —
store_agent_contextresolves virtual agent keys (e.g.nvoos-pro-spa-memory-drawer) to the canonical assistant post ID (WP_MCP_AI_Agent_Identity_Resolver, alias map in thewp_mcp_ai_agent_id_aliasesoption); the envelope echoesoriginal_agent_id/agent_id_resolved. Chat-memory recall merges alias buckets (stored_underper record) and the memory drawers show scope/stored-under chips, the agent ID, and a show-all-scopes toggle. OKF bundle. Theskill-knowledgebundle is auto-generated from bundled skills on bootstrap (and after bundled-skill reinstall), sookf_searchworks out of the box (no more "OKF bundle not found").
OKF Bundle Management & Pro Knowledge Routing (v1.1.62+)
- Bundle Manager (Base) —
WP_MCP_AI_OKF_Bundle_Managerowns the OKF bundle lifecycle: create/list/rename/archive/delete, ZipSlip-safe ZIP import/export, health stats, log maintenance;skill-knowledgeis protected from tool writes (okf_protected_bundle— curated knowledge belongs insite-knowledge). Admin screen under Assistants:edit.php?post_type=mcp_ai_assistant&page=wp-mcp-ai-okf-bundle-manager(Bundles/Browser/Editor/Import-Export/Validate;manage_options). - Tools — three new base tools (
okf_list_bundles,okf_validate_bundle,okf_import_bundle) plus theokf_write_conceptprovenance schema (resource/sources/usage_window/verified) — OKF tool surface: 10. Two new Pro tools:okf_enrich_site_content(manage_options) androute_knowledge_query(read). - Pro knowledge routing —
load_skillresolvesbundle:concept_idnames (OKF-to-Skill Bridge, per-assistant grants + trust gating); the enrichment agent crawls site content into OKF concepts; the hybrid knowledge router classifies queries across OKF / vector / Paper stores. - Pro SPA v2 drawer — in-chat OKF Skills Drawer backed by the read-only
mcp-ai-pro/v1/okfREST surface (bundles, concept browse/search, assistant skill grants);%2F-encoded concept IDs decode correctly. - Vector stores — all vector-store tools now run on the Responses API
(no
OpenAI-Beta: assistants=v2header;file_batchesingestion with bounded polling + fallback) ahead of the 2026-08-26 Assistants API removal. - Guide:
docs/features/okf-integration.md; roadmap:docs/project/plans/OKF-BUNDLE-MANAGEMENT-IMPLEMENTATION-PLAN.md.
Artifact Evolution, Addons Page & Storage Worker (v1.1.63+)
- Artifact evolution Phases A–G (Base + Pro) — the Continual Harness
Evolver + Meta-Harness are now a gated Darwinian self-improvement loop for
skills, prompts, and roles (
includes/harness/class-wp-mcp-ai-artifact-*.php): populations + parent sampling, failure replay + post-mutation verification, pre-commit admission gate, holdout-gated deployment with shadow A/B + drift rollback, governor + human approval queue + lineage. Every layer defaults off; the opt-in switches live in Settings → Orchestration Layer (WP_MCP_AI_Evolution_Settings_Bridge). Theevolve_harnesstool now calls the repaired Evolver contract (analyze_failures(), component-scopedevolve(), enforceddry_run). Proposal:docs/project/proposals/007-artifact-evolution.md. - Pro Addons page (v1.1.63+) — NV oOS Pro Dashboard → Addons
(
/wp-admin/admin.php?page=wp-mcp-ai-addons) installs/activates standalone addons whose ZIPs ship inbuild/; nonce +install_plugins+ allowlist; non-WordPress components listed read-only. - Chat storage worker offload — saves ≥
wp_mcp_ai_storage_worker_threshold(default 10,000 chars) offloadJSON.stringifyto the browserstorage-worker.js; sync fallback for small saves/unload/worker failure; kill switch:add_filter( 'wp_mcp_ai_storage_worker_threshold', '__return_zero' );. Plan:docs/project/proposals/032-chat-web-workers-wiring-implementation-plan.md. - DeepSeek empty-schema fix — tool schema
propertiesmust encode as{}never[]; legacy tools are wrapped before the first register attempt.
Reasoning Models, Full-Crawl Proxy & Security-Posture Closure (v1.1.65+)
- OpenAI reasoning-model parameters — o-series and gpt-5 models reject
max_tokens(o-series alsotemperature);lib/coreOpenAiCompatibleClientstrips unsupported parameters per model (applyModelConstraints()) and retries 400 rejections with corrected payloads (sendWithParameterCorrection()) on sync and streaming paths. Do not blanket-addmax_tokensfor reasoning models. - Media Worker full-Crawl4AI proxy (031 Phase 3) — env-gated
POST /api/crawl/full+GET /api/crawl/full/task/:idforward toCRAWL4AI_FULL_URLwith SSRF-validated targets, token gating, and 503/502/400 envelopes;TEMP_ROOTis the strict-path sandbox root (028 Q5). Worker version stays v3.2.0 —package.jsonis authoritative. - Security-posture closure (issue #5972) — Algorave Tone.js raw eval
requires per-session confirmation + warning banner; TMA source map
removed; webhook
__return_truecallbacks carry justification comments. - Chat/REST hardening — legacy top-level
attachmentsparameters tolerated; custom message roles work viawp_mcp_ai_allowed_message_roles; orphaned tool messages silently discarded; sign-preserving transcript pagination; legacyinput_textsegments normalized totext. - TPM fallback — token-budget service falls back to the bundled model catalog when the rate-limits CCT has no entry (TPM limits work without JetEngine).
- Slash commands & blocks — toolkit manager re-resolves the handler on
registration; CSV list args accept
"1,2"and"1, 2"; assistant-builder and Pro toolkit blocks register idempotently (WP 7.1 notices).
Release Notes (per version)
Historical per-version release notes (v1.1.66 through v1.1.96) moved to RELEASE-NOTES.md to keep SKILL.md under the Zed 100KB skill-size limit. Append new version sections there, not here.
v1.2.7 operational quick notes (full detail in RELEASE-NOTES.md):
F&B universalisation + open-format ingestion (PRs #7094–#7096, Proposal
078) — the F&B toolkit goes multi-tenant: WP_MCP_AI_Fnb_Tenant_Profile
de-couples currency (neutral keys + legacy *_lkr aliases), render()
de-venues both assistant surfaces, a universal single-folder ingestor scores
Drive files to table roles, and fnb_export_report (+1 Pro) exports CSV/PDF.
Sinhala TTS (PR #7099) — generate_sinhala_speech (+1 base) routes via
SpeechGen si-LK / Hugging Face MMS / custom webhook. Pro SPA expansion
(PRs #7078–#7080) — #/docs / #/media / #/documents iframes; headless
credential auth (#7085) + keep-alive tabs (#7075) + surface fix (#7076).
Schema hardening (PRs #7087/#7100/#7104) — boolean required hoisting +
empty properties as {}. Google Workspace (PRs #7097/#7101/#7105) —
unified credential resolution + native Sheets reads. F&B reliability (PRs
#7091/#7092/#7102/#7103); team-member slug resolution (#7088).
Dependency (PR #7074) — gateway SDK → 1.31.0. Skills — coding-time
73 → 74 (-universalisation, -ingestion); bundled 76 → 77 (+dictation-app).
Tool count +1 base +1 Pro → 355 base + ~1,377 Pro (1,731 total); 12
security classes; 18 providers; 30 addons (all unchanged).
v1.2.6 operational quick notes (full detail in RELEASE-NOTES.md):
Google Drive OAuth restored (PR #7053) — drive.readonly restored
alongside drive.file behind wp_mcp_ai_google_drive_oauth_scope (the
#6981 per-file narrowing broke search_drive/get_drive_file + the F&B
tools for pre-existing content). F&B reader reliability (PRs #7057/#7060/
#7061/#7062) — Sheets-API-v4 multi-worksheet reads, a DEMO_WORKBOOK_ID
fallback, the spreadsheets.readonly OAuth scope + actionable Sheets-scope
errors, a CSV exporter, and 18 shipped demo tables. OCR vLLM (PR #7055)
— the self-hosted client now speaks the vLLM contract (extra_body.vllm_xargs),
base + CG Pro mirror byte-identical. Drive fixes (PR #7051) — the
inline-async-tick trait double-declare fatal, response-body logging, and
folder_id clearing. Dictation + SPA (PRs #7041/#7043–#7050/#7063/#7066/
#7072) — a CDP browser agent, FastConformer, the polish gate, the
spa-surfaces endpoint + the drawer-401 credential fix — no plugin registry
surface. Dependency (PR #7059) — shell-quote → 1.12.0. Tool count
unchanged: 354 base + ~1,376 Pro (1,730 total); 12 security classes; 18
providers; 30 addons (all unchanged).
v1.2.5 operational quick notes (full detail in RELEASE-NOTES.md):
GTmetrix × WPCode performance toolkit (PR #7026, Proposal 068) — the
enable_gtmetrix_toolkit Pro module registers 23 gtmetrix_* tools plus
the read-only list_wpcode_snippets (a shared
WP_MCP_AI_Pro_WPCode_Snippet_Repository extracted from
create_wpcode_snippet); gtmetrix_install_wpcode_fix is drafts-only +
chat-restricted; wp mcp-ai pro gtmetrix seed-assistant. Food & Beverage
Phase 9 (PR #7032) — five transactional-table CPTs behind
enable_fnb_native_storage, the `fnb_import_table
…(truncated)