Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:625-634 (handler)

  The handler function that executes the tool: validates inputs, calls the Shortcut client to add the external link, and returns a formatted result message.

  async addExternalLinkToStory(storyPublicId: number, externalLink: string) {
  	if (!storyPublicId) throw new Error("Story public ID is required");
  	if (!externalLink) throw new Error("External link is required");
  
  	const updatedStory = await this.client.addExternalLinkToStory(storyPublicId, externalLink);
  
  	return this.toResult(
  		`Added external link to story sc-${storyPublicId}. Story URL: ${updatedStory.app_url}`,
  	);
  }

• src/tools/stories.ts:278-287 (registration)

  Registers the MCP tool 'add-external-link-to-story' with the server, providing name, description, input schema, and handler reference.

  server.tool(
  	"add-external-link-to-story",
  	"Add an external link to a Shortcut story",
  	{
  		storyPublicId: z.number().positive().describe("The public ID of the story"),
  		externalLink: z.string().url().max(2048).describe("The external link URL to add"),
  	},
  	async ({ storyPublicId, externalLink }) =>
  		await tools.addExternalLinkToStory(storyPublicId, externalLink),
  );

• src/tools/stories.ts:282-284 (schema)

  Zod schema defining the input parameters: storyPublicId (positive number) and externalLink (URL string).

  	storyPublicId: z.number().positive().describe("The public ID of the story"),
  	externalLink: z.string().url().max(2048).describe("The external link URL to add"),
  },

• src/tools/stories.ts:285-287 (handler)

  Inline handler in registration that delegates to the class method addExternalLinkToStory.

  	async ({ storyPublicId, externalLink }) =>
  		await tools.addExternalLinkToStory(storyPublicId, externalLink),
  );