D&D MCP Server

Gamemaster MCP 🐉

Um servidor abrangente Model Context Protocol MCP para gerenciar campanhas de Dungeons & Dragons assistidas por IA, construído com FastMCP 2.9.0+

Gamemaster MCP 🐉 tem como objetivo ser o Mestre de Masmorras definitivo assistido por IA para DnD 5e, fornecendo:

• Para Grupos: Um kit de ferramentas abrangente para ajudar o usuário a gerenciar campanhas de forma mais eficaz
• Para Jogadores Solo: Uma experiência virtual completa de DnD que facilita o jogo solo imersivo
• Para Construtores de Mundos: Ferramentas poderosas para auxiliar na criação de mundos de jogo ricos e interconectados

Construído sobre FastMCP, o servidor fornece modelos de dados estruturados e ferramentas inteligentes para gerenciar todos os aspectos de uma campanha de D&D, permitindo interação em linguagem natural por meio de clientes MCP.

🚧 Em construção 🚧

✨ Recursos

🌍 Gerenciamento de Campanha

A base do seu mundo de D&D. Cada campanha contém:

• Metadados Principais: Nome, descrição, cenário, nome do Mestre
• Personagens: Todos os personagens dos jogadores e suas fichas
• NPCs: Todos os personagens não jogadores do seu mundo
• Locais: Cidades, masmorras e pontos de interesse
• Missões: Histórias ativas e concluídas
• Estado do Jogo: Sessão atual, localização do grupo, condições do mundo

Todos os dados são salvos automaticamente e podem ser compartilhados entre sessões.

• Crie e gerencie múltiplas campanhas
• Alterne entre campanhas sem interrupções
• Acompanhe metadados da campanha (nome, descrição, Mestre, cenário)

📑 Gerenciamento de Personagens

Fichas de personagem completas de D&D 5e com:

• Atributos Principais: Pontuações de habilidade com modificadores calculados automaticamente
• Estatísticas de Combate: PV, CA, testes de resistência, resistências
• Inventário: Equipamento com rastreamento de peso e valor
• Conjuração: Magias preparadas, espaços de magia e CDs
• Progressão: Subidas de nível com desbloqueio automático de recursos

Os personagens evoluem conforme você joga - sofrendo dano, ganhando itens e subindo de nível.

• Fichas de personagem completas com estatísticas de D&D 5e
• Pontuações de habilidade com cálculo automático de modificadores
• Pontos de vida, classe de armadura e estatísticas de combate
• Gerenciamento de inventário e equipamento
• Suporte a conjuração

🧝 Gerenciamento de NPCs

Dê vida ao seu mundo com NPCs ricos que apresentam:

• Descrições: Aparência, personalidade, notas de voz
• Relacionamentos: Conexões com outros personagens/facções
• Locais: Onde vivem e frequentam
• Segredos: Motivações e conhecimentos ocultos
• Estatísticas: Referência rápida para combate, se necessário

NPCs podem ser vinculados a missões e locais para referência fácil.

• Crie e acompanhe personagens não jogadores
• Gerencie relacionamentos e locais
• Armazene descrições e notas

🗺️ Construção de Locais/Mundos

Crie cenários imersivos com:

• Descrições Detalhadas: Detalhes sensoriais e mapas
• Características Notáveis: Marcos, segredos, perigos
• Conexões: Áreas vinculadas para rotas de viagem
• Habitantes: NPCs e monstros presentes
• Lore: História e lendas locais

Os locais são atualizados conforme o grupo explora - adicionando áreas descobertas e mudando condições.

• Crie locais detalhados (cidades, masmorras, etc.)
• Acompanhe populações, governos e características notáveis
• Conecte locais e gerencie a geografia

💎 Gerenciamento de Missões

Acompanhe arcos de história e missões com:

• Objetivos: Passos claros para conclusão
• Acompanhamento de Status: Ativa/Concluída/Falhou
• Doadores e Recompensas: NPCs conectados e prêmios
• Sensibilidade ao Tempo: Prazos opcionais
• Caminhos Ramificados: Resoluções alternativas

O progresso da missão atualiza automaticamente o Estado do Jogo e o Registro de Aventuras.

• Crie missões com objetivos e recompensas
• Acompanhe o status e a conclusão das missões
• Vincule missões a NPCs e locais

⚔️ Gerenciamento de Combate

Acompanhe e execute encontros de combate dinâmicos com:

• Ordem de Iniciativa: Classificação automática com ajuste manual
• Acompanhamento de Turno: Destaque do ator atual e lembretes de turno
• Gerenciamento de Condições: Efeitos de status com rastreamento de duração
• Dano/Cura: Aplicar com cálculo automático de PV
• Estatísticas de Inimigos: Referência rápida para monstros/NPCs

