Shortcut MCP Server

Instructions

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"), },