tasks_search
Read-only
Search and filter tasks by status, text content, or ID within the MCP Tasks server to find specific items in your task management system.
Instructions
Search tasks from specific statuses with optional text & ID filtering
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | No | Source ID from task_setup() response - Defaults to most recent in the workspace if not provided - Try to always provide it! - If you don't have it, ask the user for a file path and call task_setup() | |
| statuses | No | Specific statuses to get. Gets all if omitted | |
| terms | No | Search terms to filter tasks by text or status (case-insensitive, OR logic, no regex or wildcards) | |
| ids | No | Optional list of task IDs to search for | |
| limit | No | Maximum number of results (only for really large task lists) |
Implementation Reference
- src/tools.ts:47-64 (handler)The handler function implementing the core logic of the 'tasks_search' tool (internally 'search'). It loads metadata, filters tasks by statuses, IDs, search terms using fuzzy search, applies limit, and returns matching tasks.
handler: (args) => { const meta = metadata.load(args.source_id) const groups = args.statuses?.length ? args.statuses : meta.statuses let results = groups.flatMap(status => meta.groups[status] || []) if (args.ids) { results = results.filter(task => args.ids!.includes(task.id)) } if (args.terms?.length) { results = results.filter(task => args.terms!.some(term => util.fuzzySearch(`${task.text} ${task.status}`, term), )) } if (args.limit) { results = results.slice(0, args.limit) } return results - src/tools.ts:37-43 (schema)Zod input schema defining parameters for the 'tasks_search' tool: source_id, statuses, terms, ids, limit.
schema: z.object({ source_id: schemas.sourceId, statuses: z.array(schemas.status).optional().describe('Specific statuses to get. Gets all if omitted'), terms: z.array(z.string()).optional().describe('Search terms to filter tasks by text or status (case-insensitive, OR logic, no regex or wildcards)'), ids: schemas.ids.optional().describe('Optional list of task IDs to search for'), limit: z.number().int().min(1).optional().describe('Maximum number of results (only for really large task lists)'), }), - src/server.ts:15-42 (registration)Registration loop in the MCP server that adds the 'tasks_search' tool (along with others) to the FastMCP server using server.addTool, providing name (tasks_search if prefixed), description, parameters (schema), and execute wrapper.
// Register all tools & resources for (const tool of Object.values(tools)) { if (!tool.isEnabled) { continue } if (tool.isResource) { // Register as resource server.addResource({ uri: `resource://${tool.name}`, name: tool.description, mimeType: 'text/plain', load: () => cli.runTool(tool, []).then(text => ({ text })), }) } else { // Register as tool with enhanced logging server.addTool({ annotations: { openWorldHint: false, // This tool doesn't interact with external systems readOnlyHint: tool.isReadOnly, title: tool.name, }, name: tool.name, description: tool.description, parameters: tool.schema, execute: (args) => cli.runTool(tool, args), }) } } - src/tools.ts:197-214 (helper)Helper function defineTool that wraps the tool definition, sets the name to 'tasks_search' if PREFIX_TOOLS is enabled, and adds default properties.
function defineTool<S extends ZodSchema>(name: string, tool: { schema: S description: string isResource?: boolean isReadOnly?: boolean isEnabled?: boolean handler: (args: z.infer<S>, context?: any) => any fromArgs: (args: string[]) => z.infer<S> }) { const toolName = env.PREFIX_TOOLS ? `tasks_${name}` : name return { ...tool, name: toolName, isResource: tool.isResource ?? false, isReadOnly: tool.isReadOnly ?? false, isEnabled: tool.isEnabled ?? true, } }