discord-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

bun run start        # run the MCP server
bun --watch run src/index.ts  # dev mode with auto-reload
bun run check        # TypeScript type-check (no emit)
bun run build        # compile TypeScript to dist/
bun test src         # run all tests
bun test src/discord/members.test.ts  # run a single test file

Architecture

This is a Bun + TypeScript MCP server that exposes Discord admin tools over Streamable HTTP transport. It uses Seyfert as the Discord client library and Zod for schema validation.

Startup flow

src/index.ts → createDiscordRuntime() → createMcpRuntime() → listen()

• createDiscordRuntime (src/discord/client.ts): Initializes a Seyfert HttpClient for REST-only mode. Optionally creates a Seyfert Client (gateway) when DISCORD_GATEWAY_ENABLED=true.
• createMcpRuntime (src/mcp/server.ts): Instantiates all Discord service classes, creates a McpServer per session, registers all tools, and starts a Bun.serve HTTP server. Sessions are tracked in a Map<string, SessionState>.

Layer structure

src/
  config/env.ts          — Zod env parsing → AppConfig
  discord/               — Service classes (one per domain area)
    base.ts              — DiscordBaseService (Shared logic: auth, dry-run, auditing)
    service.ts           — DiscordService (guilds, channels, roles)
    members.ts           — DiscordMembersService
    messages.ts          — DiscordMessagesService
    webhooks.ts          — DiscordWebhooksService
    threads.ts           — DiscordThreadsService
    special.ts           — DiscordSpecialService (invites, automod, emojis, stickers, soundboard)
    guild-settings.ts    — DiscordGuildSettingsService
    audit-logs.ts        — DiscordAuditLogsService
    scheduled-events.ts  — DiscordScheduledEventsService
    stage.ts             — DiscordStageService
    sticker-packs.ts     — DiscordStickerPacksService (public sticker pack endpoints)
    presence.ts          — DiscordPresenceService (gateway only)
  mcp/
    server.ts            — MCP HTTP transport, session management
    tools/
      register.ts        — Wires all tool handlers to McpServer
      helpers.ts         — success()/failure()/withToolResult() response builders
    schemas/             — Zod schemas for each tool's input validation
  lib/
    errors.ts            — ToolError class, normalizeError(), toolErrorResult()
    logging.ts           — Structured logger
  types/discord.ts       — Shared summary types (DiscordGuildSummary, etc.)