stories-create-subtask

Create a sub-task within a parent story in Shortcut project management to break down complex work into manageable components.

Instructions

Create a new story as a sub-task

Input Schema

TableJSON Schema

Name	Required	Description
`parentStoryPublicId`	Yes	The public ID of the parent story
`name`	Yes	The name of the sub-task. Required.
`description`	No	The description of the sub-task

Implementation Reference

src/tools/stories.ts:485-518 (handler)

The main handler function that implements the logic for creating a new subtask story under a given parent story. It fetches the parent story and workflow, determines the default state, and creates the subtask using the client.

async createSubTask({
	parentStoryPublicId,
	name,
	description,
}: {
	parentStoryPublicId: number;
	name: string;
	description?: string;
}) {
	if (!parentStoryPublicId) throw new Error("ID of parent story is required");
	if (!name) throw new Error("Sub-task name is required");

	const parentStory = await this.client.getStory(parentStoryPublicId);
	if (!parentStory)
		throw new Error(`Failed to retrieve parent story with public ID: ${parentStoryPublicId}`);

	const workflow = await this.client.getWorkflow(parentStory.workflow_id);
	if (!workflow) throw new Error("Failed to retrieve workflow of parent story");

	const workflowState = workflow.states[0];
	if (!workflowState) throw new Error("Failed to determine default state for sub-task");

	const subTask = await this.client.createStory({
		name,
		description,
		story_type: parentStory.story_type as CreateStoryParams["story_type"],
		epic_id: parentStory.epic_id,
		group_id: parentStory.group_id,
		workflow_state_id: workflowState.id,
		parent_story_id: parentStoryPublicId,
	});

	return this.toResult(`Created sub-task: sc-${subTask.id}`);
}

src/tools/stories.ts:256-265 (registration)

The registration of the 'stories-create-subtask' tool using server.addToolWithWriteAccess, linking to the handler.

server.addToolWithWriteAccess(
	"stories-create-subtask",
	"Create a new story as a sub-task",
	{
		parentStoryPublicId: z.number().positive().describe("The public ID of the parent story"),
		name: z.string().min(1).max(512).describe("The name of the sub-task. Required."),
		description: z.string().max(10_000).optional().describe("The description of the sub-task"),
	},
	async (params) => await tools.createSubTask(params),
);

src/tools/stories.ts:259-263 (schema)

The Zod schema defining the input parameters for the tool: parentStoryPublicId, name, and optional description.

{
	parentStoryPublicId: z.number().positive().describe("The public ID of the parent story"),
	name: z.string().min(1).max(512).describe("The name of the sub-task. Required."),
	description: z.string().max(10_000).optional().describe("The description of the sub-task"),
},

Shortcut MCP Server