# MCP AI Wpoos Plugin

> Complete operational guide for the NV oOS (Open Operator System) WordPress plugin in Docker/WSL2 — setup, assistant creation, credential tokens, MCP tool calling, API key auto-detection, env var bridging, common fixes, and IGCSE study configuration. Use when setting up the plugin for the first time, creating assistants programmatically, generating MCP bridge tokens, troubleshooting Docker path issues, bridging API keys, or calling tools via JSON-RPC over HTTP.

- Skill: `nvdigitalsolutions/mcp-ai-wpoos-plugin` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add nvdigitalsolutions/mcp-ai-wpoos-plugin`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvdigitalsolutions/mcp-ai-wpoos-plugin/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Proprietary. See LICENSE.txt
- Author: nvdigitalsolutions (https://skillmd.com/u/nvdigitalsolutions)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/nvdigitalsolutions/mcp-ai-wpoos-plugin

---

# 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` / `mkdir` PHP 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.SECRET` token 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 403 `wp_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-submission` skill 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-wpoos` in 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 guard `sa_platform_base_is_active()` →
  `wp_mcp_ai_core_loaded()` already detects all three flavors).
  `addons/page-agent` still 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
  upstream `Lonsdale201/wp-agent-skills` catalogue 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 upstream `wp-plugin-bootstrap` skill 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.

```bash
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-*` and `mcp-ai-wpoos-plugin` are
  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.
- `wp` inside 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/assistants` returns 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:

```bash
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_settings` array AND standalone `wp_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.php`
- `includes/paper-store/class-wp-mcp-ai-paper-store-manager.php`

If you still see warnings on older versions, pre-create the directories:

```bash
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
# 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"
```

```bash
# 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-*` and `mcp-ai-wpoos-plugin` use
> junctions pointing to `plugins/mcp-ai-wpoos/.agents/skills/`. The creation
> script is at `bin/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
<?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):

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

```php
$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

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

1. **Bearer token** (`cred_xxxxx.SECRET`) — recommended for MCP clients
2. **Raw credential** (`Authorization: cred_xxxxx.SECRET` without `Bearer `) —
   accepted since v1.1.55 for agent configs that forward the header verbatim
   (e.g. Cloudways Agent); disable via filter
   `wp_mcp_ai_accept_raw_credential_header`
3. **OAuth 2.0** (authorization_code grant) — browser-based MCP app flow
4. **Mesh Key** (`X-WP-MCP-AI-Mesh-Key` header) — mesh federation
5. **WordPress nonce** (`X-WP-Nonce` header + 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

```json
{
  "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

```json
{"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

```json
{
  "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.

```json
{
  "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 CLI `wp_create_nonce()`:

  ```php
  $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_tools` post meta. A tool not in that list returns
  `403 wp_mcp_ai_tool_forbidden` ("This assistant is not allowed to execute
  the requested tool"). Grant access with
  `update_post_meta( $assistant_id, '_wp_mcp_ai_tools', $tools_with_slug )`.
- **Gate 2 — availability:** `search_upwork_jobs` (and the other Upwork CRM
  tools) also need `enable_crm_toolkit` in `wp_mcp_ai_settings`.
- **DuckDuckGo returns no real SERPs.** The default `web_search_provider`
  (`duckduckgo`) hits the free Instant Answer API, which returns empty
  `RelatedTopics` for ordinary queries — so fallback-mode tools that
  depend on `web_search` (`search_upwork_jobs` without an Upwork
  connection, `research_company`, etc.) come back with **0 results** even
  though outbound internet works. Configure a Brave (`BRAVE_API_KEY` env)
  or Tavily key and set `web_search_provider` to it — Brave also supplies
  `published_date`, which the Upwork fallback maps onto `published`.
- **MSYS path gotcha:** `docker exec <ctr> php /tmp/probe.php` mangles
  `/tmp/...` into a Windows path unless prefixed with `MSYS_NO_PATHCONV=1`.
  CLI `php` inside the WP container also defaults to 128M — use
  `php -d memory_limit=512M` when 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/`:

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

```json
{
  "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:

1. **General request limiter** — `rate_limit_requests` per
   `rate_limit_window` seconds 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 set `rate_limit_requests` to 1000** — the default
   300 is for chat usage, and client retry loops burn requests fast.
2. **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.
3. **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 like `rest_do_request`/WP-CLI are classified
   correctly instead of by the ambient request); GET/HEAD stay exempt.
   Custom emitters of `wp_mcp_ai_before_chat_request` may 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_limit` and `wp_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 new
  `wp_mcp_ai_rate_limit_exceeded` (fired by the OOS `RateLimiter` adapter)
  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, Claude `conversations.jsonl`, ShareGPT, OpenAI
  fine-tuning JSONL.
- **Tools** — `conversation_import_detect|run|status|delete` (require
  `manage_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_context` resolves 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 the
  `wp_mcp_ai_agent_id_aliases` option); the envelope echoes
  `original_agent_id` / `agent_id_resolved`. Chat-memory recall merges alias
  buckets (`stored_under` per record) and the memory drawers show
  scope/stored-under chips, the agent ID, and a show-all-scopes toggle.
**OKF bundle.** The `skill-knowledge` bundle is auto-generated from
  bundled skills on bootstrap (and after bundled-skill reinstall), so
  `okf_search` works 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_Manager` owns the OKF
  bundle lifecycle: create/list/rename/archive/delete, ZipSlip-safe ZIP
  import/export, health stats, log maintenance; `skill-knowledge` is
  protected from tool writes (`okf_protected_bundle` — curated knowledge
  belongs in `site-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 the `okf_write_concept` provenance schema
  (`resource`/`sources`/`usage_window`/`verified`) — OKF tool surface: 10.
  Two new Pro tools: `okf_enrich_site_content` (`manage_options`) and
  `route_knowledge_query` (`read`).
- **Pro knowledge routing** — `load_skill` resolves `bundle:concept_id`
  names (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/okf` REST 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=v2` header; `file_batches` ingestion 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`). The `evolve_harness` tool now calls
  the repaired Evolver contract (`analyze_failures()`, component-scoped
  `evolve()`, enforced `dry_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 in `build/`; 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) offload `JSON.stringify` to the browser
  `storage-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 `properties` must 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 also `temperature`); `lib/core`
  `OpenAiCompatibleClient` strips unsupported parameters per model
  (`applyModelConstraints()`) and retries 400 rejections with corrected
  payloads (`sendWithParameterCorrection()`) on sync and streaming paths.
  Do not blanket-add `max_tokens` for reasoning models.
- **Media Worker full-Crawl4AI proxy (031 Phase 3)** — env-gated
  `POST /api/crawl/full` + `GET /api/crawl/full/task/:id` forward to
  `CRAWL4AI_FULL_URL` with SSRF-validated targets, token gating, and
  503/502/400 envelopes; `TEMP_ROOT` is the strict-path sandbox root
  (028 Q5). Worker version stays **v3.2.0** — `package.json` is
  authoritative.
- **Security-posture closure (issue #5972)** — Algorave Tone.js raw eval
  requires per-session confirmation + warning banner; TMA source map
  removed; webhook `__return_true` callbacks carry justification comments.
- **Chat/REST hardening** — legacy top-level `attachments` parameters
  tolerated; custom message roles work via
  `wp_mcp_ai_allowed_message_roles`; orphaned tool messages silently
  discarded; sign-preserving transcript pagination; legacy `input_text`
  segments normalized to `text`.
- **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](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)
