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."),
  },