Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:519-546 (handler)

  The main handler function for the 'add-task-to-story' tool. It validates inputs, fetches the story to ensure it exists, optionally resolves task owners, and calls the Shortcut client to add the task to the story.

  async addTaskToStory({
  	storyPublicId,
  	taskDescription,
  	taskOwnerIds,
  }: {
  	storyPublicId: number;
  	taskDescription: string;
  	taskOwnerIds?: string[];
  }) {
  	if (!storyPublicId) throw new Error("Story public ID is required");
  	if (!taskDescription) throw new Error("Task description is required");
  
  	const story = await this.client.getStory(storyPublicId);
  	if (!story)
  		throw new Error(`Failed to retrieve Shortcut story with public ID: ${storyPublicId}`);
  
  	if (taskOwnerIds?.length) {
  		const owners = await this.client.getUserMap(taskOwnerIds as string[]);
  		if (!owners) throw new Error(`Failed to retrieve users with IDs: ${taskOwnerIds.join(", ")}`);
  	}
  
  	const task = await this.client.addTaskToStory(storyPublicId, {
  		description: taskDescription,
  		ownerIds: taskOwnerIds,
  	});
  
  	return this.toResult(`Created task for story sc-${storyPublicId}. Task ID: ${task.id}.`);
  }

• src/tools/stories.ts:233-245 (registration)

  Registers the 'add-task-to-story' tool with the MCP server, including the input schema using Zod and linking to the handler method.

  server.tool(
  	"add-task-to-story",
  	"Add a task to a story",
  	{
  		storyPublicId: z.number().positive().describe("The public ID of the story"),
  		taskDescription: z.string().min(1).describe("The description of the task"),
  		taskOwnerIds: z
  			.array(z.string())
  			.optional()
  			.describe("Array of user IDs to assign as owners of the task"),
  	},
  	async (params) => await tools.addTaskToStory(params),
  );

• src/tools/stories.ts:237-243 (schema)

  Zod schema defining the input parameters for the 'add-task-to-story' tool: storyPublicId (required number), taskDescription (required string), taskOwnerIds (optional array of strings).

  	storyPublicId: z.number().positive().describe("The public ID of the story"),
  	taskDescription: z.string().min(1).describe("The description of the task"),
  	taskOwnerIds: z
  		.array(z.string())
  		.optional()
  		.describe("Array of user IDs to assign as owners of the task"),
  },

• src/tools/stories.ts:540-546 (helper)

  Core call to the ShortcutClientWrapper's addTaskToStory method, which performs the actual API interaction to add the task.

  	const task = await this.client.addTaskToStory(storyPublicId, {
  		description: taskDescription,
  		ownerIds: taskOwnerIds,
  	});
  
  	return this.toResult(`Created task for story sc-${storyPublicId}. Task ID: ${task.id}.`);
  }