MCP-Kanka

Instructions

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