Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/epics.ts:94-107 (handler)

  The core handler function for the 'epics-search' tool. Builds search query, calls Shortcut client API, handles results and pagination, formats output with related entities.

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

• src/tools/epics.ts:29-77 (registration)

  Registers the 'epics-search' tool on the CustomMcpServer using addToolWithReadAccess, including description, input schema, and wrapper to the searchEpics handler.

  server.addToolWithReadAccess(
  	"epics-search",
  	"Find Shortcut epics.",
  	{
  		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 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 ({ nextPageToken, ...params }) => await tools.searchEpics(params, nextPageToken),
  );

• src/server.ts:49-49 (registration)

  Top-level call to EpicTools.create which initializes the EpicTools instance and registers all epic tools (including 'epics-search') on the MCP server.

  EpicTools.create(client, server);

• src/tools/epics.ts:32-76 (schema)

  Input schema (Zod object) for the 'epics-search' tool parameters, defining all searchable fields and filters.

  {
  	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 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 ({ nextPageToken, ...params }) => await tools.searchEpics(params, nextPageToken),

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

  Utility function to build the Shortcut search query string from the tool input parameters, handling key mapping, user mentions, booleans, and quoting.

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