# Grimoire

> "World's okayest MCP-powered D&D 5e spellbook"

[![smithery badge](https://smithery.ai/badge/@Linell/grimoire-mcp)](https://smithery.ai/server/@Linell/grimoire-mcp)

A Model Context Protocol (MCP) server that provides D&D 5e spell information through a set of tools. Built as a learning project to explore the [Smithery](https://smithery.ai) MCP deployment platform.

## Features

- Spell search with filters (level, school, class, name, ritual, concentration)
- Detailed spell information including casting time, components, and descriptions
- Class-specific spell lists by level
- Spell school and character class references

## Powered by D&D 5e API

This project is entirely powered by the [D&D 5e API](https://5e-bits.github.io/docs/) - a comprehensive, community-driven API that provides detailed information about D&D 5e spells, monsters, and more.

## Quick Start

### Prerequisites

- Node.js 18+ 
- npm or yarn

### Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/grimoire.git
cd grimoire
```

2. Install dependencies:
```bash
npm install
```

3. Start the development server:
```bash
npm run dev
```

## Available Tools

- `search_spells` - Search for spells with various filters
- `get_spell` - Get detailed information about a specific spell
- `list_schools` - List all available D&D 5e spell schools
- `list_classes` - List all available spellcasting character classes
- `get_class_spells` - Get spells available to a specific class at a given level

## Built with Smithery

This project is deployed using [Smithery](https://smithery.ai), a platform for deploying MCP servers that makes it easy to deploy, scale, and manage MCP servers with zero configuration.

## Development

### Project Structure

```
grimoire/
├── src/
│   └── index.ts          # Main MCP server implementation
├── package.json          # Dependencies and scripts
├── smithery.yaml         # Smithery deployment configuration
└── README.md            # This file
```

### Local Development

Start the development server:
```bash
npm run dev
```

The server will be available at the local endpoint provided by Smithery CLI.

### Configuration

- `debug` (boolean): Enable debug logging (default: false)

## Contributing

Contributions are welcome! This is a learning project, so feel free to:

- Add new spell-related tools
- Improve error handling
- Enhance the documentation
- Add tests
- Suggest new features

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [D&D 5e API](https://5e-bits.github.io/docs/) for providing comprehensive spell data
- [Smithery](https://smithery.ai) for the MCP deployment platform
- The D&D 5e community for maintaining comprehensive game data

## Links

- [Smithery Documentation](https://smithery.ai/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [D&D 5e API Documentation](https://5e-bits.github.io/docs/)