add-relation-to-story
Link stories in Shortcut by establishing relationships like blocks, duplicates, or relates to connections between work items.
Instructions
Add a story relationship to a story
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story | |
| relatedStoryPublicId | Yes | The public ID of the related story | |
| relationshipType | No | The type of relationship | relates to |
Implementation Reference
- src/tools/stories.ts:585-623 (handler)The handler function that executes the tool logic: validates inputs, fetches stories, adjusts relationship direction if needed (for 'blocked by' or 'duplicated by'), calls the client to add the relation, and returns a success message.
async addRelationToStory({ storyPublicId, relatedStoryPublicId, relationshipType, }: { storyPublicId: number; relatedStoryPublicId: number; relationshipType: "relates to" | "blocks" | "blocked by" | "duplicates" | "duplicated by"; }) { if (!storyPublicId) throw new Error("Story public ID is required"); if (!relatedStoryPublicId) throw new Error("Related story public ID is required"); const story = await this.client.getStory(storyPublicId); if (!story) throw new Error(`Failed to retrieve Shortcut story with public ID: ${storyPublicId}`); const relatedStory = await this.client.getStory(relatedStoryPublicId); if (!relatedStory) throw new Error(`Failed to retrieve Shortcut story with public ID: ${relatedStoryPublicId}`); let subjectStoryId = storyPublicId; let objectStoryId = relatedStoryPublicId; if (relationshipType === "blocked by" || relationshipType === "duplicated by") { relationshipType = relationshipType === "blocked by" ? "blocks" : "duplicates"; subjectStoryId = relatedStoryPublicId; objectStoryId = storyPublicId; } await this.client.addRelationToStory(subjectStoryId, objectStoryId, relationshipType); return this.toResult( relationshipType === "blocks" ? `Marked sc-${subjectStoryId} as a blocker to sc-${objectStoryId}.` : relationshipType === "duplicates" ? `Marked sc-${subjectStoryId} as a duplicate of sc-${objectStoryId}.` : `Added a relationship between sc-${subjectStoryId} and sc-${objectStoryId}.`, ); } - src/tools/stories.ts:251-258 (schema)Zod schema defining the input parameters for the tool: storyPublicId, relatedStoryPublicId, and optional relationshipType.
storyPublicId: z.number().positive().describe("The public ID of the story"), relatedStoryPublicId: z.number().positive().describe("The public ID of the related story"), relationshipType: z .enum(["relates to", "blocks", "blocked by", "duplicates", "duplicated by"]) .optional() .default("relates to") .describe("The type of relationship"), }, - src/tools/stories.ts:247-260 (registration)Registers the MCP tool 'add-relation-to-story' with the server, including description, input schema, and handler reference.
server.tool( "add-relation-to-story", "Add a story relationship to a story", { storyPublicId: z.number().positive().describe("The public ID of the story"), relatedStoryPublicId: z.number().positive().describe("The public ID of the related story"), relationshipType: z .enum(["relates to", "blocks", "blocked by", "duplicates", "duplicated by"]) .optional() .default("relates to") .describe("The type of relationship"), }, async (params) => await tools.addRelationToStory(params), );