Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:13-27 (registration)

  Registration of the 'stories-get-by-id' MCP tool, including inline Zod schema and reference to the handler method.

  server.addToolWithReadAccess(
  	"stories-get-by-id",
  	"Get a Shortcut story by public ID",
  	{
  		storyPublicId: z.number().positive().describe("The public ID of the story to get"),
  		full: z
  			.boolean()
  			.optional()
  			.default(false)
  			.describe(
  				"True to return all story fields from the API. False to return a slim version that excludes uncommon fields",
  			),
  	},
  	async ({ storyPublicId, full }) => await tools.getStory(storyPublicId, full),
  );

• src/tools/stories.ts:17-25 (schema)

  Zod schema defining input parameters for the tool: storyPublicId (required number) and full (optional boolean).

  	storyPublicId: z.number().positive().describe("The public ID of the story to get"),
  	full: z
  		.boolean()
  		.optional()
  		.default(false)
  		.describe(
  			"True to return all story fields from the API. False to return a slim version that excludes uncommon fields",
  		),
  },

• src/tools/stories.ts:573-583 (handler)

  Handler function that fetches the story using ShortcutClientWrapper.getStory, handles errors, and formats the output using entityWithRelatedEntities and toResult.

  async getStory(storyPublicId: number, full = false) {
  	const story = await this.client.getStory(storyPublicId);
  
  	if (!story)
  		throw new Error(`Failed to retrieve Shortcut story with public ID: ${storyPublicId}.`);
  
  	return this.toResult(
  		`Story: sc-${storyPublicId}`,
  		await this.entityWithRelatedEntities(story, "story", full),
  	);
  }