search_items
Search your Things 3 task manager by query to find specific tasks, projects, or tags.
Instructions
Search for items in Things
Args: query: Search query
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/things_mcp/server.py:536-544 (handler)The main handler function for the 'search_items' MCP tool. It takes a query string, builds a Things search URL via url_scheme.search(), executes it, and returns a confirmation message.
async def search_items(query: str) -> str: """Search for items in Things Args: query: Search query """ url = url_scheme.search(query) url_scheme.execute_url(url) return f"Searching for '{query}'" - src/things_mcp/server.py:535-535 (registration)The @mcp.tool decorator registers search_items as an MCP tool on the FastMCP server instance.
@mcp.tool - src/things_mcp/url_scheme.py:231-233 (helper)The url_scheme.search() helper function constructs the Things URL for searching by calling construct_url('search', {'query': query}).
def search(query: str) -> str: """Construct URL to perform a search.""" return construct_url('search', {'query': query}) - src/things_mcp/url_scheme.py:31-41 (helper)The execute_url() helper that runs the Things URL via 'open -g' subprocess, with validation that the URL starts with 'things:///'.
def execute_url(url: str) -> None: """Execute a Things URL without bringing Things to the foreground. Security: validates the URL starts with 'things:///' before execution to prevent opening arbitrary URLs or executing unintended commands. Uses subprocess with argument list (no shell interpolation) to avoid command injection vectors. """ if not url.startswith("things:///"): raise ValueError(f"Invalid Things URL scheme: {url[:50]}") subprocess.run(['open', '-g', url], check=True, capture_output=True) - src/things_mcp/url_scheme.py:43-70 (helper)The construct_url() helper that builds the full Things URL from a command and parameters dictionary, handling encoding.
def construct_url(command: str, params: Dict[str, Any]) -> str: """Construct a Things URL from command and parameters.""" # Start with base URL url = f"things:///{command}" # Get authentication token if needed if command in ['update', 'update-project']: token = things.token() if token: params['auth-token'] = token # URL encode parameters if params: encoded_params = [] for key, value in params.items(): if value is None: continue # Handle boolean values if isinstance(value, bool): value = str(value).lower() # Handle lists (for tags, checklist items etc) elif isinstance(value, list): value = ','.join(str(v) for v in value) encoded_params.append(f"{key}={urllib.parse.quote(str(value))}") url += "?" + "&".join(encoded_params) return url