MCP Tasks

Instructions

Implementation Reference

• src/tools.ts:153-163 (registration)

  Tool registration for 'summary', automatically prefixed to 'tasks_summary' via defineTool based on env.PREFIX_TOOLS (default: true). Includes schema, description, read-only flag, and handler delegating to getSummary.

  summary: defineTool('summary', {
    schema: z.object({
      source_id: schemas.sourceId,
    }),
    fromArgs: () => ({}),
    description: 'Get per-status task counts and the WIP task(s). Redundant right after tasks_add/tasks_update',
    isReadOnly: true,
    handler: (args) => {
      return getSummary(args.source_id)
    },
  }),

• src/tools.ts:183-195 (handler)

  Core handler logic for tasks_summary: loads metadata, computes per-status task counts, total tasks, WIP tasks, and returns JSON summary.

  function getSummary(sourceId?: string, extra?: object) {
    const meta = metadata.load(sourceId)
    const counts = _.mapValues(meta.groups, tasks => tasks.length)
    const total = Object.values(counts).reduce((sum, count) => sum + count, 0)
    const wip = _.camelCase(env.STATUS_WIP)
    return JSON.stringify({
      source: _.omit(meta.source, ['workspace']),
      ...counts, total, ...extra,
      instructions: env.INSTRUCTIONS || undefined,
      reminders: env.STATUS_REMINDERS ? meta.groups[env.STATUS_REMINDERS] : undefined,
      [wip]: meta.groups[env.STATUS_WIP],
    })
  }

• src/tools.ts:154-156 (schema)

  Zod input schema for tasks_summary tool: requires optional source_id (defaults to most recent).

  schema: z.object({
    source_id: schemas.sourceId,
  }),

• src/tools.ts:15-42 (registration)

  MCP server registration loop that adds all enabled tools from tools.ts (including tasks_summary) to the FastMCP server using server.addTool.

    schema: z.object({
      workspace: z.string().optional().describe('Workspace/project directory path (provided by the IDE or use $PWD)'),
      source_path: schemas.sourcePath,
    }),
    fromArgs: ([sourcePath, workspace]) => ({ source_path: sourcePath, workspace: workspace || undefined }),
    description: util.trimLines(`
      Initializes an source file from a path
      - Always call once per conversation when asked to use these tools
      - Ask the user to clarify the file path if not given, before calling this tool
      - Creates the file if it does not exist
      - Returns the source ID for further use
      ${env.INSTRUCTIONS ? `- ${env.INSTRUCTIONS}` : ''}
    `),
    handler: (args) => {
      storage.getParser(args.source_path)
      // Register the source and get ID
      const source = sources.register(args.source_path, args.workspace)
      return getSummary(source.id)
    },
  }),
  
  search: defineTool('search', {
    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/schemas.ts:14-20 (schema)

  sourceId schema reused in tasks_summary input: string ID from setup, optional.

  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()
  `)),