Mnehmos Open5e MCP

mnehmos.open5e.mcp

MCP服务器 Open5e -查询D&D 5e游戏数据，并为开源数据库做出贡献

  ](https://nodejs.org)

双模MCP服务器，提供：

• 消费者模式：从22多本源书中查询法术、怪物、物品、条件等
• 贡献者模式：验证条目，检查冲突，根据实时API进行差异，并生成PR-就绪JSON
• RAG开发者聊天机器人：搜索Open5e存储库文档并与之聊天

特性

安装

npm

npm install -g mnehmos.open5e.mcp

来源

git clone https://github.com/Mnehmos/mnehmos.open5e.mcp.git
cd mnehmos.open5e.mcp
npm install
npm run build

Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "mnehmos.open5e.mcp": {
      "command": "node",
      "args": ["path/to/mnehmos.open5e.mcp/dist/index.js"]
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "mnehmos.open5e.mcp": {
      "command": "mnehmos-open5e-mcp"
    }
  }
}

快速开始

搜索拼写

Search: "fireball"
→ Returns Fireball, Delayed Blast Fireball from multiple sources

得到一个怪物

Get: monsters/goblin
→ Full stat block with AC, HP, abilities, actions, environments

验证贡献

Validate: { name: "Custom Spell", level: 3, school: "Evocation", ... }
→ Errors for missing required fields
→ Suggestions for slug format
→ Warnings for unusual values

工具参考

消费者工具

search

使用可选过滤器搜索所有Open5e资源。

search({
  query: "fireball",
  resource_type: "spells",      // optional: spells, monsters, items, etc.
  document_slug: "srd-2014",    // optional: filter by source book
  limit: 10                     // optional: max results (default 20)
})

返回结果 slug, key （对于v2资源）， name, excerpt，以及 web_url.

get

通过slug获取单个资源。Auto尝试v2资源的常用文档前缀。

// Simple slug - auto-discovers the full key
get({ resource_type: "spells", slug: "fireball" })
// → Finds srd-2024_fireball or srd-2014_fireball

// Full key - direct lookup
get({ resource_type: "spells", slug: "srd-2014_fireball" })

list

列出具有筛选器的资源（支持分页）。

list({
  resource_type: "monsters",
  cr: 3,                        // Challenge Rating
  document_slug: "wotc-srd",    // Source book
  type: "Dragon",               // Creature type
  limit: 20,
  offset: 0
})

list({
  resource_type: "spells",
  level: 3,                     // Spell level (0-9)
  school: "Evocation",          // Spell school
  document_slug: "srd-2014"
})

batch_get

并行获取多个资源（最多50个）。

batch_get({
  requests: [
    { resource_type: "monsters", slug: "goblin" },
    { resource_type: "monsters", slug: "kobold" },
    { resource_type: "conditions", slug: "blinded" }
  ]
})

list_documents

列出所有可用的源书。

list_documents()
// → srd-2014, srd-2024, tob, tob2, tob3, a5e-ag, bfrd, etc.

list_endpoints

列出所有带有版本信息的API终结点。

list_endpoints()
// → spells (v2), monsters (v1), conditions (v2), etc.

贡献者工具

validate_entry

根据Open5e模式验证草稿条目。

validate_entry({
  resource_type: "spells",
  data: {
    name: "Test Spell",
    slug: "test-spell",
    level: 3,
    school: "Evocation",
    // ... other fields
  },
  strict: false  // optional: fail on warnings
})

退货：

• valid：boolean
• errors：架构冲突数组
• warnings：异常但有效的值
• suggestions：有用提示（slug格式，有效枚举）

check_slug

检查是否存在蛞蝓或是否会碰撞。

check_slug({
  resource_type: "monsters",
  slug: "goblin",
  document_slug: "wotc-srd",     // optional
  original_slug: "goblin-old"    // optional: detect mutations
})

退货：

• exists：boolean
• is_mutation：boolean（slug已从原始值更改）
• collision_risk：“无”|“相同文档”|“不同文档”
• existing_entry：详细信息（如果存在）

diff

将草稿条目与API实时版本进行比较。

diff({
  resource_type: "monsters",
  slug: "goblin",
  draft: {
    name: "Goblin",
    hit_points: 10,  // Changed from 7
    // ... partial or full entry
  },
  ignore_fields: ["page_no"]  // optional
})

返回每个字段的差异 type：“添加”|“删除”|“修改”。

normalize

清理和规范条目数据。

normalize({
  resource_type: "spells",
  data: {
    name: "test   spell",
    desc: "A   spell   with   bad   spacing.\n\nAnd extra   newlines."
  },
  options: {
    fix_whitespace: true,
    fix_markdown: true,
    standardize_names: true,
    generate_slug: true
  }
})

