get-stories-by-external-link

Find Shortcut stories containing a specific external URL to track references and dependencies across project management tasks.

Instructions

Find all stories that contain a specific external link

Input Schema

TableJSON Schema

Name	Required	Description	Default
`externalLink`	Yes	The external link URL to search for

Implementation Reference

src/tools/stories.ts:300-307 (registration)

Registration of the 'get-stories-by-external-link' tool with MCP server, defining the tool name, description, input schema using Zod, and the handler function.

server.tool(
	"get-stories-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:647-660 (handler)

Core handler function that performs the tool's logic: validates input, calls the Shortcut client to retrieve stories linked to the external URL, and formats the response using toResult and entitiesWithRelatedEntities.

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/client/shortcut.ts:462-471 (helper)

Supporting method in ShortcutClientWrapper that wraps the official Shortcut API call to fetch stories by external link, normalizing the link to lowercase and handling response.

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 };
}

src/tools/stories.ts:304-305 (schema)
Input schema validation using Zod for the externalLink parameter: must be a valid URL, max 2048 chars.
```
	externalLink: z.string().url().max(2048).describe("The external link URL to search for"),
},
```

Shortcut MCP Server