# Discord Server Creator MCP

A Model Context Protocol (MCP) server that gives AI agents full control over Discord server creation and configuration. Exposes **36 tools** covering guild lifecycle, channels, roles, members, content, messages, templates, and a declarative blueprint engine.

- **Runtime:** Bun 1.1+
- **Transport:** stdio (local process)
- **Status:** 183 tests passing — see `specs.md` §14 for phase breakdown

## Quick Start

### Prerequisites

- [Bun](https://bun.sh) 1.1+
- A [Discord Bot Token](https://discord.com/developers/applications)

### 1. Install

```bash
git clone <repo> dc-server-creator
cd dc-server-creator
bun install
```

### 2. Create a Discord Bot

1. Go to <https://discord.com/developers/applications>
2. **New Application** → name it (e.g. "Server Creator")
3. **Bot** tab → **Add Bot**
4. Under **Privileged Gateway Intents**, enable **Server Members Intent** (required for member tools)
5. Copy the bot token
6. Invite the bot to a test guild via the **OAuth2 URL Generator**:
   - Scopes: `bot`
   - Permissions: `Administrator` (for testing) or select specific permissions

### 3. Register with your MCP Client

**opencode** — add to your `opencode.json` (project-level or `~/.config/opencode/opencode.json`):

```json
{
  "mcp": {
    "discord-server-creator": {
      "type": "local",
      "command": ["bun", "run", "/absolute/path/to/dc-server-creator/src/index.ts"],
      "environment": {}
    }
  }
}
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "discord-server-creator": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/dc-server-creator/src/index.ts"]
    }
  }
}
```

> Replace `/absolute/path/to/` with the actual path from `pwd` (or `cd` on Windows).

**Claude Code (plugin)** — install as a plugin with automatic skill loading:

```bash
# Add the marketplace (one-time)
/plugin marketplace add ZepioCs/dc-server-creator-mcp

# Install the plugin
/plugin install dc-server-creator@dc-server-creator-mcp
```

The plugin installs a skill (`dc-server-creator`) that teaches Claude Code when and how to use all 36 tools. After installation, Claude automatically activates the skill when you describe Discord server tasks.

You still need to configure the bot token via `configure_bot({ action: "setup", token })` — see step 4.

### 4. First Run

1. Start your MCP client (opencode / Claude Desktop)
2. The AI agent (or you) calls:
   ```
   configure_bot({ action: "setup", token: "Bot <your-token>" })
   ```
3. Server responds with the bot's identity and ready status
4. Try:
   ```
   list_guilds({})
   ```
   to see all guilds the bot is in.

### 5. One-Shot Server Creation

Apply a ready-made blueprint — no per-channel/role calls needed:

```
apply_server_blueprint({
  blueprint: { /* see examples/blueprints/ */ },
  dryRun: true   // validate first without making changes
})
```

See [examples/blueprints/](examples/blueprints/) for pre-built server templates (gaming community, dev team, support server, community default).

## Scripts

```bash
bun start          # run the MCP server (stdio)
bun run typecheck  # TypeScript type-check
bun run lint       # Biome lint
bun test           # run all tests (183+)
bun test --coverage # run with coverage report
```

## Tool Catalog

| Group | Tools | Count |
|---|---|---|
| Auth | `configure_bot`, `get_auth_status` | 2 |
| Guild | `list_guilds`, `get_guild`, `create_guild`, `modify_guild`, `delete_guild` | 5 |
| Channel | `list_channels`, `create_channel`, `create_category_with_channels`, `modify_channel`, `delete_channel`, `set_channel_permissions`, `create_invite` | 7 |
| Role | `list_roles`, `create_role`, `modify_role`, `delete_role`, `assign_role` | 5 |
| Member | `list_members`, `search_members`, `get_member`, `modify_member`, `moderate_member` | 5 |
| Messages | `send_message`, `edit_message`, `delete_message`, `get_messages` | 4 |
| Content | `manage_emoji`, `manage_sticker`, `manage_webhook`, `execute_webhook` | 4 |
| Template | `manage_template`, `create_guild_from_template` | 2 |
| Blueprint | `apply_server_blueprint` | 1 |
| Log | `get_action_log` | 1 |
| **Total** | | **36** |

See `specs.md` §5 for full input/output schemas.

## Error Handling

Every error returns a structured JSON payload with:

```json
{
  "error": "DISCORD_FORBIDDEN",
  "message": "Bot lacks MANAGE_CHANNELS permission",
  "hint": "The bot lacks the required permission. Check the bot's role permissions in the server.",
  "retryable": false,
  "traceId": "abc-123"
}
```

The `hint` field explains the likely cause and how to fix it. See `specs.md` §7 for the full error hierarchy.

## Blueprint Engine

The `apply_server_blueprint` tool accepts a declarative JSON blueprint to create an entire server in one call — including **roles, categories, channels, permissions, emoji, stickers, webhooks, and onboarding messages**.

```json
{
  "guild": { "name": "My Server", "verificationLevel": 1 },
  "roles": [{ "name": "Admin", "permissions": ["ADMINISTRATOR"] }],
  "categories": [{ "name": "General", "channels": [{ "name": "chat", "type": "text" }] }],
  "messages": [{ "channelName": "chat", "content": "Welcome!" }]
}
```

- **dryRun:** validates without making API calls
- **continueOnError:** keep going after failures
- **rollbackOnError:** undo completed steps on failure

Execution order: guild → @everyone → roles → categories → children → standalone channels → guild settings → emoji → stickers → webhooks → **messages**.

See `specs.md` §6 for the full BlueprintSpec schema and execution order.

## Project Layout

```
src/           # TypeScript source
├── index.ts           # Entry point
├── server.ts          # MCP server + tool registration
├── discord/           # Discord client, errors, mappings
├── engine/            # Blueprint engine (plan, apply, validate)
├── schemas/           # Zod schemas for all tools
├── tools/             # Tool handlers (one file per group)
└── utils/             # Logger, action log, env, retry
tests/         # Test suite
├── unit/              # Unit tests
└── integration/       # Integration tests (schema validation, etc.)
examples/      # User-facing examples
└── blueprints/        # Pre-built server blueprints
```

## Implementation Status

| Phase | Status | What |
|---|---|---|
| 1 — Foundation | ✅ | Project scaffold, Discord client, auth, basic guild tools |
| 2 — Configuration | ✅ | All channel/role/member tools, full guild CRUD |
| 3 — Content + Templates | ✅ | Emoji, sticker, webhook, template tools |
| 4 — Blueprint Engine | ✅ | Blueprint schema, validation, plan, apply with rollback, messages |
| 5 — Polish | 🔧 | Error audit (done), perf test (done), docs (done), coverage, mock tests |

See `specs.md` §14 for full details.