# Discord MCP Server
> **⚠️ Security Notice**: This project handles Discord credentials and privileged Discord operations. Treat all tokens and secrets as sensitive.
Discord MCP Server exposes Discord runtime packages through one MCP tool with a unified metadata/execution protocol.
## Current Architecture
This repository now uses the **Discord runtime vNext protocol**:
- **MCP tool**: `discord_manage`
- **HTTP runtime**: Hono (`@hono/node-server`)
- **Read operations** (`automation.read`):
- `discord.meta.packages`
- `discord.meta.symbols`
- `discord.meta.preflight`
- `discord.meta.refresh`
- **Write operations** (`automation.write`):
- `discord.exec.invoke`
- `discord.exec.batch`
### Tool Contract
`discord_manage` uses the contract below:
- `mode`: `bot` or `user`
- `identityId`: identity record (for example `default-bot`)
- `method`: optional override (`automation.read` or `automation.write`)
- `operation`: one of
- `discord.meta.packages`
- `discord.meta.symbols`
- `discord.meta.preflight`
- `discord.meta.refresh`
- `discord.exec.invoke`
- `discord.exec.batch`
- `params` or `args`
Runtime symbol coverage:
- `class`, `function`, `enum`, `interface`, `type`, and `variable` are discovered.
- `interface`, `type`, `namespace`, and `variable` can be sourced from package declaration files (`.d.ts`) when missing at runtime.
- `discord.meta.symbols` can include an operational matrix per symbol for preflight/execution readiness.
- Catalog responses include `catalogFingerprint`, `catalogBuiltAt`, and `isFresh` metadata for agent-side cache control.
## Branch Model
- Canonical branch: `new-architecture-main`
- Repository default branch: `new-architecture-main`
## Quick Start
### Prerequisites
- Node.js 18+
- npm
- Discord bot token
### Install
```bash
git clone https://github.com/drvova/discord-mcp.git
cd discord-mcp
npm install
npm run build
```
### Run
```bash
# stdio mode (default)
npm start
# dev mode
npm run dev
# HTTP/SSE mode
npm run web
```
## Configuration
Create `.env`:
```env
DISCORD_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=your_guild_id_here
# Optional user-mode token
# DISCORD_USER_TOKEN=your_discord_user_token
# Optional encrypted identity store
# DISCORD_MCP_MASTER_KEY=your_32_byte_key_material
# DISCORD_MCP_IDENTITY_STORE_PATH=./.discord-mcp-identities.enc
# Optional risk policy override
# DISCORD_MCP_BLOCK_HIGH_RISK=true
# Optional audit log file
# DISCORD_MCP_AUDIT_LOG_PATH=./data/discord-mcp-audit.log
# Optional logging
# LOG_LEVEL=INFO
# LOG_STYLE=pretty
# LOG_COLOR=true
# ENABLE_LOGGING=true
# Optional OpenTelemetry
# OTEL_ENABLED=true
# OTEL_SERVICE_NAME=discord-mcp
# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
# OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer token
# OTEL_PROMETHEUS_PORT=9464
# OTEL_PROMETHEUS_ENDPOINT=/metrics
# Optional OAuth (HTTP mode)
# DISCORD_CLIENT_ID=...
# DISCORD_CLIENT_SECRET=...
# DISCORD_OAUTH_REDIRECT_URI=http://localhost:1455/oauth/discord/callback
```
## HTTP Endpoints
When `MCP_HTTP_PORT` (or `PORT`) is set:
- `GET /sse`
- `POST /message`
- `GET /health`
- `GET /oauth/discord/start`
- `GET /oauth/discord/callback`
## Logging
Server logs use a shared Pino logger with compact one-line output (no ISO timestamp clutter in pretty mode).
- `LOG_LEVEL` controls verbosity: `ERROR`, `WARN`, `INFO`, `DEBUG` (default `INFO`)
- `LOG_STYLE` controls output shape: `pretty` or `json` (when unset, auto mode uses `pretty` for interactive terminals and dev scripts, otherwise `json`)
- `LOG_COLOR` enables/disables ANSI colors (default `true`)
- `ENABLE_LOGGING` disables all logs when set to `false` (default `true`)
For stdio MCP mode, logs are written to stderr so protocol output on stdout remains clean.
### OpenTelemetry
- Traces are exported using OTLP HTTP (`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`).
- Metrics are exposed via Prometheus exporter at `http://localhost:${OTEL_PROMETHEUS_PORT:-9464}${OTEL_PROMETHEUS_ENDPOINT:-/metrics}`.
- Service metadata is controlled by `OTEL_SERVICE_NAME`.
## Typed HTTP Client (`hc`)
You can use the generated typed client from Hono route types:
```ts
import { createHttpClient } from "./src/http-client.js";
const client = createHttpClient("http://localhost:1455");
const healthResponse = await client.health.$get();
const health = await healthResponse.json();
const rpcResponse = await client.index.$post({
json: {
id: 1,
method: "tools/list"
}
});
const rpc = await rpcResponse.json();
```
The MCP JSON-RPC contract on `POST /` is unchanged (`initialize`, `tools/list`, `tools/call`).
## Usage Examples
### 1) List Runtime Packages
```json
{
"mode": "bot",
"identityId": "default-bot",
"method": "automation.read",
"operation": "discord.meta.packages",
"params": {
"packages": ["discordjs", "discordjs_voice"]
}
}
```
### 2) Discover Symbols + Operational Matrix
```json
{
"mode": "bot",
"identityId": "default-bot",
"method": "automation.read",
"operation": "discord.meta.symbols",
"params": {
"packageAlias": "discordjs",
"kinds": ["class", "function", "enum", "interface", "type", "variable"],
"query": "TextChannel#send",
"includeAliases": true,
"includeKindCounts": true,
"includeOperationalMatrix": true
}
}
```
### 3) Preflight Before Execution
```json
{
"mode": "bot",
"identityId": "default-bot",
"method": "automation.read",
"operation": "discord.meta.preflight",
"params": {
"packageAlias": "discordjs",
"symbol": "TextChannel#send",
"kind": "function",
"target": "channel",
"context": {
"channelId": "123456789012345678"
},
"policyMode": "strict",
"strictContextCheck": true,
"strictArgCheck": false
}
}
```
### 4) Refresh Package + Symbol Catalog
```json
{
"mode": "bot",
"identityId": "default-bot",
"method": "automation.read",
"operation": "discord.meta.refresh",
"params": {
"force": true,
"includeDiff": true
}
}
```
### 5) Execute Invocation (Safe by Default)
```json
{
"mode": "bot",
"identityId": "default-bot",
"method": "automation.write",
"operation": "discord.exec.invoke",
"params": {
"packageAlias": "discordjs",
"symbol": "TextChannel#send",
"kind": "function",
"args": ["hello from invoke"],
"target": "channel",
"context": {
"channelId": "123456789012345678"
},
"dryRun": false,
"requirePreflightPass": true,
"allowWrite": true
}
}
```
### 6) Batch Invocation
```json
{
"mode": "bot",
"identityId": "default-bot",
"method": "automation.write",
"operation": "discord.exec.batch",
"params": {
"mode": "best_effort",
"haltOnPolicyBlock": false,
"maxParallelism": 4,
"dryRun": true,
"items": [
{
"packageAlias": "discordjs",
"symbol": "TextChannel#send",
"kind": "function",
"target": "channel",
"context": {
"channelId": "123456789012345678"
},
"args": ["hello from batch"]
}
]
}
}
```
## Legacy Dynamic Compatibility
Legacy operation strings are not supported. Use only vNext operations:
- `discord.meta.packages`
- `discord.meta.symbols`
- `discord.meta.preflight`
- `discord.meta.refresh`
- `discord.exec.invoke`
- `discord.exec.batch`
## Notes on Operation Counts
If you expect thousands of discovered symbols, this is by design:
- The MCP registry exposes a small, fixed operation surface.
- Package discovery is exposed through `discord.meta.packages`.
- Symbol discovery is exposed through `discord.meta.symbols`.
- Execution preflight is exposed through `discord.meta.preflight`.
- Catalog invalidation/refresh is exposed through `discord.meta.refresh`.
- Single and batch execution are exposed through `discord.exec.invoke` and `discord.exec.batch`.
- Runtime discovery includes `enum` exports (for example `ChannelType`, `ActivityType`).
- Startup logs print loaded package aliases and versions.
## Security Guidance
- Keep tokens private and rotate regularly.
- Use minimum Discord permissions required.
- Prefer `dryRun` for risky operations.
- Use `allowWrite` only when intended.
- Enable audit logging in production.
## Scripts
- `npm run build` - compile TypeScript
- `npm run dev` (or `bun run dev`) - build once, then run `tsc -w` + `node --watch` with forced pretty logs
- `npm start` - run compiled stdio server
- `npm run web` - run compiled Hono HTTP/SSE server on port 1455
## Codex + GH CLI Notes
Use `gh` to track upstream Codex MCP interface updates and keep this server aligned:
- `gh api repos/openai/codex`
- `gh api repos/openai/codex/contents/codex-rs/docs/codex_mcp_interface.md`
- `gh api "search/code?q=repo:openai/codex+mcp_tool_call.rs"`
