feat: Add category filter to mymir_query search (#99)

Co-authored-by: Furkan Akbulutlar <f.akbulutlar@gmail.com>

Author: ZeyNor

lib/data/task.ts

@@ -12,6 +12,7 @@ import {
   taskDecisions,
   taskLinks,
   type NewTask,
+  type Project,
   type TaskLink,
 } from "@/lib/db/schema";
 import { acquireProjectLock } from "@/lib/db/raw/acquire-project-lock";
@@ -907,23 +908,73 @@ export type SearchResult = {
 /** Match a full taskRef like "MYMR-83" (case-insensitive). */
 const TASK_REF_PATTERN = /^([A-Z0-9]+)-(\d+)$/i;
 
+/** Filter options for {@link searchTasks} and {@link searchTasksTx}. */
+export type SearchTasksOpts = {
+  /** Optional search string (taskRef, title, or tag substring). */
+  query?: string;
+  /** Optional exact tag filter (OR-within). */
+  tags?: string[];
+  /** Optional exact project-category filter (AND-narrows). Caller validates. */
+  category?: string;
+};
+
 /**
- * Search tasks by taskRef, title, or tags within a project.
+ * Search tasks by taskRef, title, tags, or category within a project.
+ * Prefer {@link searchTasksTx} when the caller already owns a
+ * `withUserContext` frame.
+ *
  * @param ctx - Resolved auth context.
  * @param projectId - UUID of the project.
- * @param query - Optional search string.
- * @param tags - Optional exact tag filter (OR-within).
+ * @param opts - Filter options.
  * @returns Up to 20 matching tasks with derived state.
+ * @throws ForbiddenError on missing or cross-team project.
  */
 export async function searchTasks(
   ctx: AuthContext,
   projectId: string,
-  query?: string,
-  tags?: string[],
+  opts: SearchTasksOpts = {},
 ): Promise<SearchResult[]> {
-  const trimmedQuery = query?.trim() ?? "";
-  const tagFilter = normalizeTags(tags);
-  if (trimmedQuery.length === 0 && tagFilter.length === 0) return [];
+  return withUserContext(ctx.userId, async (tx) => {
+    const { project } = await assertProjectAccessTx(tx, projectId);
+    return searchTasksTx(tx, project, opts);
+  });
+}
+
+/** The slice of {@link Project} that {@link searchTasksTx} reads. */
+export type SearchTasksProject = Pick<
+  Project,
+  "id" | "identifier" | "categories"
+>;
+
+/**
+ * {@link searchTasks} on a caller-supplied tx and pre-resolved project.
+ *
+ * The caller MUST have invoked `assertProjectAccessTx` for `project.id` on
+ * the same `tx` before calling this. RLS still gates every row read, so a
+ * missing assert never bypasses authorization — it would only mute the
+ * explicit `Forbidden` error path. The pre-resolved `project` lets the
+ * search share authorization with surrounding work without a second access
+ * check.
+ *
+ * @param tx - Active RLS transaction handle.
+ * @param project - Pre-resolved project slice (caller already authorized).
+ * @param opts - Filter options.
+ * @returns Up to 20 matching tasks with derived state.
+ */
+export async function searchTasksTx(
+  tx: Tx,
+  project: SearchTasksProject,
+  opts: SearchTasksOpts = {},
+): Promise<SearchResult[]> {
+  const trimmedQuery = opts.query?.trim() ?? "";
+  const tagFilter = normalizeTags(opts.tags);
+  const trimmedCategory = opts.category?.trim() ?? "";
+  if (
+    trimmedQuery.length === 0 &&
+    tagFilter.length === 0 &&
+    trimmedCategory.length === 0
+  )
+    return [];
 
   const lower = trimmedQuery.toLowerCase();
   const rankExpr =
@@ -936,73 +987,69 @@ export async function searchTasks(
         END`
       : null;
 
-  const { project, trimmed, stateMap } = await withUserContext(
-    ctx.userId,
-    async (tx) => {
-      const { project } = await assertProjectAccessTx(tx, projectId);
+  const clauses = [eq(tasks.projectId, project.id)];
 
-      const clauses = [eq(tasks.projectId, projectId)];
+  if (trimmedQuery.length > 0) {
+    const refMatch = trimmedQuery.match(TASK_REF_PATTERN);
+    const seqClause =
+      refMatch && refMatch[1].toUpperCase() === project.identifier
+        ? eq(tasks.sequenceNumber, Number(refMatch[2]))
+        : null;
 
-      if (trimmedQuery.length > 0) {
-        const refMatch = trimmedQuery.match(TASK_REF_PATTERN);
-        const seqClause =
-          refMatch && refMatch[1].toUpperCase() === project.identifier
-            ? eq(tasks.sequenceNumber, Number(refMatch[2]))
-            : null;
+    const pattern = `%${trimmedQuery}%`;
+    const tagSubstring = sql`EXISTS (SELECT 1 FROM jsonb_array_elements_text(${tasks.tags}) AS t WHERE t ILIKE ${pattern})`;
+    const queryClause =
+      seqClause ?? or(ilike(tasks.title, pattern), tagSubstring);
+    if (queryClause) clauses.push(queryClause);
+  }
 
-        const pattern = `%${trimmedQuery}%`;
-        const tagSubstring = sql`EXISTS (SELECT 1 FROM jsonb_array_elements_text(${tasks.tags}) AS t WHERE t ILIKE ${pattern})`;
-        const queryClause =
-          seqClause ?? or(ilike(tasks.title, pattern), tagSubstring);
-        if (queryClause) clauses.push(queryClause);
-      }
+  if (tagFilter.length > 0) {
+    clauses.push(
+      sql`EXISTS (SELECT 1 FROM jsonb_array_elements_text(${tasks.tags}) AS t WHERE t IN ${tagFilter})`,
+    );
+  }
 
-      if (tagFilter.length > 0) {
-        clauses.push(
-          sql`EXISTS (SELECT 1 FROM jsonb_array_elements_text(${tasks.tags}) AS t WHERE t IN ${tagFilter})`,
-        );
-      }
+  if (trimmedCategory.length > 0) {
+    clauses.push(eq(tasks.category, trimmedCategory));
+  }
 
-      // Inlining a literal `0` in ORDER BY is parsed as a positional column
-      // reference, not a constant — Postgres rejects it with 42P10.
-      const orderByCols = rankExpr
-        ? [rankExpr, asc(tasks.order)]
-        : [asc(tasks.order)];
-      const trimmedRows = await tx
-        .select({
-          id: tasks.id,
-          title: tasks.title,
-          status: tasks.status,
-          tags: tasks.tags,
-          category: tasks.category,
-          priority: tasks.priority,
-          estimate: tasks.estimate,
-          hasDescription: sql<boolean>`length(btrim(${tasks.description})) > 0`,
-          hasCriteria: hasCriteriaExpr(),
-          sequenceNumber: tasks.sequenceNumber,
-          order: tasks.order,
-          assigneeCount: assigneeCountExpr(),
-        })
-        .from(tasks)
-        .where(and(...clauses))
-        .orderBy(...orderByCols)
-        .limit(20);
-      const states = await deriveTaskStatesSlim(
-        projectId,
-        trimmedRows.map((t) => ({
-          id: t.id,
-          status: t.status,
-          hasDescription: t.hasDescription,
-          hasCriteria: t.hasCriteria,
-        })),
-        tx,
-      );
-      return { project, trimmed: trimmedRows, stateMap: states };
-    },
+  // Inlining a literal `0` in ORDER BY is parsed as a positional column
+  // reference, not a constant — Postgres rejects it with 42P10.
+  const orderByCols = rankExpr
+    ? [rankExpr, asc(tasks.order)]
+    : [asc(tasks.order)];
+  const trimmedRows = await tx
+    .select({
+      id: tasks.id,
+      title: tasks.title,
+      status: tasks.status,
+      tags: tasks.tags,
+      category: tasks.category,
+      priority: tasks.priority,
+      estimate: tasks.estimate,
+      hasDescription: sql<boolean>`length(btrim(${tasks.description})) > 0`,
+      hasCriteria: hasCriteriaExpr(),
+      sequenceNumber: tasks.sequenceNumber,
+      order: tasks.order,
+      assigneeCount: assigneeCountExpr(),
+    })
+    .from(tasks)
+    .where(and(...clauses))
+    .orderBy(...orderByCols)
+    .limit(20);
+  const stateMap = await deriveTaskStatesSlim(
+    project.id,
+    trimmedRows.map((t) => ({
+      id: t.id,
+      status: t.status,
+      hasDescription: t.hasDescription,
+      hasCriteria: t.hasCriteria,
+    })),
+    tx,
   );
 
   const identifier = asIdentifier(project.identifier);
-  return enrichWithTaskRef(trimmed, identifier).map((t) => ({
+  return enrichWithTaskRef(trimmedRows, identifier).map((t) => ({
     id: t.id,
     taskRef: t.taskRef,
     title: t.title,

lib/graph/tool-handlers.ts

@@ -15,14 +15,15 @@ import {
   listProjectsForMcp,
   listUserTeams,
   getProjectTags,
+  getProjectTagsTx,
   getProjectMeta,
 } from "@/lib/data/project";
 import {
   createTask,
   updateTask,
   deleteTask,
   deleteTaskPreview,
-  searchTasks,
+  searchTasksTx,
   getProjectTasksSlim,
   getTaskFull,
   fetchAssigneesUnchecked,
@@ -81,6 +82,7 @@ import type { AuthContext } from "@/lib/auth/context";
 import {
   ForbiddenError,
   InsufficientRoleError,
+  assertProjectAccessTx,
   assertTaskAccess,
 } from "@/lib/auth/authorization";
 import { withUserContext } from "@/lib/db/rls";
@@ -699,7 +701,7 @@ export const DESCRIPTIONS = {
     "Server rejects self-edges, duplicates, and cycles. On 'duplicate edge' (concurrent-write race): treat as success and verify with mymir_query type='edges'.",
   mymir_query:
     "Search and browse project data. Pick the slim tool first; reserve overview for unfamiliar projects. " +
-    "search=tasks by taskRef, title, or tag substring (case-insensitive, up to 20). Pass tags=[...] for exact tag match (OR-within); combine with `query` to AND-narrow. Single-result responses include a state hint pointing to the right next call. " +
+    "search=tasks by taskRef, title, or tag substring (case-insensitive, up to 20). Pass tags=[...] for exact tag match (OR-within); combine with `query` to AND-narrow. Pass category='...' for exact project-category match (closed vocabulary; unknown values rejected with the valid list inline); combines with query/tags via AND. Single-result responses include a state hint pointing to the right next call. " +
     "list=every task in the project (slim, ordered by position). " +
     "edges=relationships on one task (connected title, status, direction, note). " +
     "meta=slim project metadata: header, description, status, categories, tag vocabulary (with usage counts), progress + status counts. No task list, no edges. Use this to look up categories before setting one, or the tag vocabulary before coining new tags. " +
@@ -785,6 +787,7 @@ export type QueryParams = {
   projectId?: string;
   query?: string;
   tags?: string[];
+  category?: string;
   taskId?: string;
 };
 
@@ -1359,25 +1362,68 @@ export async function handleQuery(
           );
         const hasQuery = (p.query?.trim() ?? "").length > 0;
         const tagFilter = normalizeTags(p.tags);
-        if (!hasQuery && tagFilter.length === 0) {
+        const trimmedCategory = p.category?.trim() ?? "";
+        if (
+          !hasQuery &&
+          tagFilter.length === 0 &&
+          trimmedCategory.length === 0
+        ) {
           return fail(
-            "query or tags required for search. Pass `query` (taskRef, title or tag substring) or `tags=[...]` (exact tag, OR-within).",
+            "query, tags, or category required for search. Pass `query` (taskRef, title or tag substring), `tags=[...]` (exact tag, OR-within), or `category` (exact project category).",
           );
         }
 
-        const variantHints =
-          tagFilter.length > 0
-            ? tagVariantHints(
-                tagFilter,
-                (await getProjectTags(ctx, p.projectId)).map((t) => t.tag),
-              )
-            : [];
+        const projectId = p.projectId;
+        const outcome = await withUserContext(ctx.userId, async (tx) => {
+          const { project } = await assertProjectAccessTx(tx, projectId);
+
+          if (
+            trimmedCategory.length > 0 &&
+            !project.categories.includes(trimmedCategory)
+          ) {
+            return {
+              kind: "invalid_category" as const,
+              categories: project.categories,
+            };
+          }
+
+          const projectTagVocab =
+            tagFilter.length > 0
+              ? (await getProjectTagsTx(tx, projectId)).map((t) => t.tag)
+              : [];
+
+          const results = await searchTasksTx(tx, project, {
+            query: p.query,
+            tags: tagFilter,
+            category: trimmedCategory || undefined,
+          });
+
+          return { kind: "ok" as const, projectTagVocab, results };
+        });
 
-        const results = await searchTasks(ctx, p.projectId, p.query, tagFilter);
-        const hintParts: string[] = [...variantHints];
-        if (results.length === 1) hintParts.push(stateHint(results[0].state));
-        const hint = hintParts.length > 0 ? hintParts.join("\n> ") : undefined;
-        return ok(formatSearchResults(results, hint));
+        switch (outcome.kind) {
+          case "invalid_category":
+            return fail(
+              `Category "${trimmedCategory}" not in this project's categories: [${outcome.categories.join(", ")}]. Run mymir_query type='meta' for the current list.`,
+            );
+          case "ok": {
+            const variantHints =
+              tagFilter.length > 0
+                ? tagVariantHints(tagFilter, outcome.projectTagVocab)
+                : [];
+            const hintParts: string[] = [...variantHints];
+            if (outcome.results.length === 1)
+              hintParts.push(stateHint(outcome.results[0].state));
+            const hint =
+              hintParts.length > 0 ? hintParts.join("\n> ") : undefined;
+            return ok(formatSearchResults(outcome.results, hint));
+          }
+          default:
+            outcome satisfies never;
+            throw new Error(
+              `unreachable: unhandled search outcome ${JSON.stringify(outcome)}`,
+            );
+        }
       }
       case "list": {
         if (!p.projectId)

lib/mcp/create-server.ts

@@ -514,6 +514,12 @@ export function registerAllTools(server: McpServer, ctx: AuthContext): void {
           .describe(
             "Filter to tasks containing ANY of these exact tags (OR-within). Combine with `query` to narrow further. Pick from the tag vocabulary in `type='meta'`.",
           ),
+        category: z
+          .string()
+          .optional()
+          .describe(
+            "Filter to tasks in exactly this category (AND with `query`/`tags`). Must be one of the project's categories (closed vocabulary); unknown values are rejected. Run mymir_query type='meta' for the current list.",
+          ),
         taskId: z.uuid().optional().describe("Task UUID for type='edges'."),
         projectId: z
           .uuid()