### Execute Ability via REST API

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Examples of executing abilities using different HTTP methods (GET, POST, DELETE) based on the ability's requirements and annotations.

```bash
curl https://example.com/wp-json/wp-abilities/v1/my-plugin/get-site-info/run
curl "https://example.com/wp-json/wp-abilities/v1/my-plugin/get-user-info/run?input=%7B%22user_id%22%3A1%7D"
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"input":{"option_name":"blogname","option_value":"New Site Name"}}' \
  https://example.com/wp-json/wp-abilities/v1/my-plugin/update-option/run
curl -X DELETE \
  "https://example.com/wp-json/wp-abilities/v1/my-plugin/delete-post/run?input=%7B%22post_id%22%3A123%7D"
```

--------------------------------

### Client Configuration for HTTP Transport (JSON)

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Configuration example for connecting AI clients using the HTTP transport via a remote proxy. This setup requires specifying the WordPress API URL, log file path, username, and an application password for authentication.

```json
{
  "mcpServers": {
    "wordpress-http-default": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "http://your-site.test/wp-json/mcp/mcp-adapter-default-server",
        "LOG_FILE": "/path/to/logs/mcp-adapter.log",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "your-application-password"
      }
    }
  }
}
```

--------------------------------

### Install WordPress MCP Adapter via Composer

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Use Composer to install the required WordPress Abilities API and the MCP Adapter package into your project.

```bash
composer require wordpress/abilities-api wordpress/mcp-adapter
```

--------------------------------

### MCP Client Configuration

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Configuration examples for connecting AI clients like Claude Desktop or VS Code to a WordPress MCP server.

```APIDOC
## CONFIGURATION MCP Servers

### Description
Configure your AI client's mcpServers settings to communicate with the WordPress MCP adapter via STDIO or HTTP.

### Configuration Example (STDIO)
```json
{
  "mcpServers": {
    "wordpress-default": {
      "command": "wp",
      "args": ["--path=/path/to/wordpress", "mcp-adapter", "serve", "--server=mcp-adapter-default-server"]
    }
  }
}
```

### Configuration Example (HTTP Proxy)
```json
{
  "mcpServers": {
    "wordpress-http": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "http://your-site.test/wp-json/mcp/mcp-adapter-default-server"
      }
    }
  }
}
```
```

--------------------------------

### Serve MCP Adapter via STDIO (WP-CLI)

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-overview.md

This command starts the MCP adapter server using STDIO transport, typically for local development. It requires specifying the server name and the user context for the WordPress site.

```bash
wp mcp-adapter serve --server=mcp-adapter-default-server --user=admin
```

--------------------------------

### Install Abilities API Plugin via WP-CLI

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Installs the Abilities API plugin using the WP-CLI command-line tool. This is a straightforward method for adding the plugin to a WordPress site.

```bash
wp plugin install https://github.com/WordPress/abilities-api/releases/latest/download/abilities-api.zip
```

--------------------------------

### Install MCP WordPress Remote Proxy

Source: https://github.com/use-novamira/novamira/blob/main/docs/mcp-wordpress-remote.md

Installs the MCP WordPress Remote Proxy package using npm. This is the initial step to set up the proxy on your system.

```bash
npm install @automattic/mcp-wordpress-remote
```

--------------------------------

### Client Configuration for STDIO Transport (JSON)

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Configuration examples for connecting AI clients (Claude Desktop, VS Code, Cursor) using the STDIO transport. It shows how to set up a default WordPress MCP server connection and a custom server connection, specifying the WordPress path and server details.

```json
{
  "mcpServers": {
    "wordpress-default": {
      "command": "wp",
      "args": [
        "--path=/path/to/wordpress/site",
        "mcp-adapter",
        "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    }
  }
}
```

```json
{
  "mcpServers": {
    "wordpress-custom": {
      "command": "wp",
      "args": [
        "--path=/path/to/wordpress/site",
        "mcp-adapter",
        "serve",
        "--server=your-custom-server-id",
        "--user=admin"
      ]
    }
  }
}
```

--------------------------------

### GET /wp-json/mcp/mcp-adapter-default-server

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Access the default MCP server via HTTP to discover and invoke WordPress abilities.

```APIDOC
## GET /wp-json/mcp/mcp-adapter-default-server

### Description
Provides an HTTP-based MCP server endpoint that exposes all registered WordPress abilities as MCP tools, resources, and prompts.

### Method
GET

### Endpoint
/wp-json/mcp/mcp-adapter-default-server

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
GET /wp-json/mcp/mcp-adapter-default-server

### Response
#### Success Response (200)
- **server_info** (object) - MCP server capability and resource discovery information.

#### Response Example
{
  "server": "mcp-adapter-default-server",
  "status": "ready",
  "capabilities": {
    "tools": {},
    "resources": {},
    "prompts": {}
  }
}
```