Os dados de combate fluem para:

• Fichas de personagem (PV, condições)

• Estado do Jogo (encontro atual)

• Registro de Aventuras (eventos de combate)

• Acompanhamento de iniciativa

• Fluxo de combate baseado em turnos

• Planejamento de encontros de combate

⏰ Gerenciamento de Sessões

Organize suas sessões de jogo com:

• Notas de Sessão: Eventos e decisões importantes
• Acompanhamento de Presença: Quais jogadores estavam presentes
• Recompensas de XP: Acompanhe a progressão do personagem
• Distribuição de Saque: Tesouro encontrado e reivindicado
• Data do Jogo: Acompanhe a passagem do tempo no mundo

Os dados da sessão atualizam:

• Fichas de personagem (XP, itens)

• Estado do Jogo (número da sessão atual)

• Registro de Aventuras (resumo da sessão)

• Notas e resumos de sessão

• Acompanhamento de experiência e tesouro

• Presença de personagens

🏕️ Registro de Aventuras

A história viva da sua campanha:

• Tipos de Evento: Combate, Interpretação, Exploração, etc.
• Visão de Linha do Tempo: Progressão cronológica da história
• Pesquisável: Encontre momentos-chave rapidamente
• Tags e Importância: Destaque pontos principais da trama
• Vinculação de Sessão: Conecte eventos a sessões de jogo

O registro conecta-se a:

• Missões (atualizações de progresso)

• Locais (onde os eventos ocorreram)

• NPCs (quem estava envolvido)

• Registro abrangente de eventos

• Categorizado por tipo de evento (combate, interpretação, exploração, etc.)

• Pesquisável e filtrável

• Classificações de importância

🎮 Acompanhamento do Estado do Jogo

O instantâneo atual do seu mundo:

• Status do Grupo: Localização, recursos, condições
• Missões Ativas: Objetivos e progresso atuais
• Condições do Mundo: Clima, clima político
• Acompanhamento de Tempo: Data e hora no jogo
• Status de Combate: Detalhes do encontro atual

O Estado do Jogo conecta todos os outros modelos:

• Atualizações de ações dos personagens

• Conduz a simulação do mundo

• Informa decisões do Mestre de IA

• Localização e sessão atuais

• Nível e fundos do grupo

• Status de combate

• Acompanhamento de data no jogo

🎲 Ferramentas Utilitárias

• Rolagem de dados com vantagem/desvantagem
• Cálculos de pontos de experiência
• Suporte a mecânicas de D&D 5e

💾 Instalação

Pré-requisitos

• Python 3.12+
• uv (disponível no PATH do seu sistema)

Instalação do Usuário

1. Clone o repositório:

   git clone https://github.com/study-flamingo/gamemaster-mcp.git
   cd gamemaster-mcp
   

2. Crie um ambiente virtual e instale as dependências:

   uv venv
   uv pip install .
   

🏁 Executando o Servidor

Pela Linha de Comando

Para executar o servidor diretamente, primeiro ative o ambiente virtual:

# On macOS/Linux
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

Em seguida, execute o executável:

gamemaster-mcp

Alternativamente, use uv para executar o script sem ativar o ambiente:

uv run gamemaster-mcp

Com um Cliente MCP (ex.: Claude Desktop)

Configure seu cliente MCP para usar uv para executar o servidor. Você só precisa fornecer o caminho para a pasta do seu projeto como diretório de trabalho.

{
  "mcpServers": {
    "gamemaster-mcp": {
      "command": "uv",
      "args": [
        "run",
        "gamemaster-mcp"
      ],
      "cwd": "C:\\path\\to\\your\\gamemaster-mcp"
    }
  }
}

Nota: Substitua C:\\path\\to\\your\\gamemaster-mcp pelo caminho absoluto para o diretório do projeto.

🎛️ Recomendação de Prompt de Sistema

Para desempenho ideal, use um prompt de sistema que prepare o LLM para atuar como um assistente experiente de Mestre de Masmorras. Esse prompt deve orientar o modelo a entender o contexto do gerenciamento de campanhas de D&D e aproveitar as ferramentas fornecidas de forma eficaz.

📜 Exemplo de Prompt de Sistema

You are a master Dungeon Master (DM) or a Dungeon Master's Assistant, powered by the Gamemaster MCP server. Your primary role is to help users manage all aspects of their Dungeons & Dragons campaigns using a rich set of specialized tools. You are a stateful entity, always operating on a single, currently active campaign.

**Core Principles:**

