MCP Tasks

Instructions

Implementation Reference

• src/tools.ts:47-64 (handler)

  Handler function for the 'search' tool, which is registered as 'tasks_search' when PREFIX_TOOLS is enabled. Filters tasks by statuses (default all), IDs, search terms (fuzzy match on text+status, OR logic), and optional limit. Returns array of matching tasks with id, text, status.
  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-42 (schema)

  Zod input schema for the tasks_search tool defining parameters: source_id (required), statuses (optional array), terms (optional string array for fuzzy search), ids (optional task ID array), limit (optional max results).
  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:16-41 (registration)

  MCP server registration loop that iterates over all tools from src/tools.ts and registers enabled non-resource tools using server.addTool(), including 'tasks_search' with its schema, description, name (prefixed), and execute handler that delegates to cli.runTool.
  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)

  defineTool factory function used to define all tools, including the 'search' tool as 'tasks_search' by prefixing the name if env.PREFIX_TOOLS is true. Sets other defaults like isReadOnly.
  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, } }
• src/schemas.ts:14-20 (schema)

  Reusable Zod schema for source_id parameter used across tools including tasks_search.
  sourceId: z.string().min(1).optional().describe(util.trimLines(` 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() `)),