--------------------------------

### Add Abilities API as Composer Dependency

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Adds the Abilities API as a dependency to a project using Composer. This command downloads and installs the package into the vendor directory.

```bash
composer require wordpress/abilities-api
```

--------------------------------

### Configure MCP Client for STDIO Transport

Source: https://github.com/use-novamira/novamira/blob/main/readme.txt

JSON configuration for an AI client to connect to a local WordPress installation using WP-CLI. This method uses the --user flag for authentication instead of application passwords.

```json
{
  "mcpServers": {
    "wordpress": {
      "command": "wp",
      "args": [
        "--path=/path/to/wordpress",
        "mcp-adapter",
        "serve",
        "--user=admin"
      ]
    }
  }
}
```

--------------------------------

### Configure MCP Client for Local STDIO Transport

Source: https://context7.com/use-novamira/novamira/llms.txt

Sets up the MCP client for local development using STDIO transport via WP-CLI. This method bypasses HTTP overhead and requires direct filesystem access to the WordPress installation. It is configured within the `claude_desktop_config.json` or `settings.json` file.

```json
{
  "mcpServers": {
    "novamira-local": {
      "command": "wp",
      "args": [
        "--path=/var/www/html",
        "mcp-adapter",
        "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    }
  }
}
```

--------------------------------

### Configure Jetpack Autoloader for WordPress

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Install the Jetpack Autoloader to prevent version conflicts and include it in your main plugin file.

```bash
composer require automattic/jetpack-autoloader
```

```php
require_once plugin_dir_path( __FILE__ ) . 'vendor/autoload_packages.php';
```

--------------------------------

### Get an Ability

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Retrieves details for a specific ability, including its name, label, description, category, and output schema.

```APIDOC
## GET /wp-abilities/v1/{namespace}/{ability}

### Description
Retrieves details for a specific ability, including its name, label, description, category, and output schema.

### Method
GET

### Endpoint
/wp-abilities/v1/{namespace}/{ability}

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace of the ability.
- **ability** (string) - Required - The name of the ability.

### Response
#### Success Response (200)
- **name** (string) - The unique name of the ability.
- **label** (string) - The display name of the ability.
- **description** (string) - A description of what the ability does.
- **category** (string) - The category slug the ability belongs to.
- **output_schema** (object) - The JSON schema defining the output of the ability.
- **meta** (object) - Metadata about the ability, including annotations like readonly, destructive, and idempotent.

#### Response Example
```json
{
  "name": "my-plugin/get-site-info",
  "label": "Get Site Information",
  "description": "Retrieves basic information about the WordPress site.",
  "category": "site-information",
  "output_schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "url": { "type": "string", "format": "uri" }
    }
  },
  "meta": {
    "annotations": {
      "instructions": "",
      "readonly": true,
      "destructive": false,
      "idempotent": false
    }
  }
}
```
```

--------------------------------

### Register ability for simple data retrieval

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Example of registering a NovaMira ability that retrieves site information without requiring any input parameters. It defines output schema and an execute callback to fetch site name, description, and URL.

```php
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'my-plugin/get-site-info', [
        'label'       => __( 'Get Site Information', 'my-plugin' ),
        'description' => __( 'Retrieves site name, description, URL', 'my-plugin' ),
        'category'    => 'data-retrieval',
        'output_schema' => [
            'type'       => 'object',
            'properties' => [
                'name'        => [ 'type' => 'string' ],
                'description' => [ 'type' => 'string' ],
                'url'         => [ 'type' => 'string', 'format' => 'uri' ],
            ],
        ],
        'execute_callback'    => fn() => [
            'name'        => get_bloginfo( 'name' ),
            'description' => get_bloginfo( 'description' ),
            'url'         => home_url(),
        ],
        'permission_callback' => '__return_true',
        'meta' => [
            'annotations' => [ 'readonly' => true, 'destructive' => false ],
        ],
    ]);
});
```

--------------------------------

### Check, Get, or List Abilities in PHP

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Provides functions to check for the existence of an ability by name, retrieve a specific ability object, or get a list of all registered abilities. These functions are essential for interacting with and managing abilities within the API.

```php
wp_ability_exists( string $name ): bool
wp_get_ability( string $name ): ?WP_Ability
wp_get_abilities(): array
```

--------------------------------

### Get a Category

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Retrieves details for a specific ability category by its slug.

```APIDOC
## GET /wp-abilities/v1/categories/{slug}

### Description
Retrieves details for a specific ability category by its slug.

### Method
GET

### Endpoint
/wp-abilities/v1/categories/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique slug of the category to retrieve.

### Response
#### Success Response (200)
- **slug** (string) - The category slug.
- **label** (string) - The display name of the category.
- **description** (string) - A description of the category.

#### Response Example
```json
{
  "slug": "site-information",
  "label": "Site Information",
  "description": "Information about the WordPress site."
}
```
```

