search-stories

Instructions

Implementation Reference

• src/tools/stories.ts:432-444 (handler)

  The main handler function for the 'search-stories' tool. It constructs a search query from the input parameters using buildSearchQuery, calls the Shortcut client's searchStories method, and formats the results.

  async searchStories(params: QueryParams) {
  	const currentUser = await this.client.getCurrentUser();
  	const query = await buildSearchQuery(params, currentUser);
  	const { stories, total } = await this.client.searchStories(query);
  
  	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 (first ${stories.length} shown of ${total} total stories found):`,
  		await this.entitiesWithRelatedEntities(stories, "stories"),
  	);
  }

• src/tools/stories.ts:34-111 (schema)

  Zod schema defining the input parameters for the 'search-stories' tool, including optional filters for story attributes like ID, name, description, type, owner, dates, etc.

  {
  	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/stories.ts:31-113 (registration)

  Registration of the 'search-stories' tool on the MCP server, including name, description, input schema, and handler reference.

  server.tool(
  	"search-stories",
  	"Find Shortcut stories.",
  	{
  		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 (params) => await tools.searchStories(params),
  );

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

  Helper function used by the handler to build the search query string from input parameters, handling special cases for users, booleans, 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;
  };