Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:646-661 (handler)

  The handler function that implements the core logic of uploading a file to a specific Shortcut story. It validates inputs, fetches the story, uploads the file using the client, and returns a success message with file details.

  async uploadFileToStory(storyPublicId: number, filePath: string) {
  	if (!storyPublicId) throw new Error("Story public ID is required");
  	if (!filePath) throw new Error("File path is required");
  
  	const story = await this.client.getStory(storyPublicId);
  	if (!story)
  		throw new Error(`Failed to retrieve Shortcut story with public ID: ${storyPublicId}`);
  
  	const uploadedFile = await this.client.uploadFile(storyPublicId, filePath);
  
  	if (!uploadedFile) throw new Error(`Failed to upload file to story sc-${storyPublicId}`);
  
  	return this.toResult(
  		`Uploaded file "${uploadedFile.name}" to story sc-${storyPublicId}. File ID is: ${uploadedFile.id}`,
  	);
  }

• src/tools/stories.ts:222-224 (schema)

  The Zod input schema defining parameters for the 'stories-upload-file' tool: storyPublicId (positive number) and filePath (string).

  	storyPublicId: z.number().positive().describe("The public ID of the story"),
  	filePath: z.string().describe("The path to the file to upload"),
  },

• src/tools/stories.ts:218-226 (registration)

  The registration of the 'stories-upload-file' MCP tool using server.addToolWithWriteAccess, including name, description, input schema, and reference to the handler function.

  server.addToolWithWriteAccess(
  	"stories-upload-file",
  	"Upload a file and link it to a story.",
  	{
  		storyPublicId: z.number().positive().describe("The public ID of the story"),
  		filePath: z.string().describe("The path to the file to upload"),
  	},
  	async ({ storyPublicId, filePath }) => await tools.uploadFileToStory(storyPublicId, filePath),
  );