--------------------------------

### Register ability with plugin dependency (WooCommerce)

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Example of registering an ability that depends on the WooCommerce plugin being active. It includes a check for `class_exists('WooCommerce')` and defines input schema for a 'period' parameter and output schema for store statistics.

```php
add_action( 'wp_abilities_api_init', function() {
    if ( ! class_exists( 'WooCommerce' ) ) {
        return;
    }

    wp_register_ability( 'my-plugin/get-woo-stats', [
        'label'       => __( 'Get WooCommerce Statistics', 'my-plugin' ),
        'description' => __( 'Retrieves store statistics; requires WooCommerce', 'my-plugin' ),
        'category'    => 'ecommerce',
        'input_schema' => [
            'type'       => 'object',
            'properties' => [
                'period' => [
                    'type'    => 'string',
                    'enum'    => [ 'today', 'week', 'month', 'year' ],
                    'default' => 'month',
                ],
            ],
        ],
        'output_schema' => [
            'type'       => 'object',
            'properties' => [
                'total_orders'  => [ 'type' => 'integer' ],
                'total_revenue' => [ 'type' => 'number' ],
            ],
        ],
        'execute_callback'    => fn( $input ) => [ 'total_orders' => 42, 'total_revenue' => 1250.50 ],
        'permission_callback' => fn() => current_user_can( 'manage_woocommerce' ),
        'meta'                => [ 'requires_plugin' => 'woocommerce' ],
    ]);
});
```

--------------------------------

### Execute an Ability

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Executes a specific ability. The HTTP method (GET, POST, DELETE) and input format depend on the ability's annotations and requirements.

```APIDOC
## GET|POST|DELETE /wp-abilities/v1/{namespace}/{ability}/run

### Description
Executes a specific ability. The HTTP method (GET, POST, DELETE) and input format depend on the ability's annotations and requirements.

### Method
GET, POST, or DELETE (determined by ability annotations: `readonly`, `destructive`)

### Endpoint
/wp-abilities/v1/{namespace}/{ability}/run

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace of the ability.
- **ability** (string) - Required - The name of the ability to execute.

#### Query Parameters
- **input** (string) - Optional - URL-encoded JSON string representing the input for the ability. Used primarily with GET requests.

#### Request Body
- **input** (object) - Required for POST requests if the ability expects input. A JSON object containing the input parameters for the ability.

### Request Example
**GET (no input):**
```bash
curl https://example.com/wp-json/wp-abilities/v1/my-plugin/get-site-info/run
```

**GET (with input, URL-encoded):**
```bash
curl "https://example.com/wp-json/wp-abilities/v1/my-plugin/get-user-info/run?input=%7B%22user_id%22%3A1%7D"
```

**POST:**
```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"input":{"option_name":"blogname","option_value":"New Site Name"}}' \
  https://example.com/wp-json/wp-abilities/v1/my-plugin/update-option/run
```

**DELETE:**
```bash
curl -X DELETE \
  "https://example.com/wp-json/wp-abilities/v1/my-plugin/delete-post/run?input=%7B%22post_id%22%3A123%7D"
```

### Response
#### Success Response (200)
- The structure of the response depends on the `output_schema` defined for the ability. It typically returns the result of the ability execution.

#### Response Example
```json
{
  "result": "Success"
}
```
```

--------------------------------

### WP-CLI Commands for MCP Adapter

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Provides WP-CLI commands to manage and interact with the MCP adapter. This includes listing available MCP servers, discovering abilities, and listing available tools. These commands are useful for local development and testing via STDIO transport.

```bash
# List all MCP servers
wp mcp-adapter list
```

```bash
# Discover available abilities
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcp-adapter-discover-abilities","arguments":{}}}' \
  | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

```bash
# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

--------------------------------

### Configure MCP Server

Source: https://context7.com/use-novamira/novamira/llms.txt

Instructions for adding the Novamira MCP server to Claude Code or Claude Desktop using environment variables.

