Kanka

Un servidor MCP para integrarse con la API de Kanka, una herramienta

GitHub
4
Prueba este MCPPatrocinado

Documentación

MCP-Kanka

Servidor MCP (Protocolo de Contexto de Modelo) para la integración con la API de Kanka. Este servidor proporciona a los asistentes de IA herramientas para interactuar con campañas de Kanka, permitiendo operaciones CRUD en varios tipos de entidades como personajes, ubicaciones, organizaciones y más.

Este paquete está diseñado específicamente para satisfacer las necesidades de Teghrim, pero puede ser útil para otras personas que trabajen con Kanka y MCP.

Características

  • Gestión de Entidades: Crear, leer, actualizar y eliminar entidades de Kanka
  • Búsqueda y Filtrado: Buscar entidades por nombre con coincidencia parcial, filtrar por tipo/etiquetas/fecha
  • Operaciones por Lote: Procesar múltiples entidades en una sola solicitud
  • Gestión de Publicaciones: Crear, actualizar y eliminar publicaciones (notas) en entidades
  • Soporte de Markdown: Conversión automática entre Markdown y HTML con preservación de menciones de entidades
  • Seguridad de Tipos: Sugerencias de tipo completas y validación
  • Filtrado del Lado del Cliente: Filtrado mejorado más allá de las limitaciones de la API
  • Soporte de Sincronización: Sincronización eficiente con seguimiento de marcas de tiempo y la función nativa lastSync de Kanka
  • Seguimiento de Marcas de Tiempo: Todas las entidades incluyen marcas de tiempo created_at y updated_at

Requisitos

  • Python 3.10 o superior (se recomienda 3.13.5)
  • Token de API de Kanka e ID de campaña

Instalación

Desde PyPI

pip install mcp-kanka

Desde el Código Fuente (usando uv)

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

Desde el Código Fuente (usando pip)

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

Inicio Rápido

Añadir a Claude Desktop

  1. Configura tus variables de entorno:

    • KANKA_TOKEN: Tu token de API de Kanka
    • KANKA_CAMPAIGN_ID: Tu ID de campaña

  2. Añade a la configuración de Claude Desktop:

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

Uso con 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 Soportados

  • Personaje - Personajes de jugador (PJs), personajes no jugadores (PNJs)
  • Criatura - Tipos de monstruos, animales, criaturas no únicas
  • Ubicación - Lugares, regiones, edificios, puntos de referencia
  • Organización - Gremios, gobiernos, cultos, empresas
  • Raza - Especies, linajes
  • Nota - Contenido interno, resúmenes de sesión, notas del máster (privadas por defecto)
  • Diario - Resúmenes de sesión, narrativas, crónicas
  • Misión - Misiones, objetivos, arcos argumentales

Herramientas Disponibles (9 en Total)

Operaciones de Entidades

find_entities

Buscar y filtrar entidades con opciones completas y metadatos de sincronización.

Parámetros:

  • entity_type (opcional): Tipo para filtrar - personaje, criatura, ubicación, organización, raza, nota, diario, misión
  • query (opcional): Término de búsqueda para búsqueda de texto completo en nombres y contenido
  • name (opcional): Filtrar por nombre (coincidencia parcial por defecto, p. ej., "Prueba" coincide con "Personaje de Prueba")
  • name_exact (opcional): Usar coincidencia exacta de nombre en lugar de parcial (por defecto: falso)
  • name_fuzzy (opcional): Habilitar coincidencia difusa para tolerancia a errores tipográficos (por defecto: falso)
  • type (opcional): Filtrar por campo Tipo definido por el usuario (p. ej., 'PNJ', 'Ciudad')
  • tags (opcional): Matriz de etiquetas - devuelve entidades que tengan TODAS las etiquetas especificadas
  • date_range (opcional): Solo para diarios - filtrar por rango de fechas con fechas start y end
  • limit (opcional): Resultados por página (por defecto: 25, máximo: 100, usar 0 para todos)
  • page (opcional): Número de página para paginación (por defecto: 1)
  • include_full (opcional): Incluir detalles completos de la entidad (por defecto: verdadero)
  • last_synced (opcional): Marca de tiempo ISO 8601 para obtener solo entidades modificadas después de este momento

Devuelve:

