@stellarwp/mcp-api-fetch

🌐 API Fetch (@stellarwp/mcp-api-fetch)

A Node.js compatible implementation of WordPress's @wordpress/api-fetch with built-in middleware for MCP server environments.

📦 What is this?

This package provides a drop-in replacement for @wordpress/api-fetch that works seamlessly in Node.js environments while maintaining full API compatibility. It's specifically designed for MCP servers that need to interact with WordPress REST APIs, with automatic authentication and URL handling.

✨ Features

• 🔄 API Compatibility: Maintains the exact same API surface as @wordpress/api-fetch
• 🖥️ Node.js Native: Built specifically for Node.js environments with custom fetch implementation
• 🔐 Authentication: Automatic WordPress Application Password authentication
• 🌐 URL Resolution: Handles WordPress permalink structures and REST API URL construction
• 📱 Dual Build: Supports both Node.js and WordPress browser environments
• ⚡ Middleware: Extensible middleware architecture for custom functionality
• 🛡️ Error Handling: Comprehensive error handling and response parsing

🚀 Getting Started

Prerequisites

• Node.js 18+ or Bun 1.2.20+
• WordPress site with REST API enabled
• WordPress Application Password for authentication (when running on Node.js)

Installation

# Install the package
bun add @stellarwp/mcp-api-fetch

# Or with npm
npm install @stellarwp/mcp-api-fetch

Environment Setup

This package works with the Node Config package for environment variable management. Create a .env file in your project root:

WP_REST_URL=https://your-site.com/wp-json/wp/v2/
WP_USERNAME=your_username
WP_APP_PASSWORD=your_application_password

💡 Local Development Tip: When developing on a local environment where SSL certificates wouldn't validate (e.g., localhost with self-signed certs), you can set NODE_TLS_REJECT_UNAUTHORIZED=0 in your environment variables. Note: This should only be used in development environments, never in production.

🔧 Usage

Basic API Requests

import apiFetch from '@stellarwp/mcp-api-fetch';

// Simple GET request
const posts = await apiFetch({ path: '/wp/v2/posts' });

🏗️ Architecture

🔄 Core API Fetch

The package provides a middleware-based architecture that extends the standard @wordpress/api-fetch functionality:

• Request Processing: Automatically processes requests through configured middleware
• Response Handling: Standardized response parsing and error handling
• HTTP Methods: Full support for GET, POST, PUT, DELETE, PATCH, and HEAD
• Data Types: Handles JSON, FormData, and other content types

🔐 Authentication Middleware

The authentication approach depends on your deployment environment:

Node.js MCP Server (Requires Application Passwords)

When running as a Node.js-based MCP server, the package automatically adds WordPress authentication using WordPress Application Passwords:

// Middleware automatically adds these headers:
// Authorization: Basic base64(username:password)
// Uses WP_USERNAME and WP_APP_PASSWORD environment variables

Browser Integration (Uses WordPress Authentication)

When the package is used in a browser environment, it integrates with WordPress's built-in authentication system. The package must be bundled with your project's webpack configuration to include the @wordpress/api-fetch version provided by WordPress, which automatically handles authentication using the current user's WordPress session.

🌐 Root URL Middleware

Handles WordPress URL construction and normalization:

• Automatic Prefixing: Prepends WP_REST_URL to all relative paths
• Permalink Support: Works with any WordPress permalink structure
• URL Normalization: Ensures consistent URL formatting across environments

🌍 Environment Differences

Node.js Environment

• Custom Implementation: Uses Node.js fetch with full middleware support
• Authentication: Automatic WordPress Application Password authentication
• URL Handling: Automatic REST API URL prefixing
• Error Handling: Comprehensive error handling and logging

Browser Environment

• WordPress Integration: Expects @wordpress/api-fetch to be provided by WordPress
• Credential Sharing: Automatically uses WordPress authentication credentials
• Dependency: Requires wp-api-fetch to be enqueued by WordPress

Browser Setup Requirements

When using this package in a browser environment:

// In your WordPress theme or plugin
wp_enqueue_script('wp-api-fetch');
wp_enqueue_script('mcp-api-fetch', 'path/to/browser.js', ['wp-api-fetch']);

🔌 Middleware System

Built-in Middleware

1. Root URL Middleware: Automatically prefixes relative paths with WordPress REST API URL
2. Authentication Middleware: Adds Basic Authentication headers using environment variables

Custom Middleware

You can extend the functionality by adding custom middleware:

import { use } from '@stellarwp/mcp-api-fetch';

// Custom middleware for logging
use(async (options, next) => {
  console.log('Request:', options);
  const response = await next(options);
  console.log('Response:', response);
  return response;
});

📦 Bundle Information

The package provides different builds for different environments:

• Node.js: index.js - Full middleware support with custom fetch implementation
• Browser: browser.js - WordPress integration with external @wordpress/api-fetch dependency
• Types: index.d.ts - TypeScript definitions

🔗 Related Links

• WordPress API Fetch - WordPress API Fetch documentation
• WordPress REST API - WordPress REST API documentation
• Node Config Package - Environment configuration management
• StellarWP - WordPress development tools