```APIDOC
## MCP Server Configuration

### Description
Connects the Novamira MCP server to Claude using HTTP transport. This requires a valid WP-JSON endpoint and authentication credentials.

### Configuration
- **WP_API_URL**: The URL to the WordPress REST API endpoint.
- **WP_API_USERNAME**: WordPress administrator username.
- **WP_API_PASSWORD**: WordPress application password.

### Example (Claude Desktop)
```json
{
  "mcpServers": {
    "novamira": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://your-site.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "admin",
        "WP_API_PASSWORD": "xxxx-xxxx-xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}
```
```

--------------------------------

### Initialize MCP Adapter in WordPress Plugin

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Instantiate the McpAdapter singleton in your plugin to automatically create a default server exposing registered WordPress abilities.

```php
use WP\MCP\Core\McpAdapter;

if ( ! class_exists( McpAdapter::class ) ) {
    return;
}

McpAdapter::instance();
```

--------------------------------

### List MCP Tools via WP-CLI

Source: https://context7.com/use-novamira/novamira/llms.txt

Demonstrates how to list available MCP tools using WP-CLI with STDIO transport. This command sends a JSON-RPC request to the WP-CLI MCP adapter to query for available tools.

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

--------------------------------

### Register ability with input parameters

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Demonstrates registering an ability to update WordPress options, requiring specific input parameters like 'option_name' and 'option_value'. It includes input and output schema definitions and a permission callback.

```php
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'my-plugin/update-option', [
        'label'       => __( 'Update WordPress Option', 'my-plugin' ),
        'description' => __( 'Updates option values; requires manage_options', 'my-plugin' ),
        'category'    => 'data-modification',
        'input_schema' => [
            'type'       => 'object',
            'properties' => [
                'option_name'  => [ 'type' => 'string', 'minLength' => 1 ],
                'option_value' => [ 'description' => 'New option value' ],
            ],
            'required'             => [ 'option_name', 'option_value' ],
            'additionalProperties' => false,
        ],
        'output_schema' => [
            'type'       => 'object',
            'properties' => [
                'success'        => [ 'type' => 'boolean' ],
                'previous_value' => [ 'description' => 'Previous value' ],
            ],
        ],
        'execute_callback' => fn( $input ) => [
            'success'        => update_option( $input['option_name'], $input['option_value'] ),
            'previous_value' => get_option( $input['option_name'] ),
        ],
        'permission_callback' => fn() => current_user_can( 'manage_options' ),
        'meta' => [
            'annotations' => [ 'destructive' => false, 'idempotent' => true ],
        ],
    ]);
});
```

--------------------------------

### POST /wp-json/mcp/mcp-adapter-default-server (Write File)

Source: https://context7.com/use-novamira/novamira/llms.txt

Writes content to files on the server filesystem.

```APIDOC
## POST /wp-json/mcp/mcp-adapter-default-server

### Description
Writes content to files. PHP files are restricted to the sandbox directory.

### Method
POST

### Endpoint
/wp-json/mcp/mcp-adapter-default-server

### Request Body
- **params.name** (string) - Required - "novamira-write-file"
- **params.arguments.path** (string) - Required - Destination path
- **params.arguments.content** (string) - Required - File content
- **params.arguments.mode** (string) - Optional - "overwrite" or "append"

### Request Example
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "novamira-write-file",
    "arguments": {
      "path": "wp-content/novamira-sandbox/test.php",
      "content": "<?php echo 'hello'; ?>"
    }
  }
}
```

--------------------------------

### Get Specific or All Ability Categories in PHP

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Retrieves a specific ability category by its slug or fetches all registered categories. `wp_get_ability_category` returns a single category object, while `wp_get_ability_categories` returns an associative array of all categories keyed by their slugs.

```php
wp_get_ability_category( string $slug ): ?WP_Ability_Category
wp_get_ability_categories(): array  // keyed by slug
```

--------------------------------

### POST /wp-json/mcp/mcp-adapter-default-server (Execute PHP)

Source: https://context7.com/use-novamira/novamira/llms.txt

Executes arbitrary PHP code within the WordPress environment.

```APIDOC
## POST /wp-json/mcp/mcp-adapter-default-server

### Description
Executes arbitrary PHP code on the WordPress server with full access to the WordPress environment including $wpdb and loaded plugin APIs.

### Method
POST

### Endpoint
/wp-json/mcp/mcp-adapter-default-server

### Request Body
- **jsonrpc** (string) - Required - Version of JSON-RPC (2.0)
- **method** (string) - Required - Set to "tools/call"
- **params** (object) - Required - Contains tool name and arguments
- **params.name** (string) - Required - "novamira-execute-php"
- **params.arguments.code** (string) - Required - The PHP code to execute

### Request Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "novamira-execute-php",
    "arguments": {
      "code": "$posts = get_posts(['numberposts' => 5]); return $posts;"
    }
  }
}

### Response
#### Success Response (200)
- **result** (object) - Contains the execution output, return value, and any errors.
```

--------------------------------

### Configure WP-Env for MCP Adapter

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-adapter.md

Add the required plugins to your .wp-env.json configuration file to enable the MCP adapter in a local development environment.

```json
{
  "plugins": [
    "WordPress/abilities-api",
    "WordPress/mcp-adapter"
  ]
}
```

--------------------------------

### Add WordPress MCP via Claude Code

Source: https://github.com/use-novamira/novamira/blob/main/docs/mcp-wordpress-remote.md

Adds the WordPress MCP service to Claude Code using the 'claude mcp add' command. This example demonstrates adding the service with environment variables for authentication and API URL.

```bash
claude mcp add wordpress_mcp \
  --env WP_API_URL=https://your-site.com/wp-json/mcp/mcp-adapter-default-server \
  --env WP_API_USERNAME=your-username \
  --env WP_API_PASSWORD=your-application-password \
  -- npx -y @automattic/mcp-wordpress-remote@latest
```

--------------------------------

### Enable File

Source: https://context7.com/use-novamira/novamira/llms.txt

Re-enables a previously disabled sandbox file by removing the '.disabled' suffix. Accepts either the original path or the disabled path as input.

```APIDOC
## POST /api/tools/call (novamira-enable-file)

### Description
Re-enables a disabled file in the Novamira sandbox by removing the `.disabled` extension. This can be done using either the original file path or the path of the disabled file.

### Method
POST

### Endpoint
/api/tools/call

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version.
- **id** (integer) - Required - The request ID.
- **method** (string) - Required - Must be "tools/call".
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, must be "novamira-enable-file".
  - **arguments** (object) - Required - Arguments for the novamira-enable-file tool.
    - **path** (string) - Required - The path to the disabled sandbox file to re-enable (can be the original or the `.disabled` path).

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "novamira-enable-file",
    "arguments": {
      "path": "wp-content/novamira-sandbox/experimental-feature.php"
    }
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (integer) - The request ID.
- **result** (object) - The result of the tool call.
  - **content** (array) - An array containing the result details.
    - **type** (string) - The type of content, typically "text".
    - **text** (string) - A JSON string indicating the disabled path, the new enabled path, and a boolean indicating if the file was enabled.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"disabled_path\":\"/var/www/html/wp-content/novamira-sandbox/experimental-feature.php.disabled\",\"enabled_path\":\"/var/www/html/wp-content/novamira-sandbox/experimental-feature.php\",\"enabled\":true}"
      }
    ]
  }
}
```
```

--------------------------------

### Register New Ability

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Uses the wp_abilities_api_init hook to register a custom ability, including its schema, callback, and permissions.

```php
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'my-plugin/ability', [
        'label'               => __( 'Title', 'my-plugin' ),
        'description'         => __( 'Description.', 'my-plugin' ),
        'category'            => 'analytics',
        'input_schema'        => [ 'type' => 'object', 'properties' => [], 'additionalProperties' => false ],
        'output_schema'       => [ 'type' => 'string', 'description' => 'Result.' ],
        'execute_callback'    => 'my_plugin_callback',
        'permission_callback' => '__return_true',
        'meta'                => [ 'show_in_rest' => true ],
    ]);
});
```

--------------------------------

### Authenticate with REST API

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Demonstrates how to authenticate requests to the Novamira REST API using application passwords via cURL.

```bash
curl -u 'USERNAME:APPLICATION_PASSWORD' \
  https://example.com/wp-json/wp-abilities/v1/abilities
