Shortcut MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/tools/iterations.ts:80-91 (registration)

  Registration of the MCP tool named 'iterations-create' (likely the 'create-iteration' tool), including input schema validation using Zod and the handler function reference.
  server.addToolWithWriteAccess( "iterations-create", "Create a new Shortcut iteration", { name: z.string().describe("The name of the iteration"), startDate: z.string().describe("The start date of the iteration in YYYY-MM-DD format"), endDate: z.string().describe("The end date of the iteration in YYYY-MM-DD format"), teamId: z.string().optional().describe("The ID of a team to assign the iteration to"), description: z.string().optional().describe("A description of the iteration"), }, async (params) => await tools.createIteration(params), );
• src/tools/iterations.ts:164-188 (handler)

  The core handler function that executes the tool logic: creates a new iteration via the Shortcut client API, handles errors, and formats the response.
  async createIteration({ name, startDate, endDate, teamId, description, }: { name: string; startDate: string; endDate: string; teamId?: string; description?: string; }): Promise<CallToolResult> { const iteration = await this.client.createIteration({ name, start_date: startDate, end_date: endDate, group_ids: teamId ? [teamId] : undefined, description, }); if (!iteration) throw new Error(`Failed to create the iteration.`); return this.toResult(`Iteration created with ID: ${iteration.id}.`); }
• src/tools/iterations.ts:84-89 (schema)

  Zod schema for input parameters to the create iteration tool: name (required), startDate, endDate (required strings), teamId and description (optional).
  name: z.string().describe("The name of the iteration"), startDate: z.string().describe("The start date of the iteration in YYYY-MM-DD format"), endDate: z.string().describe("The end date of the iteration in YYYY-MM-DD format"), teamId: z.string().optional().describe("The ID of a team to assign the iteration to"), description: z.string().optional().describe("A description of the iteration"), },
• src/tools/iterations.ts:9-91 (helper)

  Static factory method that initializes IterationTools and registers all iteration-related tools, including create-iteration, on the MCP server.
  export class IterationTools extends BaseTools { static create(client: ShortcutClientWrapper, server: CustomMcpServer) { const tools = new IterationTools(client); server.addToolWithReadAccess( "iterations-get-stories", "Get stories in a specific iteration by iteration public ID", { iterationPublicId: z.number().positive().describe("The public ID of the iteration"), includeStoryDescriptions: z .boolean() .optional() .default(false) .describe( "Indicate whether story descriptions should be included. Including descriptions may take longer and will increase the size of the response.", ), }, async ({ iterationPublicId, includeStoryDescriptions }) => await tools.getIterationStories(iterationPublicId, includeStoryDescriptions), ); server.addToolWithReadAccess( "iterations-get-by-id", "Get a Shortcut iteration by public ID", { iterationPublicId: z.number().positive().describe("The public ID of the iteration to get"), full: z .boolean() .optional() .default(false) .describe( "True to return all iteration fields from the API. False to return a slim version that excludes uncommon fields", ), }, async ({ iterationPublicId, full }) => await tools.getIteration(iterationPublicId, full), ); 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), ); server.addToolWithWriteAccess( "iterations-create", "Create a new Shortcut iteration", { name: z.string().describe("The name of the iteration"), startDate: z.string().describe("The start date of the iteration in YYYY-MM-DD format"), endDate: z.string().describe("The end date of the iteration in YYYY-MM-DD format"), teamId: z.string().optional().describe("The ID of a team to assign the iteration to"), description: z.string().optional().describe("A description of the iteration"), }, async (params) => await tools.createIteration(params), );