1.  **Campaign-Centric:** All data—characters, NPCs, quests, locations—is stored within a single, active `Campaign`. Always be aware of the current campaign context. If a user's request seems to reference a different campaign, use the `list_campaigns` and `load_campaign` tools to switch context.
2.  **Structured Data:** You are working with structured data models (`Character`, `NPC`, `Quest`, `Location`, etc.). When creating or updating these entities, strive to populate them with as much detail as possible. If a user is vague, ask for specifics (e.g., "What is the character's class and race? What are their ability scores?").
3.  **Proactive Assistance:** Don't just execute single commands. Fulfill complex user requests by chaining tools together. For example, to "add a new character to the party," you should use `create_character`, then perhaps `add_item_to_character` to give them starting gear.
4.  **Information Gathering:** Before acting, use `list_` and `get_` tools to understand the current state. For instance, before adding a quest, you might `list_npcs` to see who could be the quest giver.
5.  **State Management:** Use the `get_game_state` and `update_game_state` tools to keep track of the party's current location, in-game date, and combat status.
6.  **Be a Storyteller:** While your primary function is data management, frame your responses in the context of a D&D game. You are not just a database; you are the keeper of the campaign's world.

**Interactive Session Zero:**

When a user wants to start a new campaign, initiate an interactive "Session Zero." Guide them through the setup process step-by-step, asking questions and using tools to build the world collaboratively. Use the following framework as a *loose* framework: it is more important to follow the user's prompting. However, be sure to establish the necessary parameters for each tool call.

1.  **Establish the Campaign:**
    *   **You:** "Welcome to the world of adventure! What shall we name our new campaign?" (Wait for user input)
    *   **You:** "Excellent! And what is the central theme or description of 'Campaign Name'?" (Wait for user input)
    *   *Then, use `create_campaign` with the gathered information.*

2.  **Build the Party:**
    *   **You:** "Now, let's assemble our heroes. How many players will be in the party?"
    *   *For each player, engage in a dialogue to create their character:*
    *   **You:** "Let's create the first character. What is their name, race, and class?"
    *   **You:** "Great. What are their ability scores (Strength, Dexterity, etc.)?"
    *   *Use `create_character` after gathering the core details for each hero.*

3.  **Flesh out the World:**
    *   **You:** "Where does our story begin? Describe the starting town or location."
    *   *Use `create_location`.*
    *   **You:** "Who is the first person the party meets? Let's create an NPC."
    *   *Use `create_npc`.*

4.  **Launch the Adventure:**
    *   **You:** "With our world set up, what is the first challenge or quest the party will face?"
    *   *Use `create_quest`.*
    *   **You:** "Session Zero is complete! I've logged the start of your first session. Are you ready to begin?"
    *   *Use `add_session_note`.*

Your goal is to be an indispensable partner to the Dungeon Master, co-creating the campaign's foundation so they can focus on telling a great story.

**In-Play Campaign Guidance:**

Once the campaign is underway, your focus shifts to dynamic management and narrative support:

1.  **Dynamic World:** Respond to player actions and tool outputs by dynamically updating the `GameState`, `NPC` statuses, `Location` details, and `Quest` progress.
2.  **Event Logging:** Every significant interaction, combat round, roleplaying encounter, or quest milestone should be logged using `add_event` to maintain a comprehensive `AdventureLog`.
3.  **Proactive DM Support:** Anticipate the DM's needs. If a character takes damage, suggest `update_character_hp`. If they enter a new area, offer `get_location` details.
4.  **Narrative Cohesion:** Maintain narrative consistency. Reference past events from the `AdventureLog` or `SessionNotes` to enrich descriptions and ensure continuity.
5.  **Challenge and Consequence:** When players attempt actions, consider the potential outcomes and use appropriate tools to reflect success, failure, or partial success, including updating character stats or game state.
6.  **Tool-Driven Responses:** Frame your narrative responses around the successful execution of tools. For example, instead of "The character's HP is now 15," say "You successfully heal [Character Name], their hit points now stand at 15."

Ferramentas Disponíveis (25+ Ferramentas FastMCP)

Gerenciamento de Campanha

• create_campaign - Crie uma nova campanha
• get_campaign_info - Obtenha informações da campanha atual
• list_campaigns - Liste todas as campanhas disponíveis
• load_campaign - Alterne para uma campanha diferente

Gerenciamento de Personagens

• create_character - Crie um novo personagem de jogador
• get_character - Obtenha detalhes da ficha do personagem
• update_character - Atualize as propriedades de um personagem (nome, estatísticas, PV, etc.).
• bulk_update_characters - Atualize vários personagens de uma vez (ex.: aplicar dano a todos).
• add_item_to_character - Adicione itens ao inventário
• list_characters - Liste todos os personagens

Gerenciamento de NPCs

• create_npc - Crie um novo NPC
• get_npc - Obtenha detalhes do NPC
• list_npcs - Liste todos os NPCs

Gerenciamento de Locais

• create_location - Crie um novo local
• get_location - Obtenha detalhes do local
• list_locations - Liste todos os locais

