Kanka

Um servidor MCP para integração com a API do Kanka, uma ferramenta de construção de mundos e gerenciamento de campanhas para RPGs de mesa.

GitHub
4
Experimente este MCPPatrocinado

Documentação

MCP-Kanka

Servidor MCP (Model Context Protocol) para integração com a API do Kanka. Este servidor fornece ferramentas para assistentes de IA interagirem com campanhas do Kanka, permitindo operações CRUD em vários tipos de entidades como personagens, locais, organizações e mais.

Este pacote foi projetado especificamente para atender às necessidades do Teghrim, mas pode ser útil para outras pessoas que trabalham com Kanka e MCP.

Recursos

  • Gerenciamento de Entidades: Criar, ler, atualizar e excluir entidades do Kanka
  • Busca e Filtro: Buscar entidades por nome com correspondência parcial, filtrar por tipo/tags/data
  • Operações em Lote: Processar múltiplas entidades em uma única solicitação
  • Gerenciamento de Posts: Criar, atualizar e excluir posts (notas) em entidades
  • Suporte a Markdown: Conversão automática entre Markdown e HTML com preservação de menções a entidades
  • Segurança de Tipos: Anotações de tipo completas e validação
  • Filtragem no Cliente: Filtragem aprimorada além das limitações da API
  • Suporte a Sincronização: Sincronização eficiente com rastreamento de timestamps e o recurso nativo lastSync do Kanka
  • Rastreamento de Timestamps: Todas as entidades incluem timestamps de created_at e updated_at

Requisitos

  • Python 3.10 ou superior (3.13.5 recomendado)
  • Token da API do Kanka e ID da campanha

Instalação

A partir do PyPI

pip install mcp-kanka

A partir do código-fonte (usando uv)

git clone https://github.com/twistymaze/mcp-kanka.git
cd mcp-kanka
uv sync --all-groups
uv pip install -e .

A partir do código-fonte (usando pip)

git clone https://github.com/twistymaze/mcp-kanka.git
cd mcp-kanka
pip install -e .

Início Rápido

Adicionando ao Claude Desktop

  1. Configure suas variáveis de ambiente:

    • KANKA_TOKEN: Seu token da API do Kanka
    • KANKA_CAMPAIGN_ID: Seu ID de campanha

  2. Adicione à configuração do Claude Desktop:

{
  "mcpServers": {
    "kanka": {
      "command": "python",
      "args": ["-m", "mcp_kanka"],
      "env": {
        "KANKA_TOKEN": "your-token",
        "KANKA_CAMPAIGN_ID": "your-campaign-id"
      }
    }
  }
}

Usando com Claude Code CLI

claude mcp add kanka \
  -e KANKA_TOKEN="your-token" \
  -e KANKA_CAMPAIGN_ID="your-campaign-id" \
  -- python -m mcp_kanka

Tipos de Entidades Suportados

  • Personagem - Personagens dos jogadores (PJs), personagens não jogadores (PNJs)
  • Criatura - Tipos de monstros, animais, criaturas não únicas
  • Local - Lugares, regiões, construções, pontos de referência
  • Organização - Guildas, governos, seitas, empresas
  • Raça - Espécies, ancestralidades
  • Nota - Conteúdo interno, resumos de sessão, notas do mestre (privadas por padrão)
  • Diário - Resumos de sessão, narrativas, crônicas
  • Missão - Missões, objetivos, arcos de história

Ferramentas Disponíveis (9 no Total)

Operações com Entidades

find_entities

Buscar e filtrar entidades com opções abrangentes e metadados de sincronização.

