fizzy_boards

Instructions

{"items": [{"id": "board_1", "name": "Project", "columns": [{"id": "col_1", "name": "Backlog"}]}], "pagination": {...}}

Implementation Reference

• src/tools/boards.ts:40-123 (handler)

  Execution handler for the fizzy_boards tool. Lists boards, hydrates columns in parallel, and returns JSON with pagination.

  export const boardsTool = {
  	name: "fizzy_boards",
  	description: `List boards in the account with column summaries.
  
  Get an overview of boards and their column structure including card counts.
  
  **When to use:**
  - Discover board IDs and column IDs for subsequent operations
  - See card counts per column across all boards
  - Find the right board/column to create cards or triage
  
  **Fizzy column conventions:**
  Every board has three implicit columns not returned in the columns array:
  - **Maybe?** (inbox): Untriaged cards. Cards here have no \`column_id\`. New cards start here.
  - **Not Now**: Deferred cards. Move here via \`status: "not_now"\` in \`fizzy_task\`.
  - **Done**: Closed cards. Move here via \`status: "closed"\` in \`fizzy_task\`.
  
  The \`columns\` array only contains custom workflow columns (e.g., "In Progress", "Backlog").
  To move a card from a column back to Maybe?, use \`fizzy_task\` with \`column_id\` omitted and no status change.
  
  **Arguments:**
  - \`account_slug\` (optional): Uses session default if omitted
  - \`limit\` (optional): Max items to return, 1-100 (default: 25)
  - \`cursor\` (optional): Continuation cursor from previous response
  
  **Returns:** JSON with items and pagination metadata.
  \`\`\`json
  {"items": [{"id": "board_1", "name": "Project", "columns": [{"id": "col_1", "name": "Backlog"}]}], "pagination": {...}}
  \`\`\`
  
  **Related:** Use board ID with \`fizzy_task\` to create cards. Use column IDs for triage.`,
  	parameters: z.object({
  		account_slug: z
  			.string()
  			.optional()
  			.describe("Account slug. Uses session default if omitted."),
  		limit: z
  			.number()
  			.int()
  			.min(1)
  			.max(100)
  			.default(DEFAULT_LIMIT)
  			.describe("Max items to return (1-100, default: 25)."),
  		cursor: z
  			.string()
  			.optional()
  			.describe(
  				"Continuation cursor from previous response. Omit to start fresh.",
  			),
  	}),
  	execute: async (args: {
  		account_slug?: string;
  		limit: number;
  		cursor?: string;
  	}) => {
  		const slug = await resolveAccount(args.account_slug);
  		const client = getFizzyClient();
  		const result = await client.listBoards(slug, {
  			limit: args.limit,
  			cursor: args.cursor,
  		});
  		if (isErr(result)) {
  			throw toUserError(result.error, {
  				resourceType: "Board",
  				container: `account "${slug}"`,
  			});
  		}
  
  		const boardsWithColumns = await hydrateColumnsForBoards(
  			client,
  			slug,
  			result.value.items,
  		);
  
  		return JSON.stringify(
  			{
  				items: boardsWithColumns,
  				pagination: result.value.pagination,
  			},
  			null,
  			2,
  		);
  	},
  };

• src/tools/boards.ts:71-89 (schema)

  Zod schema for the fizzy_boards input parameters: account_slug (optional), limit (default 25), cursor (optional pagination).

  parameters: z.object({
  	account_slug: z
  		.string()
  		.optional()
  		.describe("Account slug. Uses session default if omitted."),
  	limit: z
  		.number()
  		.int()
  		.min(1)
  		.max(100)
  		.default(DEFAULT_LIMIT)
  		.describe("Max items to return (1-100, default: 25)."),
  	cursor: z
  		.string()
  		.optional()
  		.describe(
  			"Continuation cursor from previous response. Omit to start fresh.",
  		),
  }),

• src/schemas/boards.ts:16-44 (schema)

  Zod schema definitions for Board, BoardWithColumns, and ColumnSummary types used by fizzy_boards.

  export const BoardSchema = z.object({
  	id: z.string(),
  	name: z.string(),
  	all_access: z.boolean(),
  	creator: UserSchema,
  	columns: z.array(ColumnSummarySchema).optional(),
  	created_at: z.string(),
  	url: z.string().url(),
  });
  
  export const BoardWithColumnsSchema = BoardSchema.extend({
  	columns: z.array(ColumnSummarySchema),
  });
  
  export const CreateBoardInputSchema = z.object({
  	name: z.string().min(1),
  	description: z.string().optional(),
  });
  
  export const UpdateBoardInputSchema = z.object({
  	name: z.string().min(1).optional(),
  	description: z.string().optional(),
  });
  
  export type ColumnSummary = z.infer<typeof ColumnSummarySchema>;
  export type Board = z.infer<typeof BoardSchema>;
  export type BoardWithColumns = z.infer<typeof BoardWithColumnsSchema>;
  export type CreateBoardInput = z.infer<typeof CreateBoardInputSchema>;
  export type UpdateBoardInput = z.infer<typeof UpdateBoardInputSchema>;

• src/tools/boards.ts:17-38 (helper)

  Helper function that fetches columns for each board in parallel and merges them into BoardWithColumns objects.

  async function hydrateColumnsForBoards(
  	client: FizzyClient,
  	accountSlug: string,
  	boards: Board[],
  ): Promise<BoardWithColumns[]> {
  	const columnResults = await Promise.all(
  		boards.map((board) => client.listColumns(accountSlug, board.id)),
  	);
  
  	return boards.map((board, i) => {
  		const colResult = columnResults[i];
  		const columns: ColumnSummary[] =
  			colResult && isOk(colResult)
  				? colResult.value.items.map(({ id, name, color }) => ({
  						id,
  						name,
  						color,
  					}))
  				: [];
  		return { ...board, columns };
  	});
  }

• src/server.ts:19-19 (registration)

  Registration of the fizzy_boards tool (as boardsTool) with the FastMCP server.

  server.addTool(boardsTool);