Things MCP Server

Instructions

Implementation Reference

• things_server.py:419-438 (handler)

  The main handler function for the 'show_item' tool, registered via @mcp.tool decorator. It invokes the url_scheme.show helper to construct and execute a Things URL scheme to display the specified item or list.

  @mcp.tool
  async def show_item(
      id: str,
      query: str = None,
      filter_tags: List[str] = None
  ) -> str:
      """Show a specific item or list in Things
      
      Args:
          id: ID of item to show, or one of: inbox, today, upcoming, anytime, someday, logbook
          query: Optional query to filter by
          filter_tags: Optional tags to filter by
      """
      url = url_scheme.show(
          id=id,
          query=query,
          filter_tags=filter_tags
      )
      url_scheme.execute_url(url)
      return f"Showing item: {id}"

• url_scheme.py:138-145 (helper)

  Supporting helper function in url_scheme.py that constructs the URL parameters for the 'show' command in Things URL scheme, used directly by the show_item handler.

  def show(id: str, query: Optional[str] = None, filter_tags: Optional[list[str]] = None) -> str:
      """Construct URL to show a specific item or list."""
      params = {
          'id': id,
          'query': query,
          'filter': filter_tags
      }
      return construct_url('show', {k: v for k, v in params.items() if v is not None})