create_entities
Add characters, locations, organizations, quests, and other campaign elements to Kanka with batch creation, markdown descriptions, and player visibility controls.
Instructions
Create one or more entities
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes |
Implementation Reference
- src/mcp_kanka/tools.py:50-64 (handler)The handler function handle_create_entities that processes tool requests and delegates to the operations layer. It extracts the entities parameter and calls operations.create_entities(entities).
async def handle_create_entities(**params: Any) -> list[CreateEntityResult]: """ Create one or more entities. Args: **params: Parameters from CreateEntitiesParams Returns: List of creation results """ entities = params.get("entities", []) operations = get_operations() # Delegate to operations layer return await operations.create_entities(entities) - src/mcp_kanka/types.py:43-57 (schema)Schema definitions for create_entities tool: EntityInput TypedDict defines the structure for creating a single entity, and CreateEntitiesParams wraps a list of EntityInput objects.
class EntityInput(TypedDict): """Input for creating an entity.""" entity_type: EntityType name: str type: str | None entry: str | None tags: list[str] | None is_hidden: bool | None class CreateEntitiesParams(TypedDict): """Parameters for create_entities tool.""" entities: list[EntityInput] - src/mcp_kanka/types.py:197-205 (schema)CreateEntityResult TypedDict defines the structure of the result returned after creating an entity, including id, entity_id, name, mention, success status, and optional error message.
class CreateEntityResult(TypedDict): """Result of creating an entity.""" id: int | None entity_id: int | None name: str mention: str | None success: bool error: str | None - src/mcp_kanka/__main__.py:148-197 (registration)Tool registration for create_entities with full input schema defining required entity_type and name fields, optional type, entry, tags, and is_hidden fields. Also includes the dispatch logic at lines 399-400.
types.Tool( name="create_entities", description="Create one or more entities", inputSchema={ "type": "object", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "character", "creature", "location", "organization", "race", "note", "journal", "quest", ], "description": "Entity type", }, "name": { "type": "string", "description": "Entity name", }, "type": { "type": "string", "description": "The Type field (e.g., 'NPC', 'Player Character')", }, "entry": { "type": "string", "description": "Description in Markdown format", }, "tags": {"type": "array", "items": {"type": "string"}}, "is_hidden": { "type": "boolean", "description": "If true, hidden from players (admin-only)", }, }, "required": ["entity_type", "name"], }, } }, "required": ["entities"], }, ), - src/mcp_kanka/operations.py:301-395 (handler)Core implementation in the create_entities method that validates entity types, required fields, calls service.create_entity for each entity, and handles both success and error cases returning a list of CreateEntityResult objects.
async def create_entities( self, entities: list[dict[str, Any]] ) -> list[CreateEntityResult]: """Create one or more entities. Args: entities: List of entity data to create Returns: List of results, one per entity (success or failure) """ results = [] valid_types = [ "character", "creature", "location", "organization", "race", "note", "journal", "quest", ] for entity_input in entities: entity_type = entity_input.get("entity_type") entity_name = entity_input.get("name", "") # Validate entity type if not entity_type or entity_type not in valid_types: logger.error( f"Invalid entity_type '{entity_type}' for entity '{entity_name}'" ) error_result: CreateEntityResult = { "id": None, "entity_id": None, "name": entity_name, "mention": None, "success": False, "error": f"Invalid entity_type '{entity_type}'. Must be one of: {', '.join(valid_types)}", } results.append(error_result) continue # Validate required fields if not entity_name: name_error: CreateEntityResult = { "id": None, "entity_id": None, "name": "", "mention": None, "success": False, "error": "Name is required", } results.append(name_error) continue try: # Create entity created = self.service.create_entity( entity_type=entity_type, name=entity_name, type=entity_input.get("type"), entry=entity_input.get("entry"), tags=entity_input.get("tags"), is_hidden=entity_input.get("is_hidden"), is_completed=entity_input.get("is_completed"), image_uuid=entity_input.get("image_uuid"), header_uuid=entity_input.get("header_uuid"), ) result: CreateEntityResult = { "id": created["id"], "entity_id": created["entity_id"], "name": created["name"], "mention": created["mention"], "success": True, "error": None, } results.append(result) except Exception as e: logger.error( f"Failed to create entity '{entity_input.get('name')}': {e}" ) create_error: CreateEntityResult = { "id": None, "entity_id": None, "name": entity_input.get("name", ""), "mention": None, "success": False, "error": str(e), } results.append(create_error) return results