note_list

Instructions

Implementation Reference

• src/tools/notes.ts:124-157 (handler)

  The main handler function for note_list. Builds a SQL query with optional filters (note_type, related_entity_type, related_entity_id, tag) and returns notes sorted by created_at DESC with a limit.

  function handleNoteList(args: Record<string, unknown>) {
    const db = getDb();
    const noteType = args.note_type as string | undefined;
    const relatedEntityType = args.related_entity_type as string | undefined;
    const relatedEntityId = args.related_entity_id as number | undefined;
    const tag = args.tag as string | undefined;
    const limit = (args.limit as number) ?? 30;
  
    const whereClauses: string[] = [];
    const params: unknown[] = [];
  
    if (noteType) {
      whereClauses.push('note_type = ?');
      params.push(noteType);
    }
    if (relatedEntityType) {
      whereClauses.push('related_entity_type = ?');
      params.push(relatedEntityType);
    }
    if (relatedEntityId !== undefined) {
      whereClauses.push('related_entity_id = ?');
      params.push(relatedEntityId);
    }
    if (tag) {
      addTagFilter(whereClauses, params, tag, 'notes');
    }
  
    const whereStr = whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : '';
  
    const sql = `SELECT * FROM notes ${whereStr} ORDER BY created_at DESC LIMIT ?`;
    params.push(limit);
  
    return db.prepare(sql).all(...params);
  }

• src/tools/notes.ts:36-51 (schema)

  Schema/definition for note_list tool, including description, annotations (readOnlyHint: true), and inputSchema with optional filters: note_type, related_entity_type, related_entity_id, tag, limit.

  name: 'note_list',
  description: 'List notes with optional filters. Returns notes sorted by most recent first.',
  annotations: { title: 'List Notes', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
  inputSchema: {
    type: 'object',
    properties: {
      note_type: {
        type: 'string',
        enum: ['general', 'decision', 'context', 'meeting', 'technical', 'blocker', 'progress', 'release'],
      },
      related_entity_type: { type: 'string', enum: ['project', 'epic', 'task'] },
      related_entity_id: { type: 'integer' },
      tag: { type: 'string', description: 'Filter by a single tag' },
      limit: { type: 'integer', default: 30 },
    },
  },

• src/tools/notes.ts:193-198 (registration)

  Registration of handleNoteList under the key 'note_list' in the exported handlers record.

  export const handlers: Record<string, ToolHandler> = {
    note_save: handleNoteSave,
    note_list: handleNoteList,
    note_search: handleNoteSearch,
    note_delete: handleNoteDelete,
  };

• src/helpers/sql-builder.ts:30-40 (helper)

  The addTagFilter helper function used by handleNoteList to add a JSON tag filter to SQL WHERE clauses.

  export function addTagFilter(
    whereClauses: string[],
    params: unknown[],
    tag: string,
    table: string
  ): void {
    whereClauses.push(
      `EXISTS (SELECT 1 FROM json_each(${table}.tags) WHERE json_each.value = ?)`
    );
    params.push(tag);
  }