Architecture

Trace a tool call from MCP input to Discord REST. Tools live in a Sapphire-style registry and pass through six middleware stages: telemetry → default guild → validation → category gate → preconditions → audit. The REST adapter adds bulkhead, circuit-breaker, retry, and timeout policies. Optional Gateway mode emits notifications for five URI keys and falls back to REST-only startup when the Gateway connection cannot boot.

System design

graph TD
  Client[MCP client] --> Transport[InMemoryTransport / stdio]
  Transport --> Server[McpServer]
  Server --> MW[Middleware chain]
  MW --> Tool[Tool piece]
  Tool --> REST[Resilient REST adapter]
  REST --> Discord[Discord REST API]
  Tool -. optional .-> Sampling[Client LLM via sampling]
  Server -. optional .-> Gateway[Gateway client]
  Gateway --> DiscordWS[Discord Gateway WebSocket]

• MCP client sends JSON-RPC tools/call over stdio.
• Transport owns JSON-RPC framing; production uses stdio, tests use InMemoryTransport.
• McpServer bridges MCP to the piece registry and hosts the middleware, tool, precondition, and resource stores.
• Middleware chain applies telemetry, default guild, validation, category gate, preconditions, and audit before execution.
• Tool piece implements one of the 192 tools, using Discord REST or, for intelligence, MCP sampling back to the client.
• REST adapter wraps @discordjs/rest in Cockatiel bulkhead, circuit-breaker, retry, and timeout policies.
• Gateway client is optional under --gateway; it emits notifications for five URI keys but does not add resource list/read handlers.

Registry and repository shape

discord-mcp uses Sapphire’s explicit “piece + store” model. Tool and Precondition classes are registered by server.ts; boot does not scan the filesystem. The stores provide lookup by name, while the container supplies the configured REST client, logger, and config to tool pieces.

This keeps tool construction consistent, but registration is intentionally explicit: adding a tool also requires adding it to server.ts.

packages/
  mcp-core/                # Tools, middleware, resilience policy
    src/
      tools/               # 192 tool definitions
      middleware/          # 6 stages + compose
      preconditions/       # ConfirmRequired, CategoryEnabled
      pieces/              # Tool and Precondition base classes
      stores/              # Tool/precondition lookup + resources
      rest/                # Cockatiel-wrapped @discordjs/rest
      gateway/             # Optional discord.js client
      pipeline/            # mcp_pipeline executor
      errors/              # Error hierarchy + formatErrorForUser
      audit/               # Audit sinks + redaction
      telemetry/           # OTel boot + metrics
  mcp-server/              # CLI and stdio transport wiring

mcp-core has no transport assumptions. mcp-server is the thin shell that wires it to stdio, OpenTelemetry, and signal handling.

Sources: server.ts, Tool.ts, and ToolStore.ts.

Note

The middleware boundary centralizes validation, category restriction, confirmation, audit, and observability. Tools still need registration and tests, but do not reimplement those controls.

Explore a subsystem

Middleware chain The six stages wrapping every tool call, why their order matters, and which controls run before execution.

Components V2 The V2 layout primitives (Container, Section, MediaGallery, ActionRow), the schema validator, the preview renderer, the 5 templates, and the flags=32768 contract.

Pipeline The mcp_pipeline executor: sequential fail-fast calls, {{stepN.path}} interpolation, recursion guard, and partial-failure semantics.

Gateway The optional --gateway mode: five notification URI keys, five handlers, in-memory subscriptions, debounce, and REST-only fallback.

Error handling The error hierarchy (client vs server), formatErrorForUser shape, recovery-hint contract, DRY_RUN_PREVIEW pattern, Cockatiel mappings.

Confirmation The __confirm:true + MCP_DRY_RUN=false mechanical guard used by 29 explicitly registered high-risk tools-and its limits.

Sampling Zero-API-key intelligence: how the 5 intelligence tools call back into the client’s LLM via MCP sampling, with a graceful host_llm_should_process fallback.

Rate limits Discord’s global and route buckets, the @discordjs/rest scheduler, and the boundary with local resilience policies.

Choose a path

If you’re a contributor, start with the system design above, then jump to the subsystem you’re touching. The deep-dive pages each link to source files via GitHub permalinks so you can read implementation in a tab.

If you’re an operator trying to understand a production behavior, the fastest path is usually:

1. Look up the env var or error code on the relevant Operations page.
2. Follow that page’s “Related” links into the architecture deep-dive.
3. Use the source-map table at the bottom of the architecture page to find the exact file responsible.

The architecture pages assume familiarity with Discord’s API model and basic TypeScript. We do not re-explain MCP itself - see modelcontextprotocol.io for that.

Related

• Get started - install and run the server.
• Tools - auto-generated reference for all 192 tools.
• Recipes - multi-tool workflows that exercise these subsystems.
• Operations - production-running concerns: telemetry, resilience, audit, client matrix.