Shortcut MCP Server

Instructions

Implementation Reference

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

  Registration of the MCP tool 'iterations-search' (likely the 'search-iterations' tool), including input schema and handler reference.
  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:131-148 (handler)

  Handler function that performs the iteration search using buildSearchQuery and Shortcut client API, formats results with related entities.
  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/iterations.ts:49-76 (schema)

  Zod schema defining input parameters for the iterations search tool.
  { 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/utils/search.ts:17-36 (helper)

  Helper function buildSearchQuery used to construct the search query string from parameters, and QueryParams type.
  export type QueryParams = { [key: string]: boolean | string | number }; 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; };