Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/iterations.ts:46-78 (registration)

  Registers the 'iterations-search' tool on the MCP server with description, input schema using Zod validators, and points to the searchIterations handler method.

  server.addToolWithReadAccess(
  	"iterations-search",
  	"Find Shortcut iterations.",
  	{
  		nextPageToken: z
  			.string()
  			.optional()
  			.describe(
  				"If a next_page_token was returned from the search result, pass it in to get the next page of results. Should be combined with the original search parameters.",
  			),
  		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 ({ nextPageToken, ...params }) => await tools.searchIterations(params, nextPageToken),
  );

• src/tools/iterations.ts:49-76 (schema)

  Defines the input schema for the 'iterations-search' tool using Zod, including optional parameters for pagination, filtering by id, name, description, state, team, and date fields.

  {
  	nextPageToken: z
  		.string()
  		.optional()
  		.describe(
  			"If a next_page_token was returned from the search result, pass it in to get the next page of results. Should be combined with the original search parameters.",
  		),
  	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/iterations.ts:131-148 (handler)

  The core handler function that builds the search query using buildSearchQuery helper and current user context, performs the search via ShortcutClientWrapper.searchIterations, handles errors and empty results, formats the output using toResult and entitiesWithRelatedEntities, and supports pagination with next_page_token.

  async searchIterations(params: QueryParams, nextToken?: string) {
  	const currentUser = await this.client.getCurrentUser();
  	const query = await buildSearchQuery(params, currentUser);
  	const { iterations, total, next_page_token } = await this.client.searchIterations(
  		query,
  		nextToken,
  	);
  
  	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 (${iterations.length} shown of ${total} total iterations found):`,
  		await this.entitiesWithRelatedEntities(iterations, "iterations"),
  		next_page_token,
  	);
  }

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

  Helper function to construct the Shortcut search query string from parameter object, handling key mapping, special cases for owner/requester with 'me', boolean negation, quoting phrases, etc.

  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;
  };