guildcontrol

# GuildControl MCP

<img src="https://raw.githubusercontent.com/j-256/guildcontrol/v2.3.0/assets/guildcontrol-icon.png" alt="GuildControl MCP shield and reviewed connection icon" width="128">

GuildControl MCP is a local stdio Model Context Protocol server for safe Discord guild and separately allowlisted one-to-one access through an operator-owned bot. It combines broad typed coverage with exact scope, privacy-minimized results, reviewed writes, content-free evidence, and explicit ambiguity handling.

**Least privilege. Review before mutation. Verifiable outcomes. No Discord-content persistence.**

[Documentation portal](https://docs.guildcontrol.lasers.app/) | [Verified product tour](https://docs.guildcontrol.lasers.app/generated/contract-explorer.html#tour) | [Get a verified read](docs/getting-started.md) | [Safety and usability decisions](docs/safety-usability.md) | [Switch from another MCP](docs/migration.md) | [Fit and boundaries](docs/limitations.md) | [Field comparison](docs/comparison.md) | [Complete reference](docs/reference.md) | [Privacy](PRIVACY.md) | [Security](SECURITY.md)

GuildControl is an independent project and is not affiliated with or endorsed by Discord Inc. Discord is used only to identify the platform that GuildControl connects to.

## Why this connector

| Concern | Enforced behavior |
| --- | --- |
| Discord reach | One strict non-secret policy file with verified application and bot identities, explicit guild and channel scope, a separate exact-user private-message scope, risk-separated toolsets, and read-only setup presets |
| Exact targeting | Canonical Discord jump links and official typed mentions convert locally into exact IDs without name lookup, Discord contact, input echo, persistence, or downstream authority |
| Read safety | Bounded requests, safe transient GET retries, lossless whole-result byte budgets, strict response validation, privacy-tiered projections, untrusted-content handling, caller-retained catch-up, exact attachment reads without local-file persistence, no private-channel discovery, and only explicit verified parent-thread inheritance |
| Write safety | Exact-ID requests, execute-first keyed planning, signed interactive approval, a final fresh-plan match, and action-specific Discord permission proof |
| Outcome integrity | Pending content-free evidence, non-retried writes, exact readback, durable coordination, ambiguity quarantine, and bounded local invalid-request pressure |
| Privacy | Tokens stay in a caller-owned secret source; Discord content, profiles, URLs, audit reasons, and raw operation keys are not persisted |
| Plan review | Complete evidence, MCP App display, and local authority-free blueprint preview |
| Release integrity | Exact dependency and base-image pins, credential-free contract fingerprints, reproducible npm and MCPB artifacts, hardened OCI checks, embedded and external SPDX evidence, signed-release automation, and source-bound public documentation |

Use the [first verified read guide](docs/getting-started.md) for setup and recovery. Read [product boundaries and host compatibility](docs/limitations.md) before adopting the custody, privacy, approval, and recovery model. The [complete reference](docs/reference.md) covers every policy, tool, permission, resource, prompt, command, and workflow limit.

## Quick start

The fastest supported outcome is an owner-managed read-only bot, one strict non-secret policy, one private host guide, and a successful channel inventory. You need Node.js 22 or newer, `Manage Server` authority in a Discord server you control, and a local stdio MCP host. GuildControl provides no shared bot, relay, or token store.

### Guided setup: start here

Create an application and bot in the [Discord Developer Portal](https://discord.com/developers/applications), enable Developer Mode in Discord, and copy the Application ID and target Server ID. Then run:

```sh
npx guildctl
```

`npx guildctl` starts interactive onboarding: host selection, minimum `server-observer` policy creation or exact revalidation, live bot and MCP verification, and a private activation guide. It fails closed on drift and never stores the token, reads message content, enables writes, discovers host paths, or edits host configuration.

The result explains credential handoff; a one-time prompt is cleared after smoke. See the [first verified read guide](docs/getting-started.md) for custody and recovery.

Optional `guildctl host detect` checks path metadata only. `onboard --detect-host` selects one candidate; ambiguity requires a choice. Detection reads no candidate content or credential.

For unattended setup, supply every public decision and an existing secret reference:

```sh
npx --yes guildctl@2.3.0 onboard \
  --host codex \
  --application-id YOUR_APPLICATION_ID \
  --guild-id YOUR_GUILD_ID \
  --config /absolute/private/guildcontrol.json \
  --confirm-installed YOUR_GUILD_ID \
  --token-env DISCORD_BOT_TOKEN \
  --json
```

JSON mode never prompts or opens a browser. The [first verified read guide](docs/getting-started.md) covers supported hosts, default paths, alternate credential custody, the manual route, and recovery.

Do not grant the bot `Administrator`. Generate the exact initial permission grant from a read-only preset, then narrow the installed bot role with category or channel overrides. The [bot setup guide](docs/reference.md#discord-bot-setup) explains bot ownership, optional intents, and later feature-specific permissions.

### Optional preflight: inspect without credentials

Inspect an exact release and its read-only preset without a token or Discord request:

```sh
npx --yes guildctl@2.3.0 catalog --check
npx --yes guildctl@2.3.0 catalog --html ./guildcontrol-contract.html
npx --yes guildctl@2.3.0 preset show server-observer
```

`catalog --check` verifies the credential-free, execution-disabled production contract, including complete per-tool setup and readiness metadata. `catalog --html FILE` renders it as a release-exact guided, searchable offline explorer with no external asset, runtime request, credential, or configured completion ID.

### Switch from another Discord MCP

Generate a complete release-exact outcome map before creating policy or changing the old deployment:

```sh
npx --yes guildctl@2.3.0 migrate list
npx --yes guildctl@2.3.0 migrate plan cappyeo@0.27.1 --html ./guildcontrol-migration.html
```

The [migration guide](docs/migration.md) covers every scored peer release. Planning scans no checkout, reads no configuration, host setting, environment value, or credential, contacts no network or Discord endpoint, and changes nothing. It maps every audited source tool into supported, review-required, or intentionally excluded outcomes and validates target routes against the negotiated production catalog. It does not rewrite prompts, arguments, configuration, credentials, or host settings.

### Install your owner-managed bot

Create a Discord application and bot in the [Developer Portal](https://discord.com/developers/applications), copy the public Application ID and target Server ID, and generate a callback-free install link whose guild and least-privilege permission grant come from the recommended preset:

```sh
npx --yes guildctl@2.3.0 preset install server-observer \
  --application-id YOUR_APPLICATION_ID \
  --guild-id YOUR_GUILD_ID \
  --html ./guildcontrol-onboarding.html
```

Open the printed URL while signed in as a member allowed to manage that server. It requests only `View Channel` for `server-observer`, locks the server selector to the supplied ID, requests no user token, and never sends the bot token to the connector command. Keep Public Bot disabled unless other people should be able to install your application. Use `channel-reader` instead to request `View Channel` plus `Read Message History`; its plan also identifies Message Content as the recommended Developer Portal intent.

Optional `--html FILE` adds a deterministic standalone checklist, copy controls, explicit Discord navigation, pinned follow-up commands, and exact plan evidence without a token, external asset, background request, persisted browser state, automatic browser launch, or overwrite. The terminal plan remains complete without HTML.

### Create the safest first configuration

From a canonical process-owned private directory, keep the token in a secret-capable launching environment, verify one exact guild, save the complete non-secret policy in one file, and test the full MCP path:

```bash
export DISCORD_BOT_TOKEN
printf 'Discord bot token: '
read -r -s DISCORD_BOT_TOKEN
printf '\n'
npx --yes guildctl@2.3.0 setup \
  --npx \
  --config ./guildcontrol.json \
  --preset server-observer \
  --guild-id YOUR_GUILD_ID
npx --yes guildctl@2.3.0 host --npx --config ./guildcontrol.json --html ./guildcontrol-host-activation.html
```

On PowerShell 7.1 or newer, read the token into the current process without displaying it or placing its value in command history, then run the same commands:

```powershell
$env:DISCORD_BOT_TOKEN = Read-Host "Discord bot token" -MaskInput
```

Enter each displayed multi-line shell command on one line in PowerShell; the `npx` arguments remain the same. With older Windows PowerShell, use an MCP host secret facility or protected token file instead of a token literal in command history.

If the launcher, container runtime, or orchestrator mounts the token as a file, select that input instead. The path must be absolute, the file must already exist for verified setup, and `--token-file` cannot be combined with `--token-env` or an ambient `DISCORD_BOT_TOKEN`:

```sh
npx --yes guildctl@2.3.0 setup \
  --npx \
  --config ./guildcontrol.json \
  --preset server-observer \
  --guild-id YOUR_GUILD_ID \
  --token-file /run/secrets/discord_bot_token
```

The `server-observer` preset exposes guild metadata, roles, permission diagnostics, connector health, content-free activity, and tool discovery without enabling writes, the Gateway,