Repository navigation
Architecture
This page traces one MCP request through the plugin, then describes the layer boundaries and where data lives. It summarizes docs/en/architecture/overview.md, docs/en/architecture/persistence.md and the source under src/.
| Item | Value | Source |
|---|---|---|
| PHP namespace / PSR-4 root |
XNetVN\AgentHubWP / src/
|
composer.json, docs/en/architecture/overview.md
|
| Plugin slug, text domain, server ID | xnetvn-agent-hub-wp |
xnetvn-agent-hub-wp.php, src/Mcp/ServerGateway.php
|
| Ability namespace | xnetvn/ |
docs/en/architecture/overview.md |
| Function, hook and option prefix | xnetvn_agent_hub_wp_ |
docs/en/architecture/overview.md |
| MCP route | /xnetvn-agent-hub-wp/mcp |
src/Http/RouteMatcher.php |
| Management route namespace | xnetvn-agent-hub-wp/v1 |
src/Rest/ManagementGate.php |
Client (bearer key)
│ HTTPS POST /wp-json/xnetvn-agent-hub-wp/mcp
▼
[1] RouteMatcher ── exact, normalized route only
▼
[2] OriginGuard / TransportGuard ── deny before auth
▼
[3] Authenticator ── bearer key → AuthContext (never cookie identity)
▼
[4] Policy + scope recheck ── capability ∩ key ∩ site ∩ toolset
▼
[5] ServerGateway ── the only adapter-aware class
▼
[6] Registry ── private ability definition, rechecked at invoke
▼
[7] OutputPipeline ── validate, redact, bound, revalidate
▼
[8] AuditLogger ── one bounded INSERT at shutdown (names only)
-
Exact route matching.
RouteMatcher::matches()accepts only a real REST request whose normalized route equals/xnetvn-agent-hub-wp/mcpafter trimming trailing slashes. No namespace-prefix match is allowed, so a neighbouring route never inherits bearer authentication (src/Http/RouteMatcher.php). -
Guards before authentication. Origin and TLS checks run at REST authentication priority 5 and deny unsafe requests before any credential is read. A missing
Originis permitted for non-browser clients; an explicitnullor an unlisted origin is denied (docs/en/architecture/overview.md). -
Authentication.
Authenticatorreads only the credential header, verifies the HMAC-SHA256 secret against the per-site pepper, then rechecks revocation, expiry, owner existence, the owner's currentuse_xnetvn_agent_hub_wpcapability, key and site IP allowlists, site enablement and TLS. Only then does it create a request-localAuthContextand charge the per-key budget. A cached cookie user is reauthenticated at REST priority 80; a prior cookie identity never substitutes for a key (src/Auth/Authenticator.php). -
Policy.
Policy::evaluate()returns the first failing term: transport/identity, site enabled, site tier ceiling, admin-tier opt-in, key tier, toolset, explicit allow/deny, third-party approval, then the live WordPress capability for the ability's visibility capability, then an extension filter that may only deny (src/Policy/Policy.php). -
Gateway.
ServerGatewayregisters five adapter hooks and filters the advertised tool list to the names the presented scope can use, but only on the exact MCP route (src/Mcp/ServerGateway.php). -
Registry.
Registryis the authority for ability metadata. It rejects duplicate ability or tool identities, loads packs oninitpriority 0, and registers categories and abilities through the WordPress Abilities API.allowed()rechecks the bound ability object and current policy;invoke()rechecks again, applies the per-key expensive-work budget, then runs the output pipeline (src/Abilities/Registry.php). -
Output.
OutputPipeline::process()validates against the declared schema, removes sensitive property names recursively, validates again, enforcesoutput_max_bytes(default 262144), and truncates only when the schema declares atruncatedproperty. If no valid bounded result exists, the tool fails with a safe execution error instead of returning invalid structured content (src/Abilities/OutputPipeline.php). -
Audit.
AuditLoggerbuffers metadata and writes one bounded INSERT at shutdown. It stores time, request ID, key ID, user ID, transport, protocol version, MCP method, ability, outcome, error code, duration, IP, short user agent and top-level argument names — never argument values, credentials, headers or hashes (src/Audit/AuditLogger.php,docs/en/adr/0010-minimal-audit.md).
Only src/Mcp/ServerGateway.php references adapter symbols (mcp_adapter_*, WP_MCP_VERSION); a repository-wide search of src/ returns that file alone. Packs, policy, authentication, persistence, REST and admin code never import adapter APIs, so an adapter upgrade is contained in one facade (docs/en/architecture/adapter-notes.md, docs/en/specs/M1-core.md).
Ability registration declares no public or show_in_rest metadata: abilities stay private, and core may inject show_in_rest=false, which must remain false. Unsupported adapter versions leave the plugin loadable while MCP boot stays closed (src/Bootstrap/Requirements.php).
The entry file uses PHP 7.2-compatible syntax only, loads Requirements, Notice and Loader, and calls Loader::run(). The loader fails closed: if PHP, WordPress, the Abilities API or vendor/autoload.php is missing, it registers an admin notice and never loads modern code. Otherwise it boots Plugin, which registers an ordered list of ServiceProvider implementations once and dispatches xnetvn_agent_hub_wp_loaded (xnetvn-agent-hub-wp.php, src/Bootstrap/Loader.php, src/Plugin.php).
| Layer | Responsibility | Examples |
|---|---|---|
| Admin / REST / CLI | Input handling and UI |
src/Admin/Pages.php, src/Rest/*Controller.php
|
| Services | Orchestration and rules |
KeyService, Registry, Policy
|
| Domain | Pure value objects, no WordPress calls |
RiskTier, Scope, AuthContext
|
| Persistence / rate limit | Contract implementations |
WpdbKeyRepository, WpBucketStore
|
| Packs | Ability definitions and handlers | src/Abilities/Packs/* |
| Store | Name | Purpose |
|---|---|---|
| Table | {prefix}xnetvn_agent_hub_wp_keys |
Key metadata, HMAC hash, pepper ID, scope, usage, revocation |
| Table | {prefix}xnetvn_agent_hub_wp_audit |
Audit rows, indexed by time, key, user and ability |
| Option | xnetvn_agent_hub_wp_settings |
Validated, non-autoloaded site policy |
| Option | xnetvn_agent_hub_wp_pepper |
Separate random pepper, non-autoloaded |
| Option | xnetvn_agent_hub_wp_db_version |
Forward-only schema version |
| Options | Rate buckets | Non-autoloaded counters when no persistent object cache exists |
Both tables are created per site by Schema::statements(); the schema version is forward-only and a future version is refused (src/Persistence/Schema.php, docs/en/architecture/persistence.md). See Operations for backup implications and Security-Model for the trust boundaries.
xnetvn_agent_hub_wp_loaded hands the registered kernel to extensions. Deny-only filters (..._taxonomy_allowed, ..._user_allowed), add-only filters (..._user_privileged_caps, ..._user_meta_writable) and the extra policy filter preserve the base intersection and can never widen it. Tier filters may only raise risk (docs/en/architecture/overview.md).
Nothing here proves runtime acceptance. Implemented primitives and measured acceptance are recorded separately in docs/en/TESTING.md; see Testing.
xNetVN Agent Hub WP · GPL-2.0-or-later · Copyright (c) 2026 xNetVN Inc.
This wiki summarizes the repository documentation. The source of truth is the repository; when they disagree, the repository wins.
Start here
Using the plugin
Security
Engineering
Project