```

--------------------------------

### Register and Execute a Novamira Ability in PHP

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

This pattern shows how to define a callback function, register it as a Novamira ability with input/output schemas, and execute it within a WordPress hook. It ensures proper metadata and permission handling for the ability.

```php
// 1. Define callback
function my_plugin_get_site_title( array $input = [] ): string {
    return get_bloginfo( 'name' );
}

// 2. Register on init hook
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'my-plugin/get-site-title', [
        'label'       => __( 'Get Site Title', 'my-plugin' ),
        'description' => __( 'Retrieves the title of the current WordPress site.', 'my-plugin' ),
        'category'    => 'site-info',
        'input_schema' => [
            'type'                 => 'object',
            'properties'           => [],
            'additionalProperties' => false,
        ],
        'output_schema' => [
            'type'        => 'string',
            'description' => 'The site title.',
        ],
        'execute_callback'    => 'my_plugin_get_site_title',
        'permission_callback' => '__return_true',
        'meta'                => [ 'show_in_rest' => true ],
    ]);
});

// 3. Execute programmatically
add_action( 'admin_init', function() {
    $ability = wp_get_ability( 'my-plugin/get-site-title' );
    if ( ! $ability ) {
        return;
    }

    $result = $ability->execute();
    if ( is_wp_error( $result ) ) {
        error_log( 'Error: ' . $result->get_error_message() );
        return;
    }

    echo 'Site Title: ' . esc_html( $result );
});
```

--------------------------------

### Basic MCP Client Configuration

Source: https://github.com/use-novamira/novamira/blob/main/docs/mcp-wordpress-remote.md

Configures the MCP client to use the WordPress remote proxy. This involves specifying the command to run the proxy and setting the WordPress API URL via environment variables.

```json
{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com"
      }
    }
  }
}
```

--------------------------------

### POST /wp-json/mcp/mcp-adapter-default-server (Read File)

Source: https://context7.com/use-novamira/novamira/llms.txt

Reads file contents from the WordPress server filesystem.

```APIDOC
## POST /wp-json/mcp/mcp-adapter-default-server

