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

{
  "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({
  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)
})

// 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({
  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({
  requests: [
    { resource_type: "monsters", slug: "goblin" },
    { resource_type: "monsters", slug: "kobold" },
    { resource_type: "conditions", slug: "blinded" }
  ]
})

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

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

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

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

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

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({
  resource_type: "spells",
  document_slug: "srd-2014",
  operation: "add",  // or "modify"
  data: { /* validated entry */ }
})

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

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

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

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

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_reachable: true, api_latency_ms: 628, cache_status: {...}, version: "0.1.0" }

// 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?"
});

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

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