Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:791-804 (handler)

  The main handler function for the 'stories-get-by-external-link' tool. It validates input, calls the client wrapper to fetch stories, and formats the result.

  async getStoriesByExternalLink(externalLink: string) {
  	if (!externalLink) throw new Error("External link is required");
  
  	const { stories, total } = await this.client.getStoriesByExternalLink(externalLink);
  
  	if (!stories || !stories.length) {
  		return this.toResult(`No stories found with external link: ${externalLink}`);
  	}
  
  	return this.toResult(
  		`Found ${total} stories with external link: ${externalLink}`,
  		await this.entitiesWithRelatedEntities(stories, "stories"),
  	);
  }

• src/tools/stories.ts:366-373 (registration)

  Registers the 'stories-get-by-external-link' tool on the MCP server, defining its name, description, input schema, and handler.

  server.addToolWithReadAccess(
  	"stories-get-by-external-link",
  	"Find all stories that contain a specific external link",
  	{
  		externalLink: z.string().url().max(2048).describe("The external link URL to search for"),
  	},
  	async ({ externalLink }) => await tools.getStoriesByExternalLink(externalLink),
  );

• src/tools/stories.ts:369-371 (schema)

  Zod input schema for the tool, validating the externalLink parameter as a URL string up to 2048 characters.

  {
  	externalLink: z.string().url().max(2048).describe("The external link URL to search for"),
  },

• src/client/shortcut.ts:518-527 (helper)

  Helper method in ShortcutClientWrapper that queries the Shortcut API for stories linked to the given external link, lowercasing the link for matching.

  async getStoriesByExternalLink(externalLink: string) {
  	const response = await this.client.getExternalLinkStories({
  		external_link: externalLink.toLowerCase(),
  	});
  	const stories = response?.data;
  
  	if (!stories) return { stories: null, total: null };
  
  	return { stories, total: stories.length };
  }