### Description
Reads file contents from the server. Supports text and binary files.

### Method
POST

### Endpoint
/wp-json/mcp/mcp-adapter-default-server

### Request Body
- **params.name** (string) - Required - "novamira-read-file"
- **params.arguments.path** (string) - Required - Path to the file
- **params.arguments.offset** (integer) - Optional - Start byte
- **params.arguments.limit** (integer) - Optional - Max bytes to read

### Request Example
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "novamira-read-file",
    "arguments": {
      "path": "wp-config.php"
    }
  }
}
```

--------------------------------

### Add Novamira MCP Server via Command Line

Source: https://context7.com/use-novamira/novamira/llms.txt

Adds the Novamira MCP server to Claude Code using a command-line interface. This method requires specifying environment variables for API credentials and the server URL.

```bash
claude mcp add novamira \
  --env WP_API_URL=https://your-site.com/wp-json/mcp/mcp-adapter-default-server \
  --env WP_API_USERNAME=admin \
  --env WP_API_PASSWORD=xxxx-xxxx-xxxx-xxxx-xxxx-xxxx \
  -- npx -y @automattic/mcp-wordpress-remote@latest
```

--------------------------------

### Connect to Remote WordPress MCP via HTTP (Node.js)

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-mcp-overview.md

This command uses npx to run the MCP WordPress Remote proxy, enabling AI clients to connect to remote WordPress MCP servers over HTTP. It facilitates communication through the WordPress REST API to the MCP Adapter.

```bash
npx @automattic/mcp-wordpress-remote
```

--------------------------------

### Run Mago Code Quality Checks

Source: https://github.com/use-novamira/novamira/blob/main/CLAUDE.md

Execute code formatting, linting, and static analysis using the Mago tool. Ensure code adheres to project standards before committing.

```sh
./vendor/bin/mago format    # auto-format (print-width 120)
```

```sh
./vendor/bin/mago lint      # lint checks
```

```sh
./vendor/bin/mago analyze   # static analysis (PHP 8.0, includes WP stubs)
```

--------------------------------

### List Directory Contents via MCP

Source: https://context7.com/use-novamira/novamira/llms.txt

Lists files and directories at a specified path, supporting glob patterns, recursive depth, and hidden file inclusion.

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "novamira-list-directory",
    "arguments": {
      "path": "wp-content/novamira-sandbox",
      "pattern": "*.php",
      "recursive": false,
      "include_hidden": true,
      "limit": 100
    }
  }
}
```

--------------------------------

### Hook into Ability Execution

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Uses the wp_before_execute_ability hook to log information before an ability is executed.

```php
add_action( 'wp_before_execute_ability', function( string $name, $input ) {
    error_log( "Executing ability: $name" );
    if ( $input !== null ) {
        error_log( 'Input: ' . wp_json_encode( $input ) );
    }
}, 10, 2 );
```

--------------------------------

### Register Ability in PHP

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Registers a new ability within the Abilities API. This function requires a unique name (formatted as 'namespace/ability-name') and an array of arguments, including label, description, category, output schema, and callback functions for execution and permissions. Optional arguments include input schema and metadata.

```php
wp_register_ability( string $name, array $args ): ?WP_Ability
```

--------------------------------

### List Directory

Source: https://context7.com/use-novamira/novamira/llms.txt

Lists files and directories at a given path with support for glob pattern filtering, recursive listing with configurable depth, and hidden file inclusion. Results are sorted with directories first, then alphabetically.

