MCP-Kanka

Instructions

Implementation Reference

• src/mcp_kanka/tools.py:119-133 (handler)

  The handle_create_posts function - the main handler that receives create_posts tool requests and delegates to the operations layer
  async def handle_create_posts(**params: Any) -> list[CreatePostResult]: """ Create posts on entities. Args: **params: Parameters from CreatePostsParams Returns: List of creation results """ posts = params.get("posts", []) operations = get_operations() # Delegate to operations layer return await operations.create_posts(posts)
• src/mcp_kanka/operations.py:565-605 (handler)

  The create_posts operation - actual implementation that iterates through posts and calls the Kanka service to create each post, handling errors and returning results
  async def create_posts(self, posts: list[dict[str, Any]]) -> list[CreatePostResult]: """Create posts on entities. Args: posts: List of post data to create Returns: List of results, one per post """ results = [] for post_input in posts: try: # Create post created = self.service.create_post( entity_id=post_input["entity_id"], name=post_input["name"], entry=post_input.get("entry"), is_hidden=post_input.get("is_hidden", False), ) result: CreatePostResult = { "post_id": created["post_id"], "entity_id": created["entity_id"], "success": True, "error": None, } results.append(result) except Exception as e: logger.error( f"Failed to create post on entity {post_input['entity_id']}: {e}" ) error_result: CreatePostResult = { "post_id": None, "entity_id": post_input["entity_id"], "success": False, "error": str(e), } results.append(error_result) return results
• src/mcp_kanka/types.py:90-102 (schema)

  Type definitions for create_posts tool - PostInput and CreatePostsParams TypedDict classes that define the input schema
  class PostInput(TypedDict): """Input for creating a post.""" entity_id: int name: str entry: str | None is_hidden: bool | None class CreatePostsParams(TypedDict): """Parameters for create_posts tool.""" posts: list[PostInput]
• src/mcp_kanka/types.py:248-254 (schema)

  CreatePostResult TypedDict - defines the return type structure for the create_posts tool operation
  class CreatePostResult(TypedDict): """Result of creating a post.""" post_id: int | None entity_id: int success: bool error: str | None
• src/mcp_kanka/__main__.py:270-301 (registration)

  Tool registration - registers create_posts with the MCP server, defining its name, description, and input schema validation
  types.Tool( name="create_posts", description="Create posts on entities", inputSchema={ "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "integer", "description": "The entity ID to attach post to", }, "name": {"type": "string", "description": "Post title"}, "entry": { "type": "string", "description": "Post content in Markdown format", }, "is_hidden": { "type": "boolean", "description": "If true, hidden from players (admin-only)", }, }, "required": ["entity_id", "name"], }, } }, "required": ["posts"], }, ),