get_recent

Instructions

Implementation Reference

• src/things_mcp/server.py:333-345 (handler)

  Handler for get_recent tool. Queries Things for recently created items using the `things.last()` library, formats each with format_todo helper, and returns them separated by newlines.

  @mcp.tool
  async def get_recent(period: str) -> str:
      """Get recently created items
  
      Args:
          period: Time period (e.g., '3d', '1w', '2m', '1y')
      """
      todos = things.last(period, include_items=True)
      if not todos:
          return f"No items found in the last {period}"
  
      formatted_todos = [format_todo(todo) for todo in todos]
      return "\n\n---\n\n".join(formatted_todos)

• src/things_mcp/server.py:333-334 (registration)

  Registration of get_recent as an MCP tool via @mcp.tool decorator on the FastMCP instance.

  @mcp.tool
  async def get_recent(period: str) -> str:

• src/things_mcp/server.py:333-345 (schema)

  Schema/input definition: takes a single string parameter 'period' (e.g., '3d', '1w', '2m', '1y') and returns a string.

  @mcp.tool
  async def get_recent(period: str) -> str:
      """Get recently created items
  
      Args:
          period: Time period (e.g., '3d', '1w', '2m', '1y')
      """
      todos = things.last(period, include_items=True)
      if not todos:
          return f"No items found in the last {period}"
  
      formatted_todos = [format_todo(todo) for todo in todos]
      return "\n\n---\n\n".join(formatted_todos)

• src/things_mcp/formatters.py:40-144 (helper)

  Helper used by get_recent to format each todo dict into a readable string with title, UUID, type, status, dates, notes, project, tags, checklist, etc.

  def format_todo(todo: dict) -> str:
      """Helper function to format a single todo into a readable string."""
      logger.debug(f"Formatting todo: {todo}")
      todo_text = f"Title: {todo['title']}"
  
      # Add UUID for reference
      todo_text += f"\nUUID: {todo['uuid']}"
  
      # Add type
      todo_text += f"\nType: {todo['type']}"
  
      # Add status if present
      if todo.get('status'):
          todo_text += f"\nStatus: {todo['status']}"
  
      # Look up parent project once (used for both List status and Project display)
      # For heading-level tasks without a project field, resolve heading -> project
      parent_project = None
      if todo.get('project'):
          try:
              parent_project = things.get(todo['project'])
          except Exception:
              pass
      elif todo.get('heading'):
          try:
              heading_obj = things.get(todo['heading'])
              if heading_obj and heading_obj.get('project'):
                  parent_project = things.get(heading_obj['project'])
          except Exception:
              pass
  
      # Add start/list location with Someday inheritance
      if todo.get('start'):
          effective_start = todo['start']
          if effective_start != 'Someday' and parent_project and parent_project.get('start') == 'Someday':
              effective_start = 'Someday'
              todo_text += f"\nList: {effective_start} (inherited from project)"
          else:
              todo_text += f"\nList: {effective_start}"
  
      # Add dates
      if todo.get('start_date'):
          todo_text += f"\nStart Date: {todo['start_date']}"
      if todo.get('deadline'):
          todo_text += f"\nDeadline: {todo['deadline']}"
      if todo.get('stop_date'):  # Completion date
          todo_text += f"\nCompleted: {todo['stop_date']}"
  
      # Add creation and modification dates
      if todo.get('created'):
          todo_text += f"\nCreated: {todo['created']}"
          # Calculate age since creation
          try:
              age_text = _calculate_age(todo['created'])
              todo_text += f"\nAge: {age_text}"
          except (ValueError, TypeError):
              pass
  
      if todo.get('modified'):
          todo_text += f"\nModified: {todo['modified']}"
          # Calculate time since last modification
          try:
              modified_age = _calculate_age(todo['modified'])
              todo_text += f"\nLast modified: {modified_age}"
          except (ValueError, TypeError):
              pass
  
      # Add notes if present
      if todo.get('notes'):
          todo_text += f"\nNotes: {todo['notes']}"
  
      # Add project info if present
      if parent_project:
          todo_text += f"\nProject: {parent_project['title']}"
  
      # Add heading info if present
      if todo.get('heading'):
          try:
              heading = things.get(todo['heading'])
              if heading:
                  todo_text += f"\nHeading: {heading['title']}"
          except Exception:
              pass
  
      # Add area info if present
      if todo.get('area'):
          try:
              area = things.get(todo['area'])
              if area:
                  todo_text += f"\nArea: {area['title']}"
          except Exception:
              pass
  
      # Add tags if present
      if todo.get('tags'):
          todo_text += f"\nTags: {', '.join(todo['tags'])}"
  
      # Add checklist if present and contains items
      if isinstance(todo.get('checklist'), list):
          todo_text += "\nChecklist:"
          for item in todo['checklist']:
              checkbox = "✓" if item.get('status') == 'completed' else "☐"
              todo_text += f"\n  {checkbox} {item['title']}"
  
      return todo_text