# dynamic-discord-bot-api-mcp

Production-oriented stdio MCP gateway exposing stable Discord HTTP operations that explicitly support bot-token authentication. It installs a checked-in, self-refreshing OpenAPI catalog and exposes exactly five generic tools—never one tool per endpoint.

Discord's OpenAPI specification is a public preview and may be incomplete. This project consumes only stable `openapi.json`; official Discord documentation remains authoritative.

## Scope and architecture

Refresh filters every operation by explicit `BotToken` security metadata, then applies a small fail-closed classifier for OAuth, interaction-token, webhook-token, Social SDK/lobby, and ambiguous routes. It retains only transitively referenced component schemas. Excluded endpoints cannot be searched, inspected, or called.

Gateway HTTP metadata such as `/gateway/bot` may remain because it supports bot authentication; Gateway WebSockets and events do not. Also excluded: OAuth exchange, bearer/user authorization, self-bots, Voice WebSocket/RTP, RPC, Activities/Embedded App/Social SDKs, interaction receivers/callbacks, incoming webhook servers, webhook-token execution, preview endpoints, and arbitrary HTTP requests.

Runtime resolves one active local MCP workspace root, reloads its `.env` before every call, and caches a client only while security-relevant configuration is unchanged. Schema refresh uses validation, atomic rename, concurrent coalescing, and cached fallback. JSON audit events go to stderr without values or secrets.

## Install

```sh
npm install -g dynamic-discord-bot-api-mcp
discord-bot-api-mcp
```

From GitHub:

```sh
npm install -g github:PrimeUpYourLife/dynamic-discord-bot-api-mcp
```

MCP client configuration:

```json
{"mcpServers":{"discord":{"command":"discord-bot-api-mcp"}}}
```

Codex `~/.codex/config.toml`:

```toml
[mcp_servers.discord]
command = "discord-bot-api-mcp"
```

Place `DISCORD_BOT_TOKEN` in active repository `.env`. Process environment overrides startup-directory `.env`; active workspace `.env` overrides both. Multiple, failed, non-local, or non-directory MCP roots fail closed. Catalog tools need no token.

## Five tools

- `discord_search_endpoints`: fuzzy search IDs, methods, routes, categories, descriptions, and parameters.
- `discord_get_endpoint`: exact canonical ID or OpenAPI operation-ID lookup.
- `discord_get_type`: component-schema lookup.
- `discord_call_endpoint`: validate and execute a cataloged bot endpoint.
- `discord_refresh_schema`: fetch, filter, validate, and atomically install stable schema.

Examples:

```json
{"search":"create message","limit":5}
{"endpoint":"create_message"}
{"endpoint":"POST /channels/{channel_id}/messages","pathParameters":{"channel_id":"123456789012345678"},"body":{"content":"Hello from MCP"}}
```

Upload example:

```json
{"endpoint":"create_message","pathParameters":{"channel_id":"123456789012345678"},"body":{"content":"image"},"files":[{"path":"./uploads/image.png","filename":"image.png","contentType":"image/png"}]}
```

Uploads use `payload_json` and deterministic `files[n]` parts/attachment IDs. Paths resolve from active root and must remain within configured realpath roots. Base64 descriptors are also supported.

Validation separates path, query, and body values; handles required fields, nested objects, arrays, enums, nullable values, refs and unions. Snowflakes remain strings. Arrays become repeated query keys. DELETE and centrally classified destructive operations require `confirm: true`. Optional audit reason is percent-encoded.

Errors are structured (`ENDPOINT_NOT_FOUND`, `ENDPOINT_NOT_ALLOWED`, `CONFIRMATION_REQUIRED`, `BOT_TOKEN_MISSING`, `VALIDATION_ERROR`, `DISCORD_API_ERROR`, `REQUEST_ERROR`, project-root errors, or `SCHEMA_REFRESH_FAILED`). Discord numeric codes and nested validation errors are preserved; raw bodies, stack traces, and tokens are not.

## Configuration

| Variable | Default | Meaning |
|---|---:|---|
| `DISCORD_BOT_TOKEN` | unset | Bot token; calls fail safely when absent |
| `DISCORD_API_BASE_URL` | `https://discord.com/api/v10` | Fixed API origin |
| `DISCORD_ENDPOINT_ALLOWLIST` | `*` | Comma-separated IDs/operation IDs with `*` globs |
| `DISCORD_REQUEST_TIMEOUT_MS` | `30000` | Per-attempt timeout |
| `DISCORD_REQUEST_RETRIES` | `2` | Retry count |
| `DISCORD_RATE_LIMIT_PER_SECOND` | `45` | Local global safety rate |
| `DISCORD_RATE_LIMIT_BURST` | `50` | Local burst |
| `DISCORD_SCHEMA_MAX_AGE_HOURS` | `24` | Refresh threshold |
| `DISCORD_SCHEMA_PATH` | bundled catalog | Alternate catalog path |
| `DISCORD_LOCAL_FILE_ROOTS` | active root | Platform-delimited upload roots |
| `DISCORD_MAX_UPLOAD_BYTES` | `10485760` | Per-file limit |
| `DISCORD_ALLOW_UNKNOWN_PARAMETERS` | `false` | Validation escape hatch |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |

Use narrow production allowlists. Caller cannot supply URLs, methods, authorization, or headers. Requests always use configured base URL plus catalog route, `Authorization: Bot …`, and valid package User-Agent.

Discord response headers and 429 payloads control per-route/bucket and global waits; limits are not hard-coded. Fractional `retry_after` is honored. 429s retry within configured bound. 5xx and transport retries are limited to safe GET requests, preventing duplicate messages or moderation actions.

## Development

```sh
npm ci
npm run refresh-schema
npm run check
npm test
npm run build
```

Tests mock network access. Daily workflow refreshes catalog and commits only generated-data changes. Manual publish workflow verifies tag/version and uses npm trusted publishing via GitHub OIDC; prereleases publish under `next`.