Agentimus MCP Server

Agentimus

Two things for the age of AI agents. (1) Make any WordPress site legible and citable — llms.txt, a full-text edition, markdown delivery, JSON-LD, content-signal robots rules — then score how AEO/GEO-ready it is and what to fix next. (2) Let the AI tools you already use operate the site over MCP: a Model Context Protocol server ships inside the plugin, so Claude Code, Claude Desktop, Cursor or Codex can read your readiness/traffic/bot data and — behind two more opt-in switches — draft, edit and publish posts and pages, each write running as the signed-in user, permission-checked and audited. Lightweight, no SEO bloat, no framework.

Live on WordPress.org: https://wordpress.org/plugins/agentimus/

📖 Documentation: https://heera.github.io/agentimus/ — full user manual and developer reference.

Install

• From your dashboard — Plugins → Add New → search "Agentimus" → Install → Activate.
• From WordPress.org — https://wordpress.org/plugins/agentimus/.
• From source — clone this repo, run npm install && npm run build (produces assets/admin/), then copy or symlink the folder into wp-content/plugins/.

What it does

In the admin

• AEO/GEO score — one 0–100 score on the dashboard across five rungs (Findable / Readable / Trusted / Optimized / Cited), with the single most useful next step; each rung deep-links to where you act on it. Cited is opt-in (see AI Visibility) and its weight redistributes across the others when off.
• Optimize your content — per-page citability checks (thin content, something concrete to quote, quotable passages, freshness) over your articles, with a worklist of which pages to improve and a matching read-only panel in the editor. Commerce products, commerce plugins' designated pages (cart/checkout/account — WooCommerce options and FluentCart settings both read), and shortcode/block container pages with no authored prose are excluded; set aside any page not meant to be cited (it stays published, just leaves the score); mark categories evergreen to exempt timeless content from the freshness check.
• Readiness report — pass/warn/fail checks, each with a plain-English suggestion and a deep link to the fix (including a "sitemap advertised in robots.txt" check).
• Agent preview — a modal (from Readiness) showing the exact JSON-LD and Markdown an agent receives for the site or any page/post, with a grouped site/page/post picker, copy, and validator links. It renders what would ship even when schema is disabled or an SEO plugin owns it; password-protected posts stay hidden, and an unpublished draft is shown as a preview of what it will emit once published. A read-only twin also sits in the post editor.
• AI Visibility (opt-in, bring-your-own-key — the Track AI citations switch in Settings; adds the Cited rung to your score, and a reading expires after 90 days so a stale one never counts) — track each brand, product or person you choose across ChatGPT, Perplexity, Gemini and Claude. For every one it asks the questions your audience types and reports whether it's mentioned, linked, and how it ranks against its own rivals, over time. Give an item a category ("WordPress SEO plugin") and Agentimus suggests the questions a buyer actually types — or, where an AI provider is configured in WordPress, asks that AI for a spread of unbranded buyer questions (POST /visibility/suggest and /visibility/suggest-ai). Each item has its own website, category, competitors, questions and scoreboard; pause any single one or the whole schedule, and every setting on the screen saves itself. Results are stored locally; it's the only feature that makes outbound calls — using API keys you provide (stored encrypted at rest), off by default. It keeps its own keys rather than reusing WordPress's shared AI connectors, because a visibility check is graded on the sources an engine cited and the shared client drops them.
• Agent activity log — a local-only dashboard (no IP logged by default; an optional setting stores IPs for flagged crawlers only) of which AI agents and crawlers fetch your endpoints; repeat hits are grouped with a count, newest first. Click any day's bar for that day's full report — clients, endpoints, and every request. Your own logged-in visits are skipped, and so are the readiness screen's own Verify-live/exposure-scan fetches (they carry a short-lived X-Agentimus-Selfcheck token, since they're deliberately anonymous).
• Request Log (More → Request Log) — the raw log behind that dashboard: one row per request, keyset-paged, filterable by client, endpoint, network, user-agent and date range. The filters AND together, giving the agent × endpoint cross-tab the summary rollups structurally cannot show.
• Agent Access (More → Agent Access) — the other side of the log: who authenticates to and acts on the machine surface Agentimus creates. Records application passwords being created/first-used/renamed/revoked, WordPress abilities being run, and requests that were refused or probed for abilities that don't exist — and every row says who: the user and the named application password behind it, resolved live (a renamed key shows its current label, a revoked one reads "since revoked"). A record, not a guard (it never blocks); no IP logged, so it names the credential, not the person. Rides rest_request_after_callbacks and the app-password hooks; the credential half needs no Abilities API, the ability half auto-detects it.
• Traffic from AI — a private, first-party count of which AI assistants send visitors to you (per-day tallies of assistant → landing page; no IP, no per-visitor data). The dashboard shows a summary — click any day's bar for that day's assistant → landing-page report; More → AI Traffic is the full report, with the same per-day drill-down. An opt-in CDN mode counts these in the browser so the numbers survive a full-page cache. Because recognition is a finite list, an opt-in Find missed AI sources diagnostic records the referrer hosts and utm_source tags it couldn't attribute — the only way to see a blind spot that otherwise leaves no trace.
• Visit-log retention (Settings → Visit log) — a retention period, nightly auto-delete, and a hard row cap. The cap outranks the retention: "keep for 90 days" is a ceiling on age, not a promise a row survives 90 days. Turning auto-delete off does not mean "keep forever" — the cap still collects, oldest first.
• Keep AI endpoints out of your cache (Settings → Caching & CDN, opt-in) — if a cache or CDN in front of your site serves stored copies of the AI endpoints (llms.txt, the .well-known docs, the change feed), those agent fetches never reach WordPress: the log under-counts them and the change feed can go stale. Turn this on and the endpoints send Cache-Control: no-store, so any cache that respects it lets each fetch through. The readiness report links to it when it detects a cache in front of you.
• Refresh AI files when content changes (Settings → Caching & CDN, on by default) — on every content change, asks each detected page cache (WP Rocket, Nginx Helper, W3 Total Cache, LiteSpeed, WP Super Cache, Cache Enabler, or any agentimus_purge_url listener) to drop the AI files — llms.txt, llms-full.txt, robots.txt, the change feed, the .well-known docs — plus the edited post's own .md twin, which a cache plugin otherwise never knows to refresh. Feature-detected, so it's a no-op with no cache present.
• Activity to review — a nav-bar review queue flags new, unusually high-volume, spoofed/scanner, or impersonating clients (one that claims a bot from the editable Verified-bots registry — Googlebot, GPTBot, PerplexityBot, … — but conclusively fails that operator's published check: reverse DNS or its published IP ranges), each with a plain "Check this bot" panel and one-click Block / Allow / Ignore. Pairs with the opt-in Block scanners & scrapers enforcement; an optional Store IP addresses for flagged clients setting shows the exact address to block. Every standing decision — blocked, trusted, ignored — is managed later under Settings → AI access → Manage clients: identity, decision date, and one-click undo per row.
• Exposure — opt-in controls that limit what anonymous crawlers can read (username enumeration, author archives, the WP version, <head> links, XML-RPC), plus a one-click exposed-files scan that checks whether risky files (backups, .env, debug.log, keys) are publicly downloadable and tells you how to block them. Guidance, not a firewall.
• Factory reset — one click restores every setting to its recommended defaults, with a preview of exactly what will change.

Architecture

• PHP (inc/, namespace Agentimus\, PSR-4 autoloaded) — vanilla, no framework.
  • Plugin orchestrates; Settings is the single option store; Cache handles transients; Endpoints / Markdown / Schema produce output; Readiness runs the checks; Rest backs the admin; Admin mounts the UI.
• Admin UI — Vue 3 (Options API), built with Vite into assets/admin/. Talks to the REST namespace agentimus/v1 with the standard WP nonce.

Extending to any site / content type

The free core covers post + page and any public post type you opt in (Content types card, or the agentimus_post_types filter), so products and CPTs flow into llms.txt, the full-text edition, markdown and schema automatically. Deeper coverage (a WooCommerce Product mapper, page-builder content) is an add-on that hooks these seams:

• agentimus_post_types — add/remove agent-visible post types
• agentimus_schema_for_post — return a full node, e.g. Product with offers
• agentimus_markdown_source — supply rendered HTML for page-builder content

For developers — make your plugin discoverable

Agentimus exposes a single aggregated discovery layer at /.well-known/discovery.json (plus agent-card.json and mcp.json). Any plugin can register itself with one action and no dependency — if Agentimus is not installed, the hook never fires, so the code is inert:

add_action( 'wpdiscovery_register', function ( $registry ) {
    $registry->register( array(
        'id'           => 'acme-bookings',
        'title'        => 'Acme Bookings',
        'type'         => 'scheduling',                 // controlled vocab + x-vendor-name
        'capabilities' => array( 'scheduling.booking.create' ), // dot-notation INTENT
        'endpoints'    => array(                        // WHERE (concrete paths live here)
            array( 'url' => '/wp-json/acme/v1', 'type' => 'rest', 'auth' => 'apikey' ),
        ),
        'auth'         => array( 'type' => 'apikey', 'docs' => 'https://acme.dev/api' ),
        'agent'        => array( 'name' => 'Acme Agent', 'skills' => array(
            array( 'id' => 'create_booking', 'description' => 'Book an appointment.' ),
        ) ),
    ) );
} );

A global facade is also available (guard it, since the call is direct):

if ( class_exists( 'Agentimus_Discovery' ) ) {
    Agentimus_Discovery::register( [...] );
}

Resource fields: id (req, slug), title (req), type (req — content, commerce, scheduling, courses, forms, crm, auth, search, media, messaging, analytics, payments, directory, agent, or x-vendor-name), description, version, capabilities[], endpoints[] ({url, type, methods[], auth, description}), schemas[], auth ({type, oidc, scopes[], docs}), agent ({name, description, skills[{id,description}], endpoint, auth}), abilities[], tools[] (MCP-shaped), docs. provider is auto-filled — don't set it.

Capabilities describe intent; the concrete /wp-json/... paths live only in endpoints/tools. Invalid entries are rejected and surfaced (with the reason) in Discovery Hub → Validation.

$registry->add_well_known( [...] ) serves a /.well-known/<name> doc (callback | redirect | file). See examples/integrate-your-plugin.php for the full copy-paste reference, and the WP_Discovery Protocol spec for the standard.

Hooks & filters

Every hook is optional and falls into one of three tiers. The tables give each hook's type (action or filter) and callback signature (parameters → return); copy-paste examples are in examples/all-hooks-reference.php. In signatures, Registry, Settings and Plugin are the Agentimus\Discovery\Registry, Agentimus\Settings and Agentimus\Plugin classes.

Stable

Public and frozen at WP_Discovery spec 1.0 — safe to build on.

// Add selectable schema.org entity types to Settings → Identity.
add_filter( 'agentimus_entity_types', function ( $types ) {
    $types[] = 'Restaurant';
    return $types;
} );

Extension

Supported output-shaping filters; signatures may evolve between releases.

// Add a vendor extension to the discovery document (the x- namespace is yours).
add_filter( 'agentimus_envelope', function ( $envelope, $registry ) {
    $envelope['x-acme'] = array( 'portal' => 'https://acme.example' );
    return $envelope;
}, 10, 2 );

Internal

Advanced site-owner tuning — not a third-party integration surface.

// The Guard's final say on whether to 403 a request.
add_filter( 'agentimus_deny_request', function ( $deny, $ua ) {
    return $deny;
}, 10, 2 );

Development

npm install
npm run build      # one-off build into assets/admin/
npm run dev        # rebuild on change

assets/admin/ is git-ignored — it's a build artifact. Ship it in the distributed .zip (the .org SVN tag), not the repo.

Requirements

• WordPress 6.9+ (tested up to 7.0)
• PHP 7.4+.

License

GPL-2.0-or-later. The admin app is built from Vue source in resources/ with Vite — no minified-only code ships, so the build is reproducible.