Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:440-483 (handler)

  Handler function that implements the core logic for creating a new Shortcut story. It resolves the workflow if only team is provided, fetches necessary data, calls the Shortcut client API to create the story, and returns a success message with the story ID.
  async createStory({ name, description, type, owner, epic, iteration, team, workflow, }: { name: string; description?: string; type: "feature" | "bug" | "chore"; owner?: string; epic?: number; iteration?: number; team?: string; workflow?: number; }) { if (!workflow && !team) throw new Error("Team or Workflow has to be specified"); if (!workflow && team) { const fullTeam = await this.client.getTeam(team); workflow = fullTeam?.workflow_ids?.[0]; } if (!workflow) throw new Error("Failed to find workflow for team"); const fullWorkflow = await this.client.getWorkflow(workflow); if (!fullWorkflow) throw new Error("Failed to find workflow"); const story = await this.client.createStory({ name, description, story_type: type, owner_ids: owner ? [owner] : [], epic_id: epic, iteration_id: iteration, group_id: team, workflow_state_id: fullWorkflow.default_state_id, }); return this.toResult(`Created story: sc-${story.id}`); }
• src/tools/stories.ts:128-171 (registration)

  Tool registration block that adds the 'stories-create' tool to the MCP server, specifying the name, description, input schema using Zod, and the handler function.
  server.addToolWithWriteAccess( "stories-create", `Create a new Shortcut story. Name is required, and either a Team or Workflow must be specified: - If only Team is specified, we will use the default workflow for that team. - If Workflow is specified, it will be used regardless of Team. The story will be added to the default state for the workflow. `, { name: z.string().min(1).max(512).describe("The name of the story. Required."), description: z.string().max(10_000).optional().describe("The description of the story"), type: z .enum(["feature", "bug", "chore"]) .default("feature") .describe("The type of the story"), owner: z.string().optional().describe("The user id of the owner of the story"), epic: z.number().optional().describe("The epic id of the epic the story belongs to"), iteration: z .number() .optional() .describe("The iteration id of the iteration the story belongs to"), team: z .string() .optional() .describe( "The team ID or mention name of the team the story belongs to. Required unless a workflow is specified.", ), workflow: z .number() .optional() .describe("The workflow ID to add the story to. Required unless a team is specified."), }, async ({ name, description, type, owner, epic, iteration, team, workflow }) => await tools.createStory({ name, description, type, owner, epic, iteration, team, workflow, }), );
• src/tools/stories.ts:137-159 (schema)

  Input schema using Zod for validating parameters of the stories-create tool: name (required), description, type, owner, epic, iteration, team, workflow.
  name: z.string().min(1).max(512).describe("The name of the story. Required."), description: z.string().max(10_000).optional().describe("The description of the story"), type: z .enum(["feature", "bug", "chore"]) .default("feature") .describe("The type of the story"), owner: z.string().optional().describe("The user id of the owner of the story"), epic: z.number().optional().describe("The epic id of the epic the story belongs to"), iteration: z .number() .optional() .describe("The iteration id of the iteration the story belongs to"), team: z .string() .optional() .describe( "The team ID or mention name of the team the story belongs to. Required unless a workflow is specified.", ), workflow: z .number() .optional() .describe("The workflow ID to add the story to. Required unless a team is specified."), },