@stellarwp/learndash-mcp-server/README.md

A LearnDash MCP Server implementation

# 🎁 LearnDash MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) server implementation for LearnDash that integrates with Elementor's Angie AI assistant.

## 🚀 Features

- Integration with LearnDash's course management system.
- Provides AI-powered tools for courses, lessons, assignments, enrollment management and commerce & payments.
- Connects with Elementor's Angie AI assistant.
- Built on the Model Context Protocol (MCP) standard.

### Prerequisites
- Node.js 18+ or Bun 1.2.20+

## 🔧 Installation

```bash
# Using npm
npm install @stellarwp/learndash-mcp-server

# Using bun
bun add @stellarwp/learndash-mcp-server
```

## ⚙️ Configuration

Create an `mcp.json` file with the following structure:

Using [bun](https://bun.com/) (recommended):
```json
{
  "mcpServers": {
    "learndash-mcp": {
      "command": "bunx",
      "args": ["-y", "@stellarwp/learndash-mcp-server@latest"],
      "env": {
        "WP_REST_URL": "https://your-wordpress-site.com/wp-json",
        "WP_USERNAME": "your-username",
        "WP_APP_PASSWORD": "your-application-password",
        "NODE_TLS_REJECT_UNAUTHORIZED": 1
      }
    }
  }
}
```

Using npm:
```json
{
  "mcpServers": {
    "learndash-mcp": {
      "command": "npx",
      "args": ["-y", "@stellarwp/learndash-mcp-server@latest"],
      "env": {
        "WP_REST_URL": "https://your-wordpress-site.com/wp-json",
        "WP_USERNAME": "your-username",
        "WP_APP_PASSWORD": "your-application-password",
        "NODE_TLS_REJECT_UNAUTHORIZED": 1
      }
    }
  }
}
```

Required environment variables:
- `WP_REST_URL`: Your WordPress site's REST API URL
- `WP_USERNAME`: Your WordPress username
- `WP_APP_PASSWORD`: Your WordPress application password

### Usage with Cursor or Claude Desktop

Add and customize the above configuration. For more information, read the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) or the [Claude Desktop MCP guide](https://modelcontextprotocol.io/quickstart/user).

#### Claude Code CLI

Using bun:
```bash
claude mcp add learndash \
  --env WP_REST_URL=https://your-wordpress-site.com/wp-json \
  --env WP_USERNAME=admin \
  --env WP_APP_PASSWORD='XXXX XXXX XXXX XXXX XXXX XXXX' \
  -- \
  bunx -y @stellarwp/learndash-mcp-server@latest
```

Using npm:
```bash
claude mcp add learndash \
  --env WP_REST_URL=https://your-wordpress-site.com/wp-json \
  --env WP_USERNAME=admin \
  --env WP_APP_PASSWORD='XXXX XXXX XXXX XXXX XXXX XXXX' \
  -- \
  npx -y @stellarwp/learndash-mcp-server@latest
```

### Testing MCP Server Tools

> [!IMPORTANT]
> You need an accessible WordPress installation with LearnDash installed that the MCP Server can talk to.

The easiest way to test the tools for valid REST connectivity is to use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).

1. Ensure you have [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed.
1. Create an [application password](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/#add-a-new-application-password) in your WordPress site.
1. Create a [mcp.json](#%EF%B8%8F-configuration) and fill in valid `env` values.

Run this in your terminal, and it will automatically launch the MCP Inspector and allow you to run an instance of the server
locally:

```bash
npx @modelcontextprotocol/inspector --config path/to/your/mcp.json
```

> [!TIP]
> If you're testing this against a local WordPress install that does not have a valid SSL certificate, set `NODE_TLS_REJECT_UNAUTHORIZED` to `0` in the `mcp.json`
> to allow API requests to complete. **Note**: This should only be used in development environments, never in production.

## 🏃‍♂️ Usage

### CLI Usage

> [!IMPORTANT]  
> Copy the [.env.example](.env.example) to an `.env` file in your current working directory and fill it out according to the [configuration](#%EF%B8%8F-configuration).

```bash
# Start the MCP Server with bunx
bunx -y @stellarwp/learndash-mcp-server@latest

# Start the MCP Server with npx
npx -y @stellarwp/learndash-mcp-server@latest

# Or if cloned locally
bun run src/index.ts
```

### Integration with Elementor's Angie

This server can be integrated with Elementor's Angie AI assistant:

```javascript
import register from '@stellarwp/learndash-mcp-server/angie';

// Register the MCP server with Angie
register().then(() => console.log('Angie MCP connection successful'));
```

## 🏷️ Publishing Packages to NPM

To publish packages to NPM:

> 💡 The package version is set via `publish.yml` workflow, so just leave them all as `0.0.0`.

1. Go to the [GitHub repository releases page](../../releases)
2. Click "Create a new release"
3. Create a new tag with the version number (e.g., `1.0.1`)
4. Fill in the release title and description
5. Publish the release

This will automatically trigger the `publish.yml` GitHub workflow to publish all packages to NPM.

## 🛠️ MCP Tools Available

The server provides two powerful MCP tools that give you complete access to the LearnDash REST API:

### API Tools
- **`get-learndash-api-info`** - Retrieves the complete LearnDash REST API OpenAPI schema. This must be called before making any API requests.
- **`make-learndash-api-request`** - Makes authenticated requests to any LearnDash REST API endpoints.

## 🛠️ Development

> [!NOTE]  
> Development requires [bun](https://bun.com/).

```bash
# Install dependencies
bun install

# Build all packages
bun run build

# Run tests
bun run test
```

### Available Scripts
- `bun run build` - Build all packages
- `bun run dev` - Start development mode for all packages
- `bun run test` - Run test suite
- `bun run test:ui` - Run tests with UI
- `bun run test:coverage` - Generate test coverage report
- `bun run test:coverage:open` - Generate test coverage report and open it in your default browser
- `bun run lint` - Run ESLint
- `bun run lint:fix` - Fix ESLint problems
- `bun run format` - Check code formatting
- `bun run format:fix` - Automatically fix formatting
- `bun run typecheck` - Run TypeScript type checking
- `bun run clean` - Clean all temporary build folders