search-epics

Instructions

Implementation Reference

• src/tools/epics.ts:79-91 (handler)

  The handler function that implements the core logic of the 'search-epics' tool. It constructs a search query, fetches epics from the Shortcut client, handles edge cases, and formats the results.

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

• src/tools/epics.ts:23-60 (schema)

  Zod schema defining all input parameters and validations for the 'search-epics' tool, including optional filters for ID, name, description, state, owner, etc.

  {
  	id: z.number().optional().describe("Find only epics with the specified public ID"),
  	name: z.string().optional().describe("Find only epics matching the specified name"),
  	description: z
  		.string()
  		.optional()
  		.describe("Find only epics matching the specified description"),
  	state: z
  		.enum(["unstarted", "started", "done"])
  		.optional()
  		.describe("Find only epics matching the specified state"),
  	objective: z
  		.number()
  		.optional()
  		.describe("Find only epics matching the specified objective"),
  	owner: user("owner"),
  	requester: user("requester"),
  	team: z
  		.string()
  		.optional()
  		.describe(
  			"Find only epics matching the specified team. Should be a team's mention name.",
  		),
  	comment: z.string().optional().describe("Find only epics matching the specified comment"),
  	isUnstarted: is("unstarted"),
  	isStarted: is("started"),
  	isDone: is("completed"),
  	isArchived: is("archived").default(false),
  	isOverdue: is("overdue"),
  	hasOwner: has("an owner"),
  	hasComment: has("a comment"),
  	hasDeadline: has("a deadline"),
  	hasLabel: has("a label"),
  	created: date(),
  	updated: date(),
  	completed: date(),
  	due: date(),
  },

• src/tools/epics.ts:20-62 (registration)

  Registers the 'search-epics' tool with the MCP server, specifying name, description, input schema, and handler function.

  server.tool(
  	"search-epics",
  	"Find Shortcut epics.",
  	{
  		id: z.number().optional().describe("Find only epics with the specified public ID"),
  		name: z.string().optional().describe("Find only epics matching the specified name"),
  		description: z
  			.string()
  			.optional()
  			.describe("Find only epics matching the specified description"),
  		state: z
  			.enum(["unstarted", "started", "done"])
  			.optional()
  			.describe("Find only epics matching the specified state"),
  		objective: z
  			.number()
  			.optional()
  			.describe("Find only epics matching the specified objective"),
  		owner: user("owner"),
  		requester: user("requester"),
  		team: z
  			.string()
  			.optional()
  			.describe(
  				"Find only epics matching the specified team. Should be a team's mention name.",
  			),
  		comment: z.string().optional().describe("Find only epics matching the specified comment"),
  		isUnstarted: is("unstarted"),
  		isStarted: is("started"),
  		isDone: is("completed"),
  		isArchived: is("archived").default(false),
  		isOverdue: is("overdue"),
  		hasOwner: has("an owner"),
  		hasComment: has("a comment"),
  		hasDeadline: has("a deadline"),
  		hasLabel: has("a label"),
  		created: date(),
  		updated: date(),
  		completed: date(),
  		due: date(),
  	},
  	async (params) => await tools.searchEpics(params),
  );

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

  Helper utility to build the Shortcut search query string from the tool input parameters, handling special cases for owners/requesters, 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;
  };