search-iterations

Instructions

Implementation Reference

• src/tools/iterations.ts:118-131 (handler)

  The main handler function for the 'search-iterations' tool. Builds a search query, calls the Shortcut client's searchIterations method, handles errors and empty results, and formats the output.

  async searchIterations(params: QueryParams) {
  	const currentUser = await this.client.getCurrentUser();
  	const query = await buildSearchQuery(params, currentUser);
  	const { iterations, total } = await this.client.searchIterations(query);
  
  	if (!iterations)
  		throw new Error(`Failed to search for iterations matching your query: "${query}".`);
  	if (!iterations.length) return this.toResult(`Result: No iterations found.`);
  
  	return this.toResult(
  		`Result (first ${iterations.length} shown of ${total} total iterations found):`,
  		await this.entitiesWithRelatedEntities(iterations, "iterations"),
  	);
  }

• src/tools/iterations.ts:39-65 (registration)

  Registers the 'search-iterations' MCP tool with the server, including description, input schema validation, and links to the handler method.

  server.tool(
  	"search-iterations",
  	"Find Shortcut iterations.",
  	{
  		id: z.number().optional().describe("Find only iterations with the specified public ID"),
  		name: z.string().optional().describe("Find only iterations matching the specified name"),
  		description: z
  			.string()
  			.optional()
  			.describe("Find only iterations matching the specified description"),
  		state: z
  			.enum(["started", "unstarted", "done"])
  			.optional()
  			.describe("Find only iterations matching the specified state"),
  		team: z
  			.string()
  			.optional()
  			.describe(
  				"Find only iterations matching the specified team. This can be a team ID or mention name.",
  			),
  		created: date(),
  		updated: date(),
  		startDate: date(),
  		endDate: date(),
  	},
  	async (params) => await tools.searchIterations(params),
  );

• src/tools/iterations.ts:42-63 (schema)

  Zod-based input schema defining optional parameters for searching iterations: id, name, description, state, team, created, updated, startDate, endDate.

  {
  	id: z.number().optional().describe("Find only iterations with the specified public ID"),
  	name: z.string().optional().describe("Find only iterations matching the specified name"),
  	description: z
  		.string()
  		.optional()
  		.describe("Find only iterations matching the specified description"),
  	state: z
  		.enum(["started", "unstarted", "done"])
  		.optional()
  		.describe("Find only iterations matching the specified state"),
  	team: z
  		.string()
  		.optional()
  		.describe(
  			"Find only iterations matching the specified team. This can be a team ID or mention name.",
  		),
  	created: date(),
  	updated: date(),
  	startDate: date(),
  	endDate: date(),
  },

• src/tools/utils/search.ts:19-36 (helper)

  Utility function to build the search query string from input params, handling key mapping, special cases for owner/requester ('me'), booleans, numbers, quoted strings, using supporting getKey and mapKeyName functions.

  export const buildSearchQuery = async (params: QueryParams, currentUser: MemberInfo | null) => {
  	const query = Object.entries(params)
  		.map(([key, value]) => {
  			const q = getKey(key);
  			if (key === "owner" || key === "requester") {
  				if (value === "me") return `${q}:${currentUser?.mention_name || value}`;
  				return `${q}:${String(value || "").replace(/^@/, "")}`;
  			}
  
  			if (typeof value === "boolean") return value ? q : `!${q}`;
  			if (typeof value === "number") return `${q}:${value}`;
  			if (typeof value === "string" && value.includes(" ")) return `${q}:"${value}"`;
  			return `${q}:${value}`;
  		})
  		.join(" ");
  
  	return query;
  };