AI导哈

DnD 5e MCP服务器

一个通过Model Context Protocol向LLMs暴露D&D 5e SRD GraphQL API的服务器，支持Claude Desktop和ChatGPT。

  • by carromeu
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 carromeu/mcp-dnd-5e

使用说明

DnD 5e MCP服务器

MCP 服务器展示 GraphQL API D&D 5e SRD 对于LLMS VIA 模型上下文协议与Claude Desktop和ChatGPT兼容。

功能

  • 2工具: graphql_query （查询执行） + explore_schema （动态类型内省）
  • 1个提示: dnd5e_guide — 具有示例的详细指南，可应要求提供 player/dm/general 上下文
  • instructions 自动注入客户端系统提示符（ schema， Union types， typed filters）
  • 缓存Redis 基于元数据的 stale-while-revalidate
  • 双重运输：流式HTTP+SSE（legado）
  • 速率限制 按 IP， 可配置 CORS， graceful shutdown
  • Docker Compose 两项服务的健康检查

快速开始

1. 设置环境变量

cp .env.example .env
# Editar .env se necessário (os defaults funcionam para deploy local)

2. 抬起集装箱

docker compose up --build -d

等待这两项服务保持健康：

docker compose ps
# NAME          STATUS                 PORTS
# mcp-mcp-1     Up (healthy)          0.0.0.0:3000->3000/tcp
# mcp-redis-1   Up (healthy)          6379/tcp

3. 检查

curl http://localhost:3000/health
# {"status":"ok","redis":true,"activeSessions":0,"uptime":...}

完全重建

docker compose down
docker compose up --force-recreate --build --remove-orphans -d

MCP 客户端配置

克劳德桌面版

添加到 claude_desktop_config.json （设置→ 开发者→ 编辑配置）：

{
  "mcpServers": {
    "dnd-5e": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

保存后重新启动 Claude 桌面 。

生产

{
  "mcpServers": {
    "dnd-5e": {
      "url": "https://mcp.dnd.carromeu.com/mcp"
    }
  }
}

环境变量

变量 Default 描述
PORT 3000 Porta mapeada无主机（Docker）
NODE_ENV production 环境
GRAPHQL_ENDPOINT https://www.dnd5eapi.co/graphql URL做上游GraphQL
UPSTREAM_TIMEOUT 30000 上游超时（ms）
CACHE_TTL 3600 静态缓存（segundos）
RATE_LIMIT_WINDOW 60000 速率限制窗口（ms）
RATE_LIMIT_MAX 60 每个窗口的 IP 请求
MAX_SESSIONS 100 会话并发（HTTP+SSE）
SESSION_IDLE_TTL 1800000 停机时间（ms）
MAX_RESPONSE_SIZE 102400 最大响应大小（字节）
CORS_ORIGIN * CORS的允许来源

地方 发展

没有 Docker（需要 Redis 单独运行）：

npm install
npm run dev     # tsx com hot reload

构建和运行：

npm run build
npm start

端点

方法 路径 描述
POST /mcp 流式HTTP--init+请求
GET /mcp 流式HTTP——SSE流式传输
DELETE /mcp 可流式传输的HTTP-encerrar会话
GET /sse SSE 传统 — 建立连接
POST /messages SSE 传统 — 发送消息
GET /health 健康检查（扫描电镜速率限制）

建筑

有关架构、设计决策和技术堆栈的完整技术详情，请参阅 docs/tech-spec.md.

技术栈

  • 运行时：Node.js 22 LTS（Alpine）+TypeScript 5.x
  • MCP-SDK: @modelcontextprotocol/sdk 1.27.x
  • 超文本传输协议：快递5.x
  • 图查询语言: graphql-request 7.x com rawRequest() + errorPolicy: 'all'
  • 缓存：Redis 7（Alpine）通过 ioredis 5.x
  • 基础设施：Docker多阶段构建+Docker编写

许可证

麻省理工学院

相关 MCP