Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:600-644 (handler)

  The handler function that executes the core logic for updating a Shortcut story. It validates inputs, maps parameters to API format, verifies the story exists, and calls the client to perform the update.
  async updateStory({ storyPublicId, ...updates }: { storyPublicId: number; name?: string; description?: string; type?: "feature" | "bug" | "chore"; epic?: number | null; estimate?: number | null; iteration?: number | null; owner_ids?: string[]; workflow_state_id?: number; labels?: Array<{ name: string; color?: string; description?: string; }>; }) { if (!storyPublicId) throw new Error("Story public ID is required"); // Verify the story exists const story = await this.client.getStory(storyPublicId); if (!story) throw new Error(`Failed to retrieve Shortcut story with public ID: ${storyPublicId}`); // Convert API parameters const updateParams: Record<string, unknown> = {}; if (updates.name !== undefined) updateParams.name = updates.name; if (updates.description !== undefined) updateParams.description = updates.description; if (updates.type !== undefined) updateParams.story_type = updates.type; if (updates.epic !== undefined) updateParams.epic_id = updates.epic; if (updates.estimate !== undefined) updateParams.estimate = updates.estimate; if (updates.iteration !== undefined) updateParams.iteration_id = updates.iteration; if (updates.owner_ids !== undefined) updateParams.owner_ids = updates.owner_ids; if (updates.workflow_state_id !== undefined) updateParams.workflow_state_id = updates.workflow_state_id; if (updates.labels !== undefined) updateParams.labels = updates.labels; // Update the story const updatedStory = await this.client.updateStory(storyPublicId, updateParams); return this.toResult(`Updated story sc-${storyPublicId}. Story URL: ${updatedStory.app_url}`); }
• src/tools/stories.ts:177-214 (schema)

  Zod schema defining the input parameters for the stories-update tool, including storyPublicId (required) and various optional update fields.
  storyPublicId: z.number().positive().describe("The public ID of the story to update"), name: z.string().max(512).optional().describe("The name of the story"), description: z.string().max(10_000).optional().describe("The description of the story"), type: z.enum(["feature", "bug", "chore"]).optional().describe("The type of the story"), epic: z .number() .nullable() .optional() .describe("The epic id of the epic the story belongs to, or null to unset"), estimate: z .number() .nullable() .optional() .describe("The point estimate of the story, or null to unset"), iteration: z .number() .nullable() .optional() .describe("The iteration id of the iteration the story belongs to, or null to unset"), owner_ids: z .array(z.string()) .optional() .describe("Array of user UUIDs to assign as owners of the story"), workflow_state_id: z .number() .optional() .describe("The workflow state ID to move the story to"), labels: z .array( z.object({ name: z.string().describe("The name of the label"), color: z.string().optional().describe("The color of the label"), description: z.string().optional().describe("The description of the label"), }), ) .optional() .describe("Labels to assign to the story"), },
• src/tools/stories.ts:173-216 (registration)

  Registration of the stories-update tool with the MCP server, including name, description, input schema, and handler reference.
  server.addToolWithWriteAccess( "stories-update", "Update an existing Shortcut story. Only provide fields you want to update. The story public ID will always be included in updates.", { storyPublicId: z.number().positive().describe("The public ID of the story to update"), name: z.string().max(512).optional().describe("The name of the story"), description: z.string().max(10_000).optional().describe("The description of the story"), type: z.enum(["feature", "bug", "chore"]).optional().describe("The type of the story"), epic: z .number() .nullable() .optional() .describe("The epic id of the epic the story belongs to, or null to unset"), estimate: z .number() .nullable() .optional() .describe("The point estimate of the story, or null to unset"), iteration: z .number() .nullable() .optional() .describe("The iteration id of the iteration the story belongs to, or null to unset"), owner_ids: z .array(z.string()) .optional() .describe("Array of user UUIDs to assign as owners of the story"), workflow_state_id: z .number() .optional() .describe("The workflow state ID to move the story to"), labels: z .array( z.object({ name: z.string().describe("The name of the label"), color: z.string().optional().describe("The color of the label"), description: z.string().optional().describe("The description of the label"), }), ) .optional() .describe("Labels to assign to the story"), }, async (params) => await tools.updateStory(params), );