```APIDOC
## POST /api/tools/call (novamira-list-directory)

### Description
Lists the contents of a directory, with options to filter by pattern, list recursively, include hidden files, and set a limit on the number of results.

### Method
POST

### Endpoint
/api/tools/call

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version.
- **id** (integer) - Required - The request ID.
- **method** (string) - Required - Must be "tools/call".
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, must be "novamira-list-directory".
  - **arguments** (object) - Required - Arguments for the novamira-list-directory tool.
    - **path** (string) - Required - The path to the directory to list.
    - **pattern** (string) - Optional - A glob pattern to filter the results (e.g., "*.php").
    - **recursive** (boolean) - Optional - If true, lists contents recursively. Defaults to false.
    - **include_hidden** (boolean) - Optional - If true, includes hidden files (starting with '.'). Defaults to false.
    - **limit** (integer) - Optional - The maximum number of entries to return.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "novamira-list-directory",
    "arguments": {
      "path": "wp-content/novamira-sandbox",
      "pattern": "*.php",
      "recursive": false,
      "include_hidden": true,
      "limit": 100
    }
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (integer) - The request ID.
- **result** (object) - The result of the tool call.
  - **content** (array) - An array containing the result details.
    - **type** (string) - The type of content, typically "text".
    - **text** (string) - A JSON string containing directory listing details, including path, entries, total count, and truncation status.
      - **path** (string) - The absolute path of the listed directory.
      - **entries** (array) - An array of file/directory entries.
        - **name** (string) - The name of the entry.
        - **path** (string) - The absolute path of the entry.
        - **type** (string) - "file" or "directory".
        - **size** (integer) - Size in bytes (for files).
        - **permissions** (string) - File permissions.
        - **modified** (string) - Last modified timestamp.
      - **total** (integer) - Total number of entries found.
      - **truncated** (boolean) - Indicates if the results were truncated due to the limit.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"path\":\"/var/www/html/wp-content/novamira-sandbox\",\"entries\":[{\"name\":\"custom-shortcode.php\",\"path\":\"/var/www/html/wp-content/novamira-sandbox/custom-shortcode.php\",\"type\":\"file\",\"size\":220,\"permissions\":\"0644\",\"modified\":\"2026-03-26T10:30:00+00:00\"}],\"total\":1,\"truncated\":false}"
      }
    ]
  }
}
```
```

--------------------------------

### List Abilities

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Retrieves a list of available abilities. Supports pagination and filtering by category.

```APIDOC
## GET /wp-abilities/v1/abilities

### Description
Retrieves a list of available abilities. Supports pagination and filtering by category.

### Method
GET

### Endpoint
/wp-abilities/v1/abilities

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Current page number for pagination.
- **per_page** (integer) - Optional - Number of items per page. Defaults to 50, maximum 100.
- **category** (string) - Optional - Filter abilities by category slug.

### Response
#### Success Response (200)
- **abilities** (array) - An array of ability objects.
- **total_pages** (integer) - The total number of pages available.

#### Response Example
```json
{
  "abilities": [
    {
      "name": "my-plugin/get-site-info",
      "label": "Get Site Information",
      "description": "Retrieves basic information about the WordPress site.",
      "category": "site-information"
    }
  ],
  "total_pages": 5
}
```
```

--------------------------------

### Run Code Checks

Source: https://github.com/use-novamira/novamira/blob/main/CONTRIBUTING.md

Execute these commands to ensure your code adheres to project standards for formatting, linting, and analysis before submitting a pull request.

```sh
mago format
mago lint
mago analyze
```

--------------------------------

### Write File Content with Novamira

Source: https://context7.com/use-novamira/novamira/llms.txt

Writes content to files on the server filesystem using the 'novamira/write-file' ability. PHP files can only be written to the sandbox directory. Supports UTF-8 text and base64-encoded binary content, with options to create directories and overwrite.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "novamira-write-file",
    "arguments": {
      "path": "wp-content/novamira-sandbox/custom-shortcode.php",
      "content": "<?php\n/**\n * Plugin Name: Custom Shortcode\n */\nadd_shortcode('greeting', function($atts) {
    $name = $atts['name'] ?? 'World';
    return '<p>Hello, ' . esc_html($name) . '!</p>';
});",
      "encoding": "utf-8",
      "mode": "overwrite",
      "create_directories": true
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"path\":\"/var/www/html/wp-content/novamira-sandbox/custom-shortcode.php\",\"bytes_written\":198,\"created\":true,\"directories_created\":[],\"size\":198}"
      }
    ]
  }
}
```

--------------------------------

### Configure Novamira MCP Server in JSON

Source: https://context7.com/use-novamira/novamira/llms.txt

Configures the Novamira MCP server settings within a JSON file, typically `claude_desktop_config.json` or `settings.json`. This allows for programmatic management of server connections and environment variables.

```json
{
  "mcpServers": {
    "novamira": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://your-site.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "admin",
        "WP_API_PASSWORD": "xxxx-xxxx-xxxx-xxxx-xxxx-xxxx",
        "LOG_FILE": "/tmp/novamira-mcp.log"
      }
    }
  }
}
```

--------------------------------

### Manage MCP WordPress Remote Tokens (Bash)

Source: https://github.com/use-novamira/novamira/blob/main/docs/mcp-wordpress-remote.md

Provides bash commands for managing stored authentication tokens for the MCP WordPress Remote Proxy. This includes viewing, clearing all, or clearing version-specific tokens.

