add-relation-to-story
Establish connections between stories in Shortcut by specifying relationship types such as 'relates to', 'blocks', or 'duplicates'. Input story IDs and their relationship to streamline project tracking and dependencies.
Instructions
Add a story relationship to a story
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| relatedStoryPublicId | Yes | The public ID of the related story | |
| relationshipType | No | The type of relationship | relates to |
| storyPublicId | Yes | The public ID of the story |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"relatedStoryPublicId": {
"description": "The public ID of the related story",
"exclusiveMinimum": 0,
"type": "number"
},
"relationshipType": {
"default": "relates to",
"description": "The type of relationship",
"enum": [
"relates to",
"blocks",
"blocked by",
"duplicates",
"duplicated by"
],
"type": "string"
},
"storyPublicId": {
"description": "The public ID of the story",
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"storyPublicId",
"relatedStoryPublicId"
],
"type": "object"
}
Implementation Reference
- src/tools/stories.ts:287-299 (registration)Registration of the MCP tool 'stories-add-relation', which corresponds to adding a relation to a story. Includes inline schema and references the handler."stories-add-relation", "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), );
- src/tools/stories.ts:626-664 (handler)The core handler function `addRelationToStory` that executes the tool logic: fetches stories, determines subject/object based on relation type, and calls the Shortcut client's `addRelationToStory` method.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:290-297 (schema)Zod schema defining 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"), },