generate_pr_json

使用文件路径和检查表生成PR就绪JSON。

generate_pr_json({
  resource_type: "spells",
  document_slug: "srd-2014",
  operation: "add",  // or "modify"
  data: { /* validated entry */ }
})

退货：

• json_output：格式化JSON字符串
• file_path：将文件放置在何处（例如。， data/srd-2014/spells/test-spell.json)
• validation：飞行前验证结果
• checklist：PR提交清单

RAG工具

RAG工具连接到Open5e开发者聊天机器人，该聊天机器人对整个Open5e api和Open5e（前端）存储库进行索引。

rag_health

检查RAG服务状态。

rag_health()
// → { healthy: true, chunks: 484, vectors: 484, sources: 214 }

rag_stats

获取索引统计信息。

rag_stats()
// → Project info, chunk/vector counts, embedding status

rag_sources

列出所有带有GitHub URL的索引源。

rag_sources()
// → README.md, CONTRIBUTING.md, AGENTS.md, models/*.py, views/*.py, etc.

rag_search

搜索存储库文档。

rag_search({
  query: "how to add a new monster",
  mode: "hybrid",    // semantic, keyword, or hybrid
  top_k: 5
})

返回包含分数、源URL和位置的块。

rag_chat

与AI讨论Open5e的开发。

rag_chat({
  message: "How do I add a new monster to the Open5e database?",
  history: [],  // optional: conversation history
  top_k: 5      // optional: context chunks
})

返回包含源引用的详细答案。

元工具

health_check

检查API连接和缓存状态。

health_check()
// → { api_reachable: true, api_latency_ms: 628, cache_status: {...}, version: "0.1.0" }

可用源书籍

使用 list_documents() 查看完整列表。

资源类型

使用模式

游戏大师：构建邂逅

// Find CR 3 monsters from the SRD
const monsters = await list({
  resource_type: "monsters",
  cr: 3,
  document_slug: "wotc-srd"
});

// Get full details for selected monsters
const details = await batch_get({
  requests: monsters.results.slice(0, 5).map(m => ({
    resource_type: "monsters",
    slug: m.slug
  }))
});

贡献者：添加新拼写

// 1. Draft the spell
const draft = {
  name: "Arcane Bolt",
  slug: "arcane-bolt",
  level: 0,
  school: "Evocation",
  casting_time: "1 action",
  range: "120 feet",
  verbal: true,
  somatic: true,
  material: false,
  concentration: false,
  ritual: false,
  duration: "Instantaneous",
  desc: "You hurl a bolt of arcane energy at a creature...",
  document__slug: "homebrew"
};

// 2. Validate
const validation = await validate_entry({
  resource_type: "spells",
  data: draft
});

// 3. Check for collisions
const slugCheck = await check_slug({
  resource_type: "spells",
  slug: "arcane-bolt"
});

// 4. Generate PR JSON
const prData = await generate_pr_json({
  resource_type: "spells",
  document_slug: "homebrew",
  operation: "add",
  data: draft
});

学习：理解代码库

// Search for how monsters are modeled
const results = await rag_search({
  query: "Monster model fields actions abilities",
  top_k: 5
});

// Ask the chatbot
const answer = await rag_chat({
  message: "What fields are required for a monster entry in v1?"
});

整合

rpg mcp

此服务器旨在与 rpg mcp 在游戏过程中查找活体生物：

// Replace hardcoded creature presets with Open5e lookups
const creature = await open5e.get({
  resource_type: "monsters",
  slug: "adult-red-dragon"
});

任务守护者AI

Quest Keeper AI前端中用于社区内容创建的Surface贡献者工作流程。

发展

设置

npm install
npm run build

测试

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

脚本

项目结构

src/
├── index.ts          # MCP server entry point, tool registration
├── types.ts          # Shared TypeScript types
├── api/              # Open5e API client
├── cache/            # Response caching
├── contributor/      # Validation, diff, PR generation
├── schema/           # Zod schemas for all resource types
└── utils/            # Helpers, slug handling

API 参考

• Open5e API: https://api.open5e.com
• API 文档: https://open5e.com/api-docs
• GitHub 仓库: https://github.com/open5e/open5e-api
• Discord 的中文翻译是“不和谐”或“纷争”。: https://discord.gg/9RNE2rY

贡献

1. 分叉存储库
2. 创建要素分支
3. 运行测试： npm test
4. 提交拉取请求

许可证

MIT© 马尼赫莫斯

______________________________________________________________________

Mnehmos MCP生态系统的一部分

• mnehmos.oda.mcp -文件系统和shell操作
• mnehmos.synch.mcp -代理记忆和切换
• rpg mcp -RPG游戏引擎