npm package: @hield/mcp-server
Description: MCP server for Hield event registration API
Latest version: 1.1.0

# @hield/mcp-server

MCP server for the [Hield](https://github.com/weishih/hield) event registration API. Enables AI assistants to manage events, registrations, form fields, collaborators, and stats through natural language.

## Installation

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hield": {
      "command": "npx",
      "args": ["-y", "@hield/mcp-server"],
      "env": {
        "HIELD_API_KEY": "hld_your_api_key_here",
        "HIELD_API_URL": "https://your-hield-api-url.amazonaws.com"
      }
    }
  }
}
```

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "hield": {
      "command": "npx",
      "args": ["-y", "@hield/mcp-server"],
      "env": {
        "HIELD_API_KEY": "hld_your_api_key_here",
        "HIELD_API_URL": "https://your-hield-api-url.amazonaws.com"
      }
    }
  }
}
```

## Configuration

| Environment Variable | Required | Description |
|---|---|---|
| `HIELD_API_KEY` | Yes | Your Hield tenant API key (starts with `hld_`) |
| `HIELD_API_URL` | Yes | Hield API base URL |

## Available Tools (27)

### Event Management
| Tool | Description |
|---|---|
| `hield_create_event` | Create a new event (starts as draft) |
| `hield_list_events` | List all your events (paginated) |
| `hield_get_event` | Get event details |
| `hield_update_event` | Update event properties |
| `hield_delete_event` | Delete an event |
| `hield_update_event_status` | Change event status (draft/published/closed) |

### Form Fields
| Tool | Description |
|---|---|
| `hield_create_form_field` | Add a custom form field to an event |
| `hield_list_form_fields` | List form fields for an event |
| `hield_update_form_field` | Update a form field |
| `hield_delete_form_field` | Delete a form field |

### Registration Management
| Tool | Description |
|---|---|
| `hield_list_registrations` | List registrations for an event (paginated) |
| `hield_get_registration` | Get registration details |
| `hield_update_registration` | Update registration status |
| `hield_delete_registration` | Delete a registration |

### Collaborators
| Tool | Description |
|---|---|
| `hield_invite_collaborator` | Invite a collaborator by email |
| `hield_list_collaborators` | List event collaborators |
| `hield_update_collaborator` | Change collaborator role |
| `hield_remove_collaborator` | Remove a collaborator |

### Statistics
| Tool | Description |
|---|---|
| `hield_get_event_stats` | Get registration stats for an event |
| `hield_get_overview_stats` | Get stats across all events |

### Tenant Profile
| Tool | Description |
|---|---|
| `hield_get_tenant` | Get your tenant profile |
| `hield_update_tenant` | Update tenant name |
| `hield_rotate_api_key` | Generate a new API key |

### Public (No Auth)
| Tool | Description |
|---|---|
| `hield_public_get_event` | View a published event |
| `hield_public_register` | Register for an event |
| `hield_public_get_registration` | Check registration status |
| `hield_public_cancel_registration` | Cancel a registration |

## Usage Examples

Ask your AI assistant:

- "Create an event called Tech Conference 2026 for 200 people on June 1st in Singapore"
- "Add a t-shirt size dropdown with S, M, L, XL options to my event"
- "Publish the event so people can register"
- "Show me the registration stats for my conference"
- "Invite alice@example.com as an editor on my event"
- "Build me a registration page for my published event"

## Development

```bash
cd mcp
npm install
npm run build
```

Test locally:
```bash
HIELD_API_KEY=hld_xxx HIELD_API_URL=http://localhost:8942 node dist/index.js
```

## License

MIT