Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:29-117 (registration)

  Registration of the 'stories-search' tool using server.addToolWithReadAccess. Includes the tool name, description, comprehensive input schema using Zod for various search parameters, and references the 'searchStories' handler method.

  server.addToolWithReadAccess(
  	"stories-search",
  	"Find Shortcut stories.",
  	{
  		nextPageToken: z
  			.string()
  			.optional()
  			.describe(
  				"If a next_page_token was returned from the search result, pass it in to get the next page of results. Should be combined with the original search parameters.",
  			),
  		id: z.number().optional().describe("Find only stories with the specified public ID"),
  		name: z.string().optional().describe("Find only stories matching the specified name"),
  		description: z
  			.string()
  			.optional()
  			.describe("Find only stories matching the specified description"),
  		comment: z.string().optional().describe("Find only stories matching the specified comment"),
  		type: z
  			.enum(["feature", "bug", "chore"])
  			.optional()
  			.describe("Find only stories of the specified type"),
  		estimate: z
  			.number()
  			.optional()
  			.describe("Find only stories matching the specified estimate"),
  		branch: z.string().optional().describe("Find only stories matching the specified branch"),
  		commit: z.string().optional().describe("Find only stories matching the specified commit"),
  		pr: z.number().optional().describe("Find only stories matching the specified pull request"),
  		project: z.number().optional().describe("Find only stories matching the specified project"),
  		epic: z.number().optional().describe("Find only stories matching the specified epic"),
  		objective: z
  			.number()
  			.optional()
  			.describe("Find only stories matching the specified objective"),
  		state: z.string().optional().describe("Find only stories matching the specified state"),
  		label: z.string().optional().describe("Find only stories matching the specified label"),
  		owner: user("owner"),
  		requester: user("requester"),
  		team: z
  			.string()
  			.optional()
  			.describe(
  				"Find only stories matching the specified team. This can be a team mention name or team name.",
  			),
  		skillSet: z
  			.string()
  			.optional()
  			.describe("Find only stories matching the specified skill set"),
  		productArea: z
  			.string()
  			.optional()
  			.describe("Find only stories matching the specified product area"),
  		technicalArea: z
  			.string()
  			.optional()
  			.describe("Find only stories matching the specified technical area"),
  		priority: z
  			.string()
  			.optional()
  			.describe("Find only stories matching the specified priority"),
  		severity: z
  			.string()
  			.optional()
  			.describe("Find only stories matching the specified severity"),
  		isDone: is("completed"),
  		isStarted: is("started"),
  		isUnstarted: is("unstarted"),
  		isUnestimated: is("unestimated"),
  		isOverdue: is("overdue"),
  		isArchived: is("archived").default(false),
  		isBlocker: is("blocking"),
  		isBlocked: is("blocked"),
  		hasComment: has("a comment"),
  		hasLabel: has("a label"),
  		hasDeadline: has("a deadline"),
  		hasOwner: has("an owner"),
  		hasPr: has("a pr"),
  		hasCommit: has("a commit"),
  		hasBranch: has("a branch"),
  		hasEpic: has("an epic"),
  		hasTask: has("a task"),
  		hasAttachment: has("an attachment"),
  		created: date(),
  		updated: date(),
  		completed: date(),
  		due: date(),
  	},
  	async ({ nextPageToken, ...params }) => await tools.searchStories(params, nextPageToken),
  );

• src/tools/stories.ts:558-571 (handler)

  The handler function 'searchStories' that executes the tool logic. Fetches current user, builds search query using 'buildSearchQuery' helper, calls the Shortcut client's 'searchStories' method, handles results and pagination, formats output with 'entitiesWithRelatedEntities'.

  async searchStories(params: QueryParams, nextToken?: string) {
  	const currentUser = await this.client.getCurrentUser();
  	const query = await buildSearchQuery(params, currentUser);
  	const { stories, total, next_page_token } = await this.client.searchStories(query, nextToken);
  
  	if (!stories) throw new Error(`Failed to search for stories matching your query: "${query}".`);
  	if (!stories.length) return this.toResult(`Result: No stories found.`);
  
  	return this.toResult(
  		`Result (${stories.length} shown of ${total} total stories found):`,
  		await this.entitiesWithRelatedEntities(stories, "stories"),
  		next_page_token,
  	);
  }

