Shortcut MCP Server

Instructions

Implementation Reference

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

  Executes the core logic of the 'search-iterations' tool by constructing a search query and retrieving matching iterations from the Shortcut API.
  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:42-64 (schema)

  Input schema using Zod for validating tool parameters such as id, name, description, state, team, and date fields.
  { 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:39-66 (registration)

  Registers the 'search-iterations' MCP tool with the server, specifying name, description, input schema, and handler.
  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/utils/search.ts:19-36 (helper)

  Utility function that constructs the search query string from input parameters, handling special keys like owner, booleans, numbers, and quoted strings; used by the handler.
  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; };