LunaTask MCP Server

Instructions

Implementation Reference

• src/lunatask_mcp/tools/people.py:181-281 (handler)

  The primary handler `create_person_tool` which validates input and calls the API client to create a person.

  async def create_person_tool(  # noqa: PLR0913
      self,
      ctx: ServerContext,
      first_name: str,
      last_name: str,
      relationship_strength: str | None = None,
      source: str | None = None,
      source_id: str | None = None,
      email: str | None = None,
      birthday: str | None = None,
      phone: str | None = None,
  ) -> dict[str, Any]:
      """Create a person in LunaTask with optional duplicate detection.
  
      Args:
          ctx: Server context for logging and communication
          first_name: Person's first name
          last_name: Person's last name
          relationship_strength: Optional relationship strength enum value
          source: Optional source identifier for duplicate detection
          source_id: Optional source-specific ID for duplicate detection
          email: Optional email address
          birthday: Optional birthday in YYYY-MM-DD format
          phone: Optional phone number
  
      Returns:
          Dictionary with success status, person_id (if created), and message.
          May include 'duplicate' flag if person already exists.
      """
  
      await ctx.info("Creating new person")
  
      # Validate and convert relationship_strength
      parsed_relationship_strength = PersonRelationshipStrength.CASUAL_FRIENDS
      if relationship_strength is not None:
          try:
              parsed_relationship_strength = PersonRelationshipStrength(relationship_strength)
          except ValueError:
              valid_values = ", ".join([e.value for e in PersonRelationshipStrength])
              message = (
                  f"Invalid relationship_strength '{relationship_strength}'. "
                  f"Must be one of: {valid_values}"
              )
              await ctx.error(message)
              logger.warning("Invalid relationship_strength provided: %s", relationship_strength)
              return {
                  "success": False,
                  "error": "validation_error",
                  "message": message,
              }
  
      # Parse birthday if provided
      parsed_birthday: date_class | None = None
      if birthday is not None:
          try:
              parsed_birthday = date_class.fromisoformat(birthday)
          except ValueError as error:
              message = f"Invalid birthday format. Expected YYYY-MM-DD format: {error!s}"
              await ctx.error(message)
              logger.warning("Invalid birthday provided for create_person: %s", birthday)
              return {
                  "success": False,
                  "error": "validation_error",
                  "message": message,
              }
  
      person_payload = PersonCreate(
          first_name=first_name,
          last_name=last_name,
          relationship_strength=parsed_relationship_strength,
          source=source,
          source_id=source_id,
          email=email,
          birthday=parsed_birthday,
          phone=phone,
      )
  
      try:
          async with self.lunatask_client as client:
              person_response = await client.create_person(person_payload)
  
      except Exception as error:
          return await self._handle_lunatask_api_errors(ctx, error, "person creation")
  
      if person_response is None:
          duplicate_message = "Person already exists for this source/source_id"
          await ctx.info("Person already exists; duplicate create skipped")
          logger.info("Duplicate person detected for source=%s, source_id=%s", source, source_id)
          return {
              "success": True,
              "duplicate": True,
              "message": duplicate_message,
          }
  
      await ctx.info(f"Successfully created person {person_response.id}")
      logger.info("Successfully created person %s", person_response.id)
      return {
          "success": True,
          "person_id": person_response.id,
          "message": "Person created successfully",
      }

• src/lunatask_mcp/tools/people.py:415-447 (registration)

  Tool registration using `self.mcp.tool` in `_register_tools` for `create_person`.

  async def _create_person(  # noqa: PLR0913
      ctx: ServerContext,
      first_name: str,
      last_name: str,
      relationship_strength: str | None = None,
      source: str | None = None,
      source_id: str | None = None,
      email: str | None = None,
      birthday: str | None = None,
      phone: str | None = None,
  ) -> dict[str, Any]:
      return await self.create_person_tool(
          ctx,
          first_name,
          last_name,
          relationship_strength,
          source,
          source_id,
          email,
          birthday,
          phone,
      )
  
  valid_strengths = ", ".join([e.value for e in PersonRelationshipStrength])
  self.mcp.tool(
      name="create_person",
      description=(
          f"Create a person/contact in LunaTask. Requires first_name and last_name. "
          f"Optional relationship_strength ({valid_strengths}), "
          f"source/source_id for duplicate detection, email, birthday (YYYY-MM-DD), "
          f"and phone. Returns person_id or duplicate status."
      ),
  )(_create_person)