board_create_project

Instructions

Implementation Reference

• src/tools/projects.ts:160-192 (handler)

  The async handler function for board_create_project. It receives { name, description, priority, metadata }, creates a Firestore document in the 'projects' collection with status='active' and default priority='medium', then returns the new project's ID, name, status, priority, and a success message.

    async ({ name, description, priority, metadata }) => {
      const now = Timestamp.now();
      const resolvedPriority: Priority = priority ?? "medium";
      const docRef = await db.collection("projects").add({
        name,
        description: description ?? null,
        status: "active",
        priority: resolvedPriority,
        metadata: metadata ?? {},
        created_at: now,
        updated_at: now,
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                id: docRef.id,
                name,
                status: "active",
                priority: resolvedPriority,
                message: `Project "${name}" created successfully`,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

• src/tools/projects.ts:145-159 (schema)

  Zod input schema for board_create_project. Defines the 'name' (required string), 'description' (optional string), 'priority' (optional enum critical/high/medium/low), and 'metadata' (optional record of string to unknown) parameters.

  {
    name: z.string().describe("Project name — short, human-readable title shown everywhere the project is referenced"),
    description: z
      .string()
      .optional()
      .describe("Optional longer description of the project's scope, goals, or context. Omit if the name is self-explanatory."),
    priority: z
      .enum(["critical", "high", "medium", "low"])
      .optional()
      .describe("Portfolio-level importance — drives weekly focus and default sort order in board_get_projects. This is DISTINCT from task.priority, which orders execution within a single project. Use critical/high for projects that should dominate the coming week; medium for steady-state work (default); low for back-burner initiatives you want visible but not pressing. Defaults to 'medium' when omitted."),
    metadata: z
      .record(z.string(), z.unknown())
      .optional()
      .describe("Optional key/value metadata (e.g., linked doc paths, deadlines, stakeholder names). Merged shallowly on board_update_project."),
  },

• src/tools/projects.ts:142-192 (registration)

  Registration of the 'board_create_project' tool via server.tool(), called within the registerProjectTools() function.

  server.tool(
    "board_create_project",
    "Create a new project to group tasks and sessions under a shared goal. Projects are the top-level container — every task and session must belong to one. Use sparingly: create a new project for major initiatives (3+ related tasks), not for every piece of work. New projects are created with status='active' and priority='medium' (unless overridden). Returns { id, name, status, priority, message }.",
    {
      name: z.string().describe("Project name — short, human-readable title shown everywhere the project is referenced"),
      description: z
        .string()
        .optional()
        .describe("Optional longer description of the project's scope, goals, or context. Omit if the name is self-explanatory."),
      priority: z
        .enum(["critical", "high", "medium", "low"])
        .optional()
        .describe("Portfolio-level importance — drives weekly focus and default sort order in board_get_projects. This is DISTINCT from task.priority, which orders execution within a single project. Use critical/high for projects that should dominate the coming week; medium for steady-state work (default); low for back-burner initiatives you want visible but not pressing. Defaults to 'medium' when omitted."),
      metadata: z
        .record(z.string(), z.unknown())
        .optional()
        .describe("Optional key/value metadata (e.g., linked doc paths, deadlines, stakeholder names). Merged shallowly on board_update_project."),
    },
    async ({ name, description, priority, metadata }) => {
      const now = Timestamp.now();
      const resolvedPriority: Priority = priority ?? "medium";
      const docRef = await db.collection("projects").add({
        name,
        description: description ?? null,
        status: "active",
        priority: resolvedPriority,
        metadata: metadata ?? {},
        created_at: now,
        updated_at: now,
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                id: docRef.id,
                name,
                status: "active",
                priority: resolvedPriority,
                message: `Project "${name}" created successfully`,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

• src/types.ts:5-15 (helper)

  The Project interface type used for the project data structure created by board_create_project.

  export interface Project {
    name: string;
    description: string | null;
    status: "active" | "paused" | "completed" | "archived";
    priority: Priority;
    metadata: Record<string, unknown>;
    created_at: Timestamp;
    updated_at: Timestamp;
  }
  
  export interface Task {

• src/tools/projects.ts:31-36 (helper)

  Valid state transitions map used for status management of projects, relevant context for the board_create_project handler.

  const validTransitions: Record<string, readonly string[]> = {
    active: ["paused", "completed", "archived"],
    paused: ["active", "completed", "archived"],
    completed: ["archived", "active"], // allow re-opening
    archived: ["active"], // allow un-archiving; caller can re-transition afterward
  };