get_someday

Instructions

Implementation Reference

• src/things_mcp/server.py:126-144 (handler)

  The main handler function for the get_someday tool. It fetches todos from the Someday list via things.someday(), then also includes tasks from Anytime that belong to Someday projects (since Things.py doesn't inherit project Someday status). Uses _get_someday_context() and _is_in_someday_project() helpers to identify tasks belonging to Someday projects.

  @mcp.tool
  async def get_someday() -> str:
      """Get todos from Someday list, including tasks in Someday projects"""
      todos = things.someday(include_items=True)
      if todos is None:
          todos = []
      # Also include tasks that have start="Anytime" but belong to a Someday project
      # (directly or via a heading), since Things.py doesn't inherit project Someday status
      someday_project_ids, heading_to_project = _get_someday_context()
      if someday_project_ids:
          anytime_todos = things.anytime(include_items=True) or []
          existing_uuids = {t['uuid'] for t in todos}
          for todo in anytime_todos:
              if _is_in_someday_project(todo, someday_project_ids, heading_to_project) and todo['uuid'] not in existing_uuids:
                  todos.append(todo)
      if not todos:
          return "No items found"
      formatted_todos = [format_todo(todo) for todo in todos]
      return "\n\n---\n\n".join(formatted_todos)

• src/things_mcp/server.py:126-127 (registration)

  The tool is registered via the @mcp.tool decorator on the get_someday function. FastMCP (line 19) is the MCP server that provides the .tool() decorator for registration.

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

• src/things_mcp/server.py:24-45 (helper)

  Helper function _get_someday_context() builds a set of Someday project UUIDs and a mapping of heading UUID -> project UUID for headings inside Someday projects. Used by get_someday to identify which tasks belong to Someday projects.

  def _get_someday_context():
      """Return (someday_project_ids, heading_to_project) for Someday filtering.
  
      Returns:
          Tuple of (set of Someday project UUIDs, dict mapping heading UUID to project UUID)
      """
      try:
          someday_project_ids = {p['uuid'] for p in (things.projects(start='Someday') or [])}
      except Exception:
          return set(), {}
      if not someday_project_ids:
          return set(), {}
      # Build heading -> project mapping for headings inside Someday projects
      heading_to_project = {}
      for proj_id in someday_project_ids:
          try:
              headings = things.tasks(type='heading', project=proj_id)
              for h in (headings or []):
                  heading_to_project[h['uuid']] = proj_id
          except Exception:
              pass
      return someday_project_ids, heading_to_project

• src/things_mcp/server.py:48-54 (helper)

  Helper function _is_in_someday_project() checks if a todo belongs to a Someday project, either directly via project field or indirectly via heading that belongs to a Someday project.

  def _is_in_someday_project(todo, someday_project_ids, heading_to_project):
      """Check if a todo belongs to a Someday project, directly or via heading."""
      if todo.get('project') in someday_project_ids:
          return True
      if not todo.get('project') and todo.get('heading'):
          return todo['heading'] in heading_to_project
      return False

• src/things_mcp/server.py:57-74 (helper)

  Helper function filter_someday_project_tasks() filters out tasks that belong to Someday projects from a list of todos. Used by get_today, get_upcoming, and get_anytime (but not directly by get_someday, which has its own logic).

  # Helper function to filter out tasks from Someday projects
  def filter_someday_project_tasks(todos):
      """Filter out tasks that belong to Someday projects.
  
      This matches Things UI behavior where tasks from Someday projects
      don't appear in Today, Upcoming, or Anytime views. Handles both
      direct project membership and tasks under headings in Someday projects.
  
      Args:
          todos: List of todo dictionaries
  
      Returns:
          Filtered list excluding tasks from Someday projects
      """
      someday_project_ids, heading_to_project = _get_someday_context()
      if not someday_project_ids:
          return todos
      return [todo for todo in todos if not _is_in_someday_project(todo, someday_project_ids, heading_to_project)]