{
  "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

Crear una o más entidades con contenido en Markdown.

Parámetros:

  • entities: Matriz de entidades a crear, cada una con:
    • entity_type (obligatorio): Tipo de entidad a crear
    • name (obligatorio): Nombre de la entidad
    • entry (opcional): Descripción en formato Markdown
    • type (opcional): Campo Tipo definido por el usuario (p. ej., 'PNJ', 'Personaje de Jugador')
    • tags (opcional): Matriz de nombres de etiquetas
    • is_hidden (opcional): Si es verdadero, oculto de los jugadores (solo administradores)

Devuelve: Matriz de entidades creadas con sus IDs y marcas de tiempo

update_entities

Actualizar una o más entidades existentes.

Parámetros:

  • updates: Matriz de actualizaciones, cada una con:
    • entity_id (obligatorio): ID de la entidad a actualizar
    • name (obligatorio): Nombre de la entidad (obligatorio por la API de Kanka incluso si no cambia)
    • entry (opcional): Contenido actualizado en formato Markdown
    • type (opcional): Campo Tipo actualizado
    • tags (opcional): Matriz de etiquetas actualizada
    • is_hidden (opcional): Si es verdadero, oculto de los jugadores (solo administradores)

Devuelve: Matriz de resultados con estado de éxito/error para cada actualización

get_entities

Recuperar entidades específicas por ID con publicaciones opcionales.

Parámetros:

  • entity_ids (obligatorio): Matriz de IDs de entidades a recuperar
  • include_posts (opcional): Incluir publicaciones para cada entidad (por defecto: falso)

Devuelve: Matriz de detalles completos de entidades con marcas de tiempo y publicaciones opcionales

delete_entities

Eliminar una o más entidades.

Parámetros:

  • entity_ids (obligatorio): Matriz de IDs de entidades a eliminar

Devuelve: Matriz de resultados con estado de éxito/error para cada eliminación

check_entity_updates

Verificar eficientemente qué entidades han sido modificadas desde la última sincronización.

Parámetros:

  • entity_ids (obligatorio): Matriz de IDs de entidades a verificar
  • last_synced (obligatorio): Marca de tiempo ISO 8601 para verificar actualizaciones desde ese momento

Devuelve:

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

Operaciones de Publicaciones

create_posts

Añadir publicaciones (notas) a entidades.

Parámetros:

  • posts: Matriz de publicaciones a crear, cada una con:
    • entity_id (obligatorio): Entidad a la que adjuntar la publicación
    • name (obligatorio): Título de la publicación
    • entry (opcional): Contenido de la publicación en formato Markdown
    • is_hidden (opcional): Si es verdadero, oculto de los jugadores (solo administradores)

Devuelve: Matriz de publicaciones creadas con sus IDs

update_posts

Modificar publicaciones existentes.

Parámetros:

  • updates: Matriz de actualizaciones, cada una con:
    • entity_id (obligatorio): El ID de la entidad
    • post_id (obligatorio): El ID de la publicación a actualizar
    • name (obligatorio): Título de la publicación (obligatorio por la API incluso si no cambia)
    • entry (opcional): Contenido actualizado en formato Markdown
    • is_hidden (opcional): Si es verdadero, oculto de los jugadores (solo administradores)

Devuelve: Matriz de resultados con estado de éxito/error para cada actualización

delete_posts

Eliminar publicaciones de entidades.

Parámetros:

  • deletions: Matriz de eliminaciones, cada una con:
    • entity_id (obligatorio): El ID de la entidad
    • post_id (obligatorio): El ID de la publicación a eliminar

Devuelve: Matriz de resultados con estado de éxito/error para cada eliminación

Búsqueda y Filtrado

El servidor MCP proporciona capacidades de búsqueda mejoradas:

  • Búsqueda de contenido: Búsqueda de texto completo en nombres y contenido de entidades (del lado del cliente)
  • Filtro de nombre: Coincidencia de nombre exacta o difusa
  • Filtro de tipo: Filtrar por campo de tipo definido por el usuario (p. ej., 'PNJ', 'Ciudad')
  • Filtro de etiquetas: Filtrar por etiquetas (lógica Y - la entidad debe tener todas las etiquetas especificadas)
  • Rango de fechas: Filtrar diarios por fecha
  • Coincidencia difusa: Coincidencia de nombre difusa opcional para búsquedas más flexibles
  • Filtro de última sincronización: Usar el parámetro nativo lastSync de Kanka para obtener solo entidades modificadas

Nota: La búsqueda de contenido obtiene todas las entidades y busca del lado del cliente, lo que puede ser más lento para campañas grandes, pero proporciona una funcionalidad de búsqueda completa.

Características de Sincronización

Soporte de Marcas de Tiempo

Todas las entidades incluyen marcas de tiempo created_at y updated_at en formato ISO 8601, lo que permite:

  • Rastrear cuándo se crearon o modificaron por última vez las entidades
  • Implementar estrategias de resolución de conflictos
  • Construir pistas de auditoría

Metadatos de Sincronización

La herramienta find_entities devuelve metadatos de sincronización que incluyen:

  • request_timestamp: Cuándo se realizó la solicitud
  • newest_updated_at: Último updated_at de las entidades devueltas
  • total_count: Total de entidades coincidentes
  • returned_count: Número devuelto en esta respuesta

Sincronización Eficiente con lastSync

Usa el parámetro last_synced para obtener solo entidades modificadas después de un momento 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"
)

Verificación de Actualizaciones por Lote

La herramienta check_entity_updates verifica eficientemente qué entidades han sido 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

Desarrollo

Configuración

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

# Install development dependencies
make install

Ejecución de Pruebas

# Run all tests
make test

# Run with coverage
make coverage

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

Calidad del Código

# Format code
make format

# Run linting
make lint

# Run type checking
make typecheck

Uso Programático

Además de ser un servidor MCP, este paquete proporciona una capa de operaciones que se puede usar directamente en scripts de 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"
}])

Esto facilita la creación de scripts de sincronización, operaciones masivas u otras herramientas que interactúen con Kanka.

Configuración

El servidor MCP requiere:

  • KANKA_TOKEN: Tu token de API de Kanka
  • KANKA_CAMPAIGN_ID: El ID de tu campaña de Kanka

Recursos

El servidor proporciona un recurso kanka://context que explica la estructura y capacidades de Kanka.

Historial de Versiones

v0.1.0

  • Lanzamiento inicial
  • Operaciones CRUD completas para entidades de Kanka
  • Soporte de operaciones por lote
  • Conversión Markdown/HTML con preservación de menciones de entidades
  • Soporte de sincronización con seguimiento de marcas de tiempo
  • Capacidades completas de búsqueda y filtrado

Licencia

MIT