Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/objectives.ts:28-64 (registration)

  Registers the 'objectives-search' MCP tool using server.addToolWithReadAccess, including the tool name, description, input schema, and handler reference.

  server.addToolWithReadAccess(
  	"objectives-search",
  	"Find Shortcut objectives.",
  	{
  		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 objectives matching the specified id"),
  		name: z.string().optional().describe("Find objectives matching the specified name"),
  		description: z
  			.string()
  			.optional()
  			.describe("Find objectives matching the specified description"),
  		state: z
  			.enum(["unstarted", "started", "done"])
  			.optional()
  			.describe("Find objectives matching the specified state"),
  		owner: user("owner"),
  		requester: user("requester"),
  		team: z
  			.string()
  			.optional()
  			.describe("Find objectives matching the specified team. Should be a team mention name."),
  		isUnstarted: is("unstarted"),
  		isStarted: is("started"),
  		isDone: is("completed"),
  		isArchived: is("archived"),
  		hasOwner: has("an owner"),
  		created: date(),
  		updated: date(),
  		completed: date(),
  	},
  	async ({ nextPageToken, ...params }) => await tools.searchObjectives(params, nextPageToken),
  );

• src/tools/objectives.ts:69-86 (handler)

  Handler function that performs the objectives search: builds query, calls Shortcut client searchMilestones, formats results with pagination.

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

• src/tools/objectives.ts:31-62 (schema)

  Input schema using Zod validators for the 'objectives-search' tool parameters, including pagination, filters by id, name, state, users, dates, etc.

  {
  	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 objectives matching the specified id"),
  	name: z.string().optional().describe("Find objectives matching the specified name"),
  	description: z
  		.string()
  		.optional()
  		.describe("Find objectives matching the specified description"),
  	state: z
  		.enum(["unstarted", "started", "done"])
  		.optional()
  		.describe("Find objectives matching the specified state"),
  	owner: user("owner"),
  	requester: user("requester"),
  	team: z
  		.string()
  		.optional()
  		.describe("Find objectives matching the specified team. Should be a team mention name."),
  	isUnstarted: is("unstarted"),
  	isStarted: is("started"),
  	isDone: is("completed"),
  	isArchived: is("archived"),
  	hasOwner: has("an owner"),
  	created: date(),
  	updated: date(),
  	completed: date(),
  },