```bash
# View stored tokens
ls -la ~/.mcp-auth/wordpress-remote-*

# Clear all tokens
rm -rf ~/.mcp-auth/wordpress-remote-*

# Clear version-specific tokens
rm -rf ~/.mcp-auth/wordpress-remote-0.2.1/
```

--------------------------------

### Authentication

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Details on how to authenticate requests to the WP Abilities API.

```APIDOC
## Authentication

All endpoints require an authenticated user. Abilities must have `show_in_rest => true` to be exposed.

### Methods
- **Cookie authentication**: Standard same-origin authentication.
- **Application passwords**: Recommended for external access. Use Basic Authentication with your username and application password.

### Example (using Application Passwords)
```bash
curl -u 'USERNAME:APPLICATION_PASSWORD' \
  https://example.com/wp-json/wp-abilities/v1/abilities
```
```

--------------------------------

### Configure WordPress Application Passwords (Legacy)

Source: https://github.com/use-novamira/novamira/blob/main/docs/mcp-wordpress-remote.md

Configures legacy authentication using WordPress application passwords. This method uses basic HTTP authentication and is less secure than OAuth 2.1.

```json
{
  "env": {
    "WP_API_URL": "https://your-wordpress-site.com",
    "WP_API_USERNAME": "your-username",
    "WP_API_PASSWORD": "your-application-password",
    "OAUTH_ENABLED": "false"
  }
}
```

--------------------------------

### Execute an Ability in PHP

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Executes a registered ability using its object. The `execute` method takes optional input and returns the result of the ability's callback function. Error handling is included for cases where the execution fails or returns a `WP_Error` object.

```php
$ability = wp_get_ability( 'my-plugin/get-site-title' );
$result  = $ability->execute( $input );

if ( is_wp_error( $result ) ) {
    $error_message = $result->get_error_message();
}

```

--------------------------------

### Enable File via MCP

Source: https://context7.com/use-novamira/novamira/llms.txt

Re-enables a previously disabled file by removing the '.disabled' suffix from the filename.

```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "novamira-enable-file",
    "arguments": {
      "path": "wp-content/novamira-sandbox/experimental-feature.php"
    }
  }
}
```

--------------------------------

### Configure WooCommerce Integration

Source: https://github.com/use-novamira/novamira/blob/main/docs/mcp-wordpress-remote.md

Configures the WordPress remote proxy for WooCommerce integration by providing consumer key and secret for API access.

```json
{
  "env": {
    "WOO_CUSTOMER_KEY": "ck_your-consumer-key",
    "WOO_CUSTOMER_SECRET": "cs_your-consumer-secret"
  }
}
```

--------------------------------

### Check Abilities API Availability in PHP

Source: https://github.com/use-novamira/novamira/blob/main/docs/wordpress-abilities-api.md

Checks if the Abilities API classes are available in the WordPress environment. If not, it displays an admin notice and exits. It also includes a check for a minimum required version.

```php
if ( ! class_exists( 'WP_Ability' ) ) {
    add_action( 'admin_notices', static function() {
        wp_admin_notice(
            esc_html__( 'This plugin requires the Abilities API.', 'my-plugin' ),
            'error'
        );
    } );
    return;
}

// Check specific version
if ( ! defined( 'WP_ABILITIES_API_VERSION' ) ||
     version_compare( WP_ABILITIES_API_VERSION, '0.1.0', '<' ) ) {
    // handle version mismatch
}

```

--------------------------------

### Restrict Filesystem Access via Filter

Source: https://github.com/use-novamira/novamira/blob/main/readme.txt

A PHP filter implementation to restrict AI agent filesystem access to a specific directory. Returning a path limits access, while returning false disables the restriction.

```php
add_filter( 'novamira_filesystem_base_dir', function() {
    return WP_CONTENT_DIR; // Only allow access within wp-content
} );
```

--------------------------------

### Register Custom WordPress Ability

Source: https://context7.com/use-novamira/novamira/llms.txt

How to register custom abilities in WordPress that are automatically exposed to MCP clients.

```APIDOC
## Register Custom Ability

### Description
Registers a new ability using the `wp_abilities_api_init` hook. Abilities marked with `mcp => ['public' => true]` are automatically exposed to connected MCP clients.

### Parameters
- **label** (string) - Human-readable name.
- **description** (string) - Purpose of the ability.
- **input_schema** (object) - JSON schema defining expected input parameters.
- **execute_callback** (callable) - The logic to execute when the ability is called.

### Example
```php
add_action('wp_abilities_api_init', function() {
    wp_register_ability('my-plugin/get-recent-orders', [
        'label' => 'Get Recent Orders',
        'input_schema' => [...],
        'execute_callback' => function($input) { ... },
        'meta' => [
            'mcp' => ['public' => true]
        ]
    ]);
});
```
```