• src/tools/stories.ts:32-115 (schema)

  Detailed Zod input schema for 'stories-search' tool, defining optional parameters for filtering stories by ID, name, description, type, state, labels, owners, dates, and various status flags.

  {
  	nextPageToken: z
  		.string()
  		.optional()
  		.describe(
  			"If a next_page_token was returned from the search result, pass it in to get the next page of results. Should be combined with the original search parameters.",
  		),
  	id: z.number().optional().describe("Find only stories with the specified public ID"),
  	name: z.string().optional().describe("Find only stories matching the specified name"),
  	description: z
  		.string()
  		.optional()
  		.describe("Find only stories matching the specified description"),
  	comment: z.string().optional().describe("Find only stories matching the specified comment"),
  	type: z
  		.enum(["feature", "bug", "chore"])
  		.optional()
  		.describe("Find only stories of the specified type"),
  	estimate: z
  		.number()
  		.optional()
  		.describe("Find only stories matching the specified estimate"),
  	branch: z.string().optional().describe("Find only stories matching the specified branch"),
  	commit: z.string().optional().describe("Find only stories matching the specified commit"),
  	pr: z.number().optional().describe("Find only stories matching the specified pull request"),
  	project: z.number().optional().describe("Find only stories matching the specified project"),
  	epic: z.number().optional().describe("Find only stories matching the specified epic"),
  	objective: z
  		.number()
  		.optional()
  		.describe("Find only stories matching the specified objective"),
  	state: z.string().optional().describe("Find only stories matching the specified state"),
  	label: z.string().optional().describe("Find only stories matching the specified label"),
  	owner: user("owner"),
  	requester: user("requester"),
  	team: z
  		.string()
  		.optional()
  		.describe(
  			"Find only stories matching the specified team. This can be a team mention name or team name.",
  		),
  	skillSet: z
  		.string()
  		.optional()
  		.describe("Find only stories matching the specified skill set"),
  	productArea: z
  		.string()
  		.optional()
  		.describe("Find only stories matching the specified product area"),
  	technicalArea: z
  		.string()
  		.optional()
  		.describe("Find only stories matching the specified technical area"),
  	priority: z
  		.string()
  		.optional()
  		.describe("Find only stories matching the specified priority"),
  	severity: z
  		.string()
  		.optional()
  		.describe("Find only stories matching the specified severity"),
  	isDone: is("completed"),
  	isStarted: is("started"),
  	isUnstarted: is("unstarted"),
  	isUnestimated: is("unestimated"),
  	isOverdue: is("overdue"),
  	isArchived: is("archived").default(false),
  	isBlocker: is("blocking"),
  	isBlocked: is("blocked"),
  	hasComment: has("a comment"),
  	hasLabel: has("a label"),
  	hasDeadline: has("a deadline"),
  	hasOwner: has("an owner"),
  	hasPr: has("a pr"),
  	hasCommit: has("a commit"),
  	hasBranch: has("a branch"),
  	hasEpic: has("an epic"),
  	hasTask: has("a task"),
  	hasAttachment: has("an attachment"),
  	created: date(),
  	updated: date(),
  	completed: date(),
  	due: date(),
  },

• src/tools/utils/search.ts:19-36 (helper)

  'buildSearchQuery' utility function called by the handler to construct the Shortcut search query string from input parameters, handling key mapping, special cases for users ('me'), booleans (negation), numbers, and quoted strings.

  export const buildSearchQuery = async (params: QueryParams, currentUser: MemberInfo | null) => {
  	const query = Object.entries(params)
  		.map(([key, value]) => {
  			const q = getKey(key);
  			if (key === "owner" || key === "requester") {
  				if (value === "me") return `${q}:${currentUser?.mention_name || value}`;
  				return `${q}:${String(value || "").replace(/^@/, "")}`;
  			}
  
  			if (typeof value === "boolean") return value ? q : `!${q}`;
  			if (typeof value === "number") return `${q}:${value}`;
  			if (typeof value === "string" && value.includes(" ")) return `${q}:"${value}"`;
  			return `${q}:${value}`;
  		})
  		.join(" ");
  
  	return query;
  };