board_get_projects

Instructions

Implementation Reference

• src/tools/projects.ts:68-140 (handler)

  The 'board_get_projects' tool handler function. Registered via server.tool(), it queries Firestore's 'projects' collection, optionally filters by status, fetches per-project task counts, sorts by priority then updated_at, and returns the result as JSON.

  export function registerProjectTools(server: McpServer, db: Firestore) {
    server.tool(
      "board_get_projects",
      "List all projects with per-status task counts. Call this at session start to discover available projects before creating tasks or sessions — the returned IDs are required inputs to board_create_session, board_create_task, and most other tools. Results are sorted by priority descending (critical → low), then updated_at descending as tiebreaker. Projects without an explicit priority are treated as 'medium' for sort purposes (backward compat). Each entry includes: id, name, description, status, priority, metadata, ISO-formatted created_at/updated_at, task_counts (e.g., {todo: 3, in_progress: 1, done: 12}), and total_tasks. Use this over board_get_tasks when you don't yet know which project to target.",
      {
        status: z
          .enum(["active", "paused", "completed", "archived"])
          .optional()
          .describe("Filter to a single status. Omit to return all projects regardless of status. Typical usage: 'active' for current work; 'paused' for projects intentionally on hold pending capacity or dependency; archived projects are usually hidden from day-to-day views."),
      },
      async ({ status }) => {
        let query: FirebaseFirestore.Query = db.collection("projects");
        if (status) {
          query = query.where("status", "==", status);
        }
  
        // Pull by updated_at desc first; we re-sort in-memory to apply the
        // primary priority rank. Firestore can't do a composite sort where
        // one of the fields may be missing (pre-priority projects) — doing it
        // in-memory is cheap at project-list cardinality (~tens of docs).
        const snapshot = await query.orderBy("updated_at", "desc").get();
        const projects = await Promise.all(
          snapshot.docs.map(async (doc) => {
            const data = doc.data();
            const tasksSnap = await db
              .collection("tasks")
              .where("project_id", "==", doc.id)
              .get();
  
            const taskCounts: Record<string, number> = {};
            tasksSnap.docs.forEach((t) => {
              const s = t.data().status as string;
              taskCounts[s] = (taskCounts[s] || 0) + 1;
            });
  
            return {
              id: doc.id,
              ...data,
              // Backfill priority for backward compat — existing docs without
              // the field are treated as "medium" in the response too.
              priority: (data.priority as Priority | undefined) ?? "medium",
              created_at: data.created_at?.toDate?.()?.toISOString() ?? null,
              updated_at: data.updated_at?.toDate?.()?.toISOString() ?? null,
              task_counts: taskCounts,
              total_tasks: tasksSnap.size,
            };
          })
        );
  
        // Primary sort: priority desc (critical → low). Tiebreaker: updated_at desc.
        // updated_at is already an ISO string here; lexical compare works because
        // ISO 8601 is sortable as a string.
        projects.sort((a, b) => {
          const pa = PRIORITY_RANK[a.priority] ?? PRIORITY_RANK.medium;
          const pb = PRIORITY_RANK[b.priority] ?? PRIORITY_RANK.medium;
          if (pa !== pb) return pb - pa;
          const ua = a.updated_at ?? "";
          const ub = b.updated_at ?? "";
          if (ua < ub) return 1;
          if (ua > ub) return -1;
          return 0;
        });
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(projects, null, 2),
            },
          ],
        };
      }
    );

• src/tools/projects.ts:69-77 (schema)

  Input schema for board_get_projects: an optional 'status' enum parameter (active/paused/completed/archived) to filter projects. No output schema defined inline — returns raw JSON text.

  server.tool(
    "board_get_projects",
    "List all projects with per-status task counts. Call this at session start to discover available projects before creating tasks or sessions — the returned IDs are required inputs to board_create_session, board_create_task, and most other tools. Results are sorted by priority descending (critical → low), then updated_at descending as tiebreaker. Projects without an explicit priority are treated as 'medium' for sort purposes (backward compat). Each entry includes: id, name, description, status, priority, metadata, ISO-formatted created_at/updated_at, task_counts (e.g., {todo: 3, in_progress: 1, done: 12}), and total_tasks. Use this over board_get_tasks when you don't yet know which project to target.",
    {
      status: z
        .enum(["active", "paused", "completed", "archived"])
        .optional()
        .describe("Filter to a single status. Omit to return all projects regardless of status. Typical usage: 'active' for current work; 'paused' for projects intentionally on hold pending capacity or dependency; archived projects are usually hidden from day-to-day views."),
    },

• src/tools/projects.ts:68-70 (registration)

  Registration of the 'board_get_projects' tool via server.tool() call inside registerProjectTools(). The function registerProjectTools is exported and invoked from src/index.ts line 28.

  export function registerProjectTools(server: McpServer, db: Firestore) {
    server.tool(
      "board_get_projects",

• src/tools/projects.ts:17-24 (helper)

  PRIORITY_RANK constant used for sorting projects by priority (critical=4, high=3, medium=2, low=1). Used in the board_get_projects handler to sort results.

  // Portfolio-level priority rank for sorting. Higher = more important.
  // Projects without a priority field are treated as "medium" for backward compat.
  const PRIORITY_RANK: Record<string, number> = {
    critical: 4,
    high: 3,
    medium: 2,
    low: 1,
  };