fizzy_get_card

Instructions

Implementation Reference

• src/tools/cards.ts:223-306 (handler)

  Definition of the getCardTool which implements the 'fizzy_get_card' tool. Contains the name, description, Zod schema parameters, and execute handler that resolves account, gets a FizzyClient, and retrieves a card by number or ID, then formats it using formatCard.

  export const getCardTool = {
  	name: "fizzy_get_card",
  	description: `Get full details of a card by its number or ID.
  Retrieve complete card data including description, steps count, and metadata.
  
  **When to use:**
  - Need full description or metadata for a specific card
  - Check step completion status or see all tags/assignees
  
  **Don't use when:** Scanning multiple cards - use \`fizzy_search\` first.
  
  **Arguments:**
  - \`account_slug\` (optional): Uses session default if omitted
  - \`card_number\` (recommended): The human-readable \`#\` number from URLs/lists (e.g., 42)
  - \`card_id\` (alternative): The UUID from API responses. Use \`card_number\` when possible.
  
  **IMPORTANT:** Provide \`card_number\` (integer) OR \`card_id\` (string UUID), not both.
  The \`card_number\` is the \`#\` visible in the UI (e.g., #42). The \`card_id\` is the internal UUID.
  
  **Returns:**
  JSON with id, number, title, description (markdown), status, board_id, column_id, tags array, assignees array, steps_count, completed_steps_count, comments_count, url, created_at, updated_at, closed_at (null if open).
  Example: \`{"id": "card_abc", "number": 42, "title": "Fix bug", "status": "open", "steps_count": 3, ...}\`
  
  **Related:** Use \`fizzy_comment\` or \`fizzy_step\` for deeper interaction.`,
  	parameters: z
  		.object({
  			account_slug: z
  				.string()
  				.optional()
  				.describe(
  					"Account slug (e.g., 'acme-corp'). Uses session default if omitted.",
  				),
  			card_number: z
  				.number()
  				.optional()
  				.describe(
  					"Card number - the human-readable # from URLs/UI (e.g., 42). Preferred over card_id.",
  				),
  			card_id: z
  				.string()
  				.optional()
  				.describe(
  					"Card UUID from API responses. Use card_number instead when you have the # visible in the UI.",
  				),
  		})
  		.strict(),
  	execute: async (args: {
  		account_slug?: string;
  		card_number?: number;
  		card_id?: string;
  	}) => {
  		const slug = await resolveAccount(args.account_slug);
  		const client = getFizzyClient();
  
  		// Prefer card_number over card_id
  		if (args.card_number !== undefined) {
  			const result = await client.getCard(slug, args.card_number);
  			if (isErr(result)) {
  				throw toUserError(result.error, {
  					resourceType: "Card",
  					resourceId: `#${args.card_number}`,
  					container: `account "${slug}"`,
  				});
  			}
  			return formatCard(result.value);
  		}
  
  		if (args.card_id !== undefined) {
  			const result = await client.getCardById(slug, args.card_id);
  			if (isErr(result)) {
  				throw toUserError(result.error, {
  					resourceType: "Card",
  					resourceId: args.card_id,
  					container: `account "${slug}"`,
  				});
  			}
  			return formatCard(result.value);
  		}
  
  		throw new UserError(
  			"Either card_number or card_id must be provided. Use card_number (the # from URLs) when possible.",
  		);
  	},
  };

• src/tools/cards.ts:16-48 (helper)

  The formatCard helper function converts a Card object (with HTML description) to a JSON string with markdown description. Used by the execute handler to format the result.

  function formatCard(card: Card): string {
  	// Convert HTML to markdown for LLM-friendly output
  	const description = card.description_html
  		? htmlToMarkdown(card.description_html)
  		: null;
  	return JSON.stringify(
  		{
  			id: card.id,
  			number: card.number,
  			title: card.title,
  			description,
  			status: card.status,
  			closed: card.closed,
  			board_id: card.board_id,
  			column_id: card.column_id,
  			tags: card.tags,
  			assignees: card.assignees,
  			steps_count: card.steps_count,
  			completed_steps_count: card.completed_steps_count,
  			comments_count: card.comments_count,
  			url: card.url,
  			created_at: card.created_at,
  			updated_at: card.updated_at,
  			closed_at: card.closed_at,
  			golden: card.golden ?? false,
  			last_active_at: card.last_active_at ?? null,
  			image_url: card.image_url ?? null,
  			steps: card.steps ?? [],
  		},
  		null,
  		2,
  	);
  }

• src/schemas/cards.ts:44-73 (schema)

  CardSchema defining the shape of Card data returned by the API. Used as the return type for getCard and getCardById responses.

  export const CardSchema = z.object({
  	id: z.string(),
  	number: z.number(),
  	title: z.string(),
  	description: z.string().nullable().optional(),
  	description_html: z.string().nullable(),
  	status: CardStatusSchema,
  	closed: z.boolean(),
  	board_id: z.string(),
  	// Null when card is closed or not yet placed in a column
  	column_id: z.string().nullable(),
  	tags: z.array(CardTagSchema),
  	assignees: z.array(CardAssigneeSchema),
  	steps_count: z.number(),
  	completed_steps_count: z.number(),
  	comments_count: z.number(),
  	steps: z.array(StepSchema).optional(),
  	created_at: z.string(),
  	updated_at: z.string(),
  	closed_at: z.string().nullable(),
  	url: z.string(),
  	image_url: z.string().nullable().optional(),
  	golden: z.boolean().optional(),
  	last_active_at: z.string().optional(),
  	board: BoardRefSchema.optional(),
  	column: ColumnRefSchema.optional(),
  	creator: CreatorRefSchema.optional(),
  	comments_url: z.string().optional(),
  	reactions_url: z.string().optional(),
  });

• src/server.ts:12-27 (registration)

  Registration of getCardTool on the FastMCP server via server.addTool(getCardTool).

  export function createServer(): FastMCP {
  	const server = new FastMCP({
  		name: "fizzy-mcp",
  		version: "1.0.0",
  	});
  
  	server.addTool(defaultAccountTool);
  	server.addTool(boardsTool);
  	server.addTool(searchTool);
  	server.addTool(getCardTool);
  	server.addTool(taskTool);
  	server.addTool(commentTool);
  	server.addTool(stepTool);
  
  	return server;
  }

• src/tools/index.ts:1-23 (registration)

  Re-export and collection of getCardTool in the tools index for centralized tool aggregation.

  export { boardsTool } from "./boards.js";
  export { getCardTool, searchTool } from "./cards.js";
  export { commentTool } from "./comments.js";
  export { defaultAccountTool } from "./identity.js";
  export { stepTool } from "./steps.js";
  export { taskTool } from "./task.js";
  
  import { boardsTool } from "./boards.js";
  import { getCardTool, searchTool } from "./cards.js";
  import { commentTool } from "./comments.js";
  import { defaultAccountTool } from "./identity.js";
  import { stepTool } from "./steps.js";
  import { taskTool } from "./task.js";
  
  export const allTools = [
  	defaultAccountTool,
  	boardsTool,
  	searchTool,
  	getCardTool,
  	taskTool,
  	commentTool,
  	stepTool,
  ];