Parâmetros:

  • entity_type (opcional): Tipo para filtrar - character, creature, location, organization, race, note, journal, quest
  • query (opcional): Termo de busca para pesquisa de texto completo em nomes e conteúdos
  • name (opcional): Filtrar por nome (correspondência parcial por padrão, ex.: "Test" corresponde a "Test Character")
  • name_exact (opcional): Usar correspondência exata de nome em vez de parcial (padrão: false)
  • name_fuzzy (opcional): Ativar correspondência difusa para tolerância a erros de digitação (padrão: false)
  • type (opcional): Filtrar pelo campo Tipo definido pelo usuário (ex.: 'NPC', 'Cidade')
  • tags (opcional): Matriz de tags - retorna entidades que possuem TODAS as tags especificadas
  • date_range (opcional): Apenas para diários - filtrar por intervalo de datas com datas start e end
  • limit (opcional): Resultados por página (padrão: 25, máximo: 100, use 0 para todos)
  • page (opcional): Número da página para paginação (padrão: 1)
  • include_full (opcional): Incluir detalhes completos da entidade (padrão: true)
  • last_synced (opcional): Timestamp ISO 8601 para obter apenas entidades modificadas após este horário

Retorna:

{
  "entities": [...],
  "sync_info": {
    "request_timestamp": "2024-01-01T12:00:00Z",
    "newest_updated_at": "2024-01-01T11:30:00Z",
    "total_count": 150,
    "returned_count": 25
  }
}

create_entities

Criar uma ou mais entidades com conteúdo em Markdown.

Parâmetros:

  • entities: Matriz de entidades para criar, cada uma com:
    • entity_type (obrigatório): Tipo de entidade a criar
    • name (obrigatório): Nome da entidade
    • entry (opcional): Descrição em formato Markdown
    • type (opcional): Campo Tipo definido pelo usuário (ex.: 'NPC', 'Personagem do Jogador')
    • tags (opcional): Matriz de nomes de tags
    • is_hidden (opcional): Se true, oculto dos jogadores (somente administrador)

Retorna: Matriz de entidades criadas com seus IDs e timestamps

update_entities

Atualizar uma ou mais entidades existentes.

Parâmetros:

  • updates: Matriz de atualizações, cada uma com:
    • entity_id (obrigatório): ID da entidade a atualizar
    • name (obrigatório): Nome da entidade (obrigatório pela API do Kanka mesmo se inalterado)
    • entry (opcional): Conteúdo atualizado em formato Markdown
    • type (opcional): Campo Tipo atualizado
    • tags (opcional): Matriz de tags atualizada
    • is_hidden (opcional): Se true, oculto dos jogadores (somente administrador)

Retorna: Matriz de resultados com status de sucesso/erro para cada atualização

get_entities

Recuperar entidades específicas por ID com posts opcionais.

Parâmetros:

  • entity_ids (obrigatório): Matriz de IDs de entidades para recuperar
  • include_posts (opcional): Incluir posts para cada entidade (padrão: false)

Retorna: Matriz de detalhes completos das entidades com timestamps e posts opcionais

delete_entities

Excluir uma ou mais entidades.

Parâmetros:

  • entity_ids (obrigatório): Matriz de IDs de entidades para excluir

Retorna: Matriz de resultados com status de sucesso/erro para cada exclusão

check_entity_updates

Verificar eficientemente quais entidades foram modificadas desde a última sincronização.

Parâmetros:

  • entity_ids (obrigatório): Matriz de IDs de entidades para verificar
  • last_synced (obrigatório): Timestamp ISO 8601 para verificar atualizações desde

Retorna:

{
  "modified_entity_ids": [101, 103],
  "deleted_entity_ids": [102],
  "check_timestamp": "2024-01-01T12:00:00Z"
}

Operações com Posts

create_posts

Adicionar posts (notas) a entidades.

Parâmetros:

  • posts: Matriz de posts para criar, cada um com:
    • entity_id (obrigatório): Entidade à qual anexar o post
    • name (obrigatório): Título do post
    • entry (opcional): Conteúdo do post em formato Markdown
    • is_hidden (opcional): Se true, oculto dos jogadores (somente administrador)

Retorna: Matriz de posts criados com seus IDs

update_posts

Modificar posts existentes.

Parâmetros:

  • updates: Matriz de atualizações, cada uma com:
    • entity_id (obrigatório): O ID da entidade
    • post_id (obrigatório): O ID do post a atualizar
    • name (obrigatório): Título do post (obrigatório pela API mesmo se inalterado)
    • entry (opcional): Conteúdo atualizado em formato Markdown
    • is_hidden (opcional): Se true, oculto dos jogadores (somente administrador)

Retorna: Matriz de resultados com status de sucesso/erro para cada atualização

