mcp-5etools-core

mcp-5etools Core Rules

Purpose

Treat this repository as an MCP server exposing 5eTools data to LLMs. The 5etools-src/ folder at project root is read-only input. Do not rewrite or reformat upstream data files.

High-level goals

1. Implement stable MCP tools/resources for search, fetch, and render of 5eTools entities.
2. Prefer 2024 rules when an entity exists in both 2014 and 2024, unless explicitly requested otherwise.
3. Ensure all generated text links back to fiveet://entity/{kind}/{source}/{slug} URIs.
4. Keep rendering deterministic, resolving common {@...} tags.

Architecture boundaries

• src/server.ts is the entry point; all file I/O and indexing stays under src/.
• The data path defaults to ./5etools-src. Allow override with FIVETOOLS_SRC_DIR env var.
• Avoid global state leakage; keep indices in a simple in-memory cache for now.

Tasks to prefer

• Add more {@tag} handlers in the renderer with unit tests.
• Add fuzzy search and ranking (e.g., minisearch) with facets.
• Add list_sources, get_rules_section, resolve_tag tools.
• Write schema/resource docs in ARCHITECTURE.md when types grow.

Tasks to avoid

• Editing anything inside 5etools-src/.
• Introducing non-deterministic rendering (e.g., random ordering, timestamps).
• Over-fetching: return resource_link when possible.

Coding standards

• TypeScript strict mode; no any in public types.
• Small, composable functions; prefer pure utilities for rendering.
• Keep dependencies minimal (MCP SDK, zod).

PR/commit hygiene

• One logical concern per PR.
• Update README/ARCHITECTURE when changing surfaces.
• Include quick tests for any new tag handler.

Prompts for in-IDE use

• When unsure, call a tool. Don’t hallucinate rules text.
• Prefer 2024 rules unless told otherwise.
• Always include source abbreviations in results.