tracker_search

Instructions

Implementation Reference

• src/tools/search.ts:32-93 (handler)

  Handler function for tracker_search tool. Accepts query, entity_types, branch, and limit arguments. Searches across projects, epics (with optional branch filter via JOIN on projects), tasks (with branch filter via JOIN on epics), and notes using LIKE patterns.

  function handleSearch(args: Record<string, unknown>) {
    const db = getDb();
    const query = args.query as string;
    const entityTypes = (args.entity_types as string[] | undefined) ?? ['project', 'epic', 'task', 'note'];
    const limit = (args.limit as number) ?? 20;
    const pattern = `%${query}%`;
    const branchFilter = resolveBranch(args.branch);
  
    let epicBranchClause = '';
    let taskBranchClause = '';
    const epicBranchParams: unknown[] = [];
    const taskBranchParams: unknown[] = [];
    if (branchFilter === null) {
      epicBranchClause = ' AND e.branch IS NULL';
      taskBranchClause = ' AND e.branch IS NULL';
    } else if (branchFilter !== undefined) {
      epicBranchClause = ' AND e.branch = ?';
      taskBranchClause = ' AND e.branch = ?';
      epicBranchParams.push(branchFilter);
      taskBranchParams.push(branchFilter);
    }
  
    const results: Record<string, unknown[]> = {};
  
    if (entityTypes.includes('project')) {
      results.projects = db
        .prepare('SELECT * FROM projects WHERE name LIKE ? OR description LIKE ? LIMIT ?')
        .all(pattern, pattern, limit);
    }
  
    if (entityTypes.includes('epic')) {
      results.epics = db
        .prepare(
          `SELECT e.*, p.name as project_name
           FROM epics e
           JOIN projects p ON p.id = e.project_id
           WHERE (e.name LIKE ? OR e.description LIKE ?)${epicBranchClause}
           LIMIT ?`
        )
        .all(pattern, pattern, ...epicBranchParams, limit);
    }
  
    if (entityTypes.includes('task')) {
      results.tasks = db
        .prepare(
          `SELECT t.*, e.name as epic_name
           FROM tasks t
           JOIN epics e ON e.id = t.epic_id
           WHERE (t.title LIKE ? OR t.description LIKE ?)${taskBranchClause}
           LIMIT ?`
        )
        .all(pattern, pattern, ...taskBranchParams, limit);
    }
  
    if (entityTypes.includes('note')) {
      results.notes = db
        .prepare('SELECT * FROM notes WHERE title LIKE ? OR content LIKE ? LIMIT ?')
        .all(pattern, pattern, limit);
    }
  
    return results;
  }

• src/tools/search.ts:7-29 (schema)

  Tool definition with input schema for tracker_search. Declares the tool name, description, annotations (readOnly, idempotent), and input schema with query (required string), entity_types (optional array of project/epic/task/note), branch (optional string), and limit (optional integer, default 20).

  {
    name: 'tracker_search',
    description:
      'Search across ALL entities (projects, epics, tasks, notes) by keyword. Returns categorized results. Pass branch="current" to restrict epic/task matches to the active git branch (projects and notes are not branch-scoped).',
    annotations: { title: 'Global Search', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search keywords' },
        entity_types: {
          type: 'array',
          items: { type: 'string', enum: ['project', 'epic', 'task', 'note'] },
          description: 'Limit search to specific entity types (omit for all)',
        },
        branch: {
          type: 'string',
          description: 'Filter epic/task results by git branch. Pass "current" to auto-detect; pass empty string to restrict to branch-agnostic epics. Omit to include all.',
        },
        limit: { type: 'integer', default: 20, description: 'Max results per entity type' },
      },
      required: ['query'],
    },
  },

• src/index.ts:37-49 (registration)

  Registration of the tracker_search handler in the main server index. searchHandlers (exported from search.ts) is spread into ALL_HANDLERS, which is used by the CallToolRequestSchema handler to dispatch tool calls.

  const ALL_HANDLERS: Record<string, (args: Record<string, unknown>) => unknown> = {
    ...projectHandlers,
    ...epicHandlers,
    ...taskHandlers,
    ...subtaskHandlers,
    ...noteHandlers,
    ...commentHandlers,
    ...templateHandlers,
    ...dashboardHandlers,
    ...searchHandlers,
    ...activityHandlers,
    ...exportImportHandlers,
  };

• src/helpers/git.ts:26-32 (helper)

  Helper function resolveBranch used by tracker_search to process the 'branch' argument. Returns undefined if omitted, null if empty string (restrict to branch-agnostic), the result of getCurrentBranch() if 'current', or the literal branch string otherwise.

  export function resolveBranch(input: unknown): string | null | undefined {
    if (input === undefined) return undefined;
    if (input === null || input === '') return null;
    if (typeof input !== 'string') return undefined;
    if (input === 'current') return getCurrentBranch();
    return input;
  }

• src/types.ts:86-86 (helper)

  Type definition for ToolHandler used by the handlers export in search.ts.

  export type ToolHandler = (args: Record<string, unknown>) => unknown;