Shortcut MCP Server

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