Gerenciamento de Missões

• create_quest - Crie uma nova missão
• update_quest - Atualize o status ou os objetivos da missão
• list_quests - Liste missões (opcionalmente filtradas por status)

Gerenciamento do Estado do Jogo

• update_game_state - Atualize o estado atual do jogo
• get_game_state - Obtenha o estado atual do jogo

Gerenciamento de Combate

• start_combat - Inicialize o combate com ordem de iniciativa
• end_combat - Encerre o encontro de combate
• next_turn - Avance para o turno do próximo participante

Gerenciamento de Sessões

• add_session_note - Adicione notas e resumo da sessão
• get_sessions - Obtenha todas as notas de sessão

Registro de Aventuras

• add_event - Adicione evento ao registro de aventuras
• get_events - Obtenha eventos (com filtragem e pesquisa)

Ferramentas Utilitárias

• roll_dice - Role dados com notação de D&D (ex.: "1d20", "3d6+2")
• calculate_experience - Calcule a distribuição de XP para encontros

💽 Estrutura de Dados

O servidor Gamemaster MCP organiza todos os dados da campanha em torno de um modelo central Campaign, que atua como o contêiner principal para todo o mundo do jogo. Esse design garante uma estrutura de dados coesa e interconectada, permitindo fácil gerenciamento e interação com vários elementos do jogo.

O sistema é construído em torno de uma estrutura de dados hierárquica com o modelo Campaign em seu núcleo. Todos os outros modelos se relacionam com a campanha ativa, como mostrado abaixo:

graph TD
    A[Campaign] --> B[GameState]
    A --> C[Character]
    A --> D[NPC]
    A --> E[Location]
    A --> F[Quest]
    A --> G[CombatEncounter]
    A --> H[SessionNote]
    B --> I[AdventureEvent]
    
    C --> J[Item]
    C --> K[Spell]
    C --> L[AbilityScore]
    C --> M[CharacterClass]
    C --> N[Race]
    
    style A fill:#f9f,stroke:#333,stroke-width:4px

Veja como os modelos de dados principais em src/gamemaster_mcp/models.py interagem:

• Campaign: O modelo fundamental. Ele encapsula todos os dados específicos da campanha, incluindo:

  • characters: Um dicionário de modelos Character, representando personagens de jogadores. Cada Character é um modelo complexo composto por CharacterClass, Race, AbilityScore (para estatísticas principais), Item (para inventário e equipamento) e Spell (para magias conhecidas).
  • npcs: Um dicionário de modelos NPC, representando personagens não jogadores. NPCs podem ser vinculados a modelos Location.
  • locations: Um dicionário de modelos Location, definindo lugares dentro do mundo da campanha. Locais podem listar NPCs associados e conexões com outros locais.
  • quests: Um dicionário de modelos Quest, acompanhando missões em andamento e concluídas. Missões podem referenciar NPCs como doadores.
  • encounters: Um dicionário de modelos CombatEncounter, detalhando cenários de combate planejados ou ativos. Encontros podem ser vinculados a locais específicos.
  • sessions: Uma lista de modelos SessionNote, fornecendo resumos e detalhes para cada sessão de jogo jogada na campanha.
  • game_state: Um único modelo GameState, que captura as condições dinâmicas e em tempo real da campanha, como localização atual, missões ativas e fundos do grupo. Esse modelo é crucial para entender o contexto imediato do jogo.

• GameState: Embora parte do Campaign, o GameState desempenha um papel fundamental em refletir o estado atual do mundo. Ele influencia e é influenciado por outros modelos:

  • current_location pode apontar para um modelo Location.
  • active_quests referencia títulos de Quest.
  • Mudanças no status de Character (ex.: hit_points_current) ou no status de Quest (active, completed) impactam diretamente o GameState.

• AdventureEvent: Este modelo é usado para registrar ocorrências significativas ao longo da campanha. Embora não esteja diretamente aninhado dentro de Campaign (é armazenado globalmente), instâncias de AdventureEvent frequentemente referenciam elementos dos dados do Campaign, como characters_involved e location. Isso fornece um registro histórico para entender eventos passados e a progressão narrativa.

🖥️ Desenvolvimento

Fluxo de Trabalho de Desenvolvimento

Se você quiser contribuir com o projeto, a configuração é um pouco diferente.

1. Siga os passos da Instalação do Usuário para clonar o repositório e configurar o ambiente virtual.

2. Instale em modo editável com dependências de desenvolvimento:

   uv pip install -e .[dev]
   

   Isso instala o projeto de forma que suas alterações de código sejam refletidas imediatamente, sem precisar reinstalar. Também instala ferramentas para testes e linting.

Executando Testes

Para executar a suíte de testes, use o seguinte comando:

uv run pytest

📜 Licença

Licença MIT