Shortcut MCP Server

Instructions

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),
  );