This document provides detailed information about the WordPress API client in the WordPress MCP Server, including how to use it, the available endpoints, and how to implement custom endpoints.
The WordPress API client is a JavaScript library for interacting with the WordPress REST API. It provides a simple and consistent interface for making requests to the WordPress REST API, handling authentication, error handling, and response parsing.
The WordPress API client is composed of several modules:
- auth.js: Handles authentication with WordPress sites using Application Passwords
- client.js: Provides a base REST client for making requests to the WordPress REST API
- index.js: Exports the main WordPress API client class
- endpoints/: Contains endpoint-specific implementations
The WordPress API client uses Application Passwords for authentication. Application Passwords are a feature of WordPress that allows you to create a password for a specific application without sharing your main WordPress password.
- Log in to your WordPress admin dashboard
- Go to Users > Profile
- Scroll down to the "Application Passwords" section
- Enter a name for the application (e.g., "WordPress MCP Server")
- Click "Add New Application Password"
- Copy the generated password (it will only be shown once)
When creating a WordPress client, you need to provide the following credentials:
const wordpress = new WordPress({
url: 'https://example.com',
username: 'admin',
applicationPassword: 'xxxx xxxx xxxx xxxx xxxx xxxx'
});The base REST client (client.js) provides methods for making HTTP requests to the WordPress REST API:
- get(endpoint, params, options): Make a GET request
- post(endpoint, data, params, options): Make a POST request
- put(endpoint, data, params, options): Make a PUT request
- patch(endpoint, data, params, options): Make a PATCH request
- delete(endpoint, params, options): Make a DELETE request
// Get all posts
const posts = await client.get('/wp/v2/posts');
// Get a specific post
const post = await client.get('/wp/v2/posts/123');
// Create a new post
const newPost = await client.post('/wp/v2/posts', {
title: 'Hello World',
content: 'This is my first post',
status: 'publish'
});
// Update a post
const updatedPost = await client.put('/wp/v2/posts/123', {
title: 'Updated Title'
});
// Delete a post
await client.delete('/wp/v2/posts/123');The main WordPress client (index.js) provides a higher-level interface for interacting with the WordPress REST API. It includes methods for common operations and initializes endpoint-specific handlers.
// Create a WordPress client
const wordpress = new WordPress({
url: 'https://example.com',
username: 'admin',
applicationPassword: 'xxxx xxxx xxxx xxxx xxxx xxxx'
});
// Validate credentials
const userData = await wordpress.validateCredentials();
// Get site information
const siteInfo = await wordpress.getSiteInfo();
// Check if the site is reachable
const reachable = await wordpress.ping();
// Get the WordPress REST API schema
const schema = await wordpress.getSchema();The WordPress MCP Server includes a site management module for managing WordPress sites. It provides methods for adding, updating, retrieving, and removing sites, as well as validating site credentials and testing connectivity.
// Create a site manager
const siteManager = new SiteManager({
configPath: '/path/to/config.json'
});
// Add a site
const site = await siteManager.addSite({
name: 'Example Site',
url: 'https://example.com',
username: 'admin',
applicationPassword: 'xxxx xxxx xxxx xxxx xxxx xxxx'
});
// Get all sites
const sites = siteManager.getAllSites();
// Get a site by ID
const site = siteManager.getSiteById('site-id');
// Update a site
const updatedSite = await siteManager.updateSite('site-id', {
name: 'Updated Site Name'
});
// Remove a site
const success = siteManager.removeSite('site-id');
// Set the active site
const activeSite = siteManager.setActiveSite('site-id');
// Get the active site
const activeSite = siteManager.getActiveSite();
// Create a WordPress client for a site
const wordpress = siteManager.createClientForSite('site-id');
// Create a WordPress client for the active site
const wordpress = siteManager.createClientForActiveSite();
// Test connectivity to a site
const reachable = await siteManager.testSiteConnectivity('site-id');
// Get information about a site
const info = await siteManager.getSiteInfo('site-id');To implement a custom endpoint, you need to create a new file in the endpoints/ directory and export an object with methods for interacting with the endpoint.
// endpoints/posts.js
export default {
/**
* Get all posts
*
* @param {Object} options - Request options
* @param {Object} options.params - Query parameters
* @returns {Promise<Array<Object>>} Array of posts
*/
async getAll(client, options = {}) {
return client.get('/wp/v2/posts', options.params);
},
/**
* Get a post by ID
*
* @param {Object} options - Request options
* @param {number} options.id - Post ID
* @param {Object} options.params - Query parameters
* @returns {Promise<Object>} Post object
*/
async getById(client, options = {}) {
if (!options.id) {
throw new Error('Post ID is required');
}
return client.get(`/wp/v2/posts/${options.id}`, options.params);
},
/**
* Create a new post
*
* @param {Object} options - Request options
* @param {Object} options.data - Post data
* @param {Object} options.params - Query parameters
* @returns {Promise<Object>} Created post object
*/
async create(client, options = {}) {
if (!options.data) {
throw new Error('Post data is required');
}
return client.post('/wp/v2/posts', options.data, options.params);
},
/**
* Update a post
*
* @param {Object} options - Request options
* @param {number} options.id - Post ID
* @param {Object} options.data - Post data
* @param {Object} options.params - Query parameters
* @returns {Promise<Object>} Updated post object
*/
async update(client, options = {}) {
if (!options.id) {
throw new Error('Post ID is required');
}
if (!options.data) {
throw new Error('Post data is required');
}
return client.put(`/wp/v2/posts/${options.id}`, options.data, options.params);
},
/**
* Delete a post
*
* @param {Object} options - Request options
* @param {number} options.id - Post ID
* @param {Object} options.params - Query parameters
* @returns {Promise<Object>} Deleted post object
*/
async delete(client, options = {}) {
if (!options.id) {
throw new Error('Post ID is required');
}
return client.delete(`/wp/v2/posts/${options.id}`, options.params);
}
};Then, in the main WordPress client, you need to initialize the endpoint handler:
// In index.js
import postsEndpoint from './endpoints/posts.js';
// ...
_initializeEndpoints() {
this.posts = {
getAll: (options) => postsEndpoint.getAll(this.client, options),
getById: (options) => postsEndpoint.getById(this.client, options),
create: (options) => postsEndpoint.create(this.client, options),
update: (options) => postsEndpoint.update(this.client, options),
delete: (options) => postsEndpoint.delete(this.client, options)
};
// Initialize other endpoints...
}The WordPress API client includes comprehensive error handling. All methods that make requests to the WordPress REST API will throw an error if the request fails.
try {
const posts = await wordpress.posts.getAll();
} catch (error) {
console.error('Error getting posts:', error);
}The WordPress API client respects WordPress API rate limits. If you exceed the rate limit, the client will throw an error with a message indicating that you've been rate limited.
The WordPress API client does not currently implement caching, but it's planned for a future release. Caching will be implemented using a configurable cache adapter, allowing you to use different caching strategies (memory, file, Redis, etc.).