delete_posts

Remover posts de entidades.

Parâmetros:

  • deletions: Matriz de exclusões, cada uma com:
    • entity_id (obrigatório): O ID da entidade
    • post_id (obrigatório): O ID do post a excluir

Retorna: Matriz de resultados com status de sucesso/erro para cada exclusão

Busca e Filtragem

O servidor MCP fornece recursos aprimorados de busca:

  • Busca de conteúdo: Pesquisa de texto completo em nomes e conteúdos de entidades (no cliente)
  • Filtro de nome: Correspondência exata ou difusa de nomes
  • Filtro de tipo: Filtrar pelo campo de tipo definido pelo usuário (ex.: 'NPC', 'Cidade')
  • Filtro de tags: Filtrar por tags (lógica E - a entidade deve ter todas as tags especificadas)
  • Intervalo de datas: Filtrar diários por data
  • Correspondência difusa: Correspondência difusa opcional de nomes para buscas mais flexíveis
  • Filtro de última sincronização: Usar o parâmetro nativo lastSync do Kanka para obter apenas entidades modificadas

Nota: A busca de conteúdo busca todas as entidades e pesquisa no cliente, o que pode ser mais lento para campanhas grandes, mas fornece funcionalidade de busca abrangente.

Recursos de Sincronização

Suporte a Timestamps

Todas as entidades incluem timestamps created_at e updated_at no formato ISO 8601, permitindo:

  • Rastrear quando as entidades foram criadas ou modificadas pela última vez
  • Implementar estratégias de resolução de conflitos
  • Construir trilhas de auditoria

Metadados de Sincronização

A ferramenta find_entities retorna metadados de sincronização incluindo:

  • request_timestamp: Quando a solicitação foi feita
  • newest_updated_at: updated_at mais recente das entidades retornadas
  • total_count: Total de entidades correspondentes
  • returned_count: Número retornado nesta resposta

Sincronização Eficiente com lastSync

Use o parâmetro last_synced para buscar apenas entidades modificadas após um horário específico:

# Example: Get entities modified in the last 24 hours
result = await find_entities(
    entity_type="character",
    last_synced="2024-01-01T00:00:00Z"
)

Verificação de Atualizações em Lote

A ferramenta check_entity_updates verifica eficientemente quais entidades foram modificadas:

# Check which of these entities have changed
result = await check_entity_updates(
    entity_ids=[101, 102, 103],
    last_synced="2024-01-01T00:00:00Z"
)
# Returns: modified_entity_ids, deleted_entity_ids, check_timestamp

Desenvolvimento

Configuração

# Clone the repository
git clone https://github.com/twistymaze/mcp-kanka.git
cd mcp-kanka

# Install development dependencies
make install

Executando Testes

# Run all tests
make test

# Run with coverage
make coverage

# Run all checks (lint + typecheck + test)
make check

Qualidade do Código

# Format code
make format

# Run linting
make lint

# Run type checking
make typecheck

Uso Programático

Além de ser um servidor MCP, este pacote fornece uma camada de operações que pode ser usada diretamente em scripts Python:

from mcp_kanka.operations import create_operations

# Create operations instance
ops = create_operations()

# Find entities
result = await ops.find_entities(
    entity_type="character",
    name="Moradin"
)

# Create an entity
results = await ops.create_entities([{
    "entity_type": "character",
    "name": "New Character",
    "type": "NPC",
    "entry": "A mysterious figure"
}])

Isso facilita a criação de scripts de sincronização, operações em massa ou outras ferramentas que interagem com o Kanka.

Configuração

O servidor MCP requer:

  • KANKA_TOKEN: Seu token da API do Kanka
  • KANKA_CAMPAIGN_ID: O ID da sua campanha no Kanka

Recursos

O servidor fornece um recurso kanka://context que explica a estrutura e os recursos do Kanka.

Histórico de Versões

v0.1.0

  • Lançamento inicial
  • Operações CRUD completas para entidades do Kanka
  • Suporte a operações em lote
  • Conversão Markdown/HTML com preservação de menções a entidades
  • Suporte a sincronização com rastreamento de timestamps
  • Recursos abrangentes de busca e filtragem

Licença

MIT