@givewp/mcp-server/README.md

A GiveWP MCP Server implementation

# 🎁 GiveWP MCP Server

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

## 🚀 Features

- Integration with GiveWP's donation management system
- Provides AI-powered tools for campaigns, donations, donors, and forms
- 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 @givewp/mcp-server

# Using bun
bun add @givewp/mcp-server
```

## ⚙️ Configuration

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

Using [bun](https://bun.com/) (recommended):
```json
{
  "mcpServers": {
    "givewp-mcp": {
      "command": "bunx",
      "args": ["-y", "@givewp/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": {
    "givewp-mcp": {
      "command": "npx",
      "args": ["-y", "@givewp/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 givewp \
  --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 @givewp/mcp-server@latest
```

Using npm:
```bash
claude mcp add givewp \
  --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 @givewp/mcp-server@latest
```

### Testing MCP Server Tools

> [!IMPORTANT]
> You need an accessible WordPress installation with GiveWP 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 @givewp/mcp-server@latest

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

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

### Integration with Elementor's Angie

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

```javascript
import register from '@givewp/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 GiveWP REST API:

### API Tools
- **`get-give-api-info`** - Retrieves the complete GiveWP REST API schema, endpoints, and available operations. This must be called before making any API requests.
- **`make-give-api-request`** - Makes authenticated requests to any GiveWP REST API endpoint with full CRUD capabilities.

### Supported Operations
Through these API tools, you can perform all GiveWP operations including:

**Campaigns:**
- List, view, create, update, and duplicate campaigns
- Get campaign statistics and revenue data
- View campaign comments

**Donors:**
- List and view donors with donation history
- Access donor notes and statistics

**Donations:**
- List, view, and manage donations
- Access donation notes

**Forms:**
- List and view donation forms

## 🛠️ 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