Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/epics.ts:109-118 (handler)

  The main handler function that executes the tool logic: fetches the epic by public ID from the Shortcut client, handles errors, and formats the result using inherited helper methods.

  async getEpic(epicPublicId: number, full = false) {
  	const epic = await this.client.getEpic(epicPublicId);
  
  	if (!epic) throw new Error(`Failed to retrieve Shortcut epic with public ID: ${epicPublicId}`);
  
  	return this.toResult(
  		`Epic: ${epicPublicId}`,
  		await this.entityWithRelatedEntities(epic, "epic", full),
  	);
  }

• src/tools/epics.ts:16-25 (schema)

  Input schema defined using Zod for validating tool parameters: epicPublicId (positive number) and optional full (boolean, default false).

  {
  	epicPublicId: z.number().positive().describe("The public ID of the epic to get"),
  	full: z
  		.boolean()
  		.optional()
  		.default(false)
  		.describe(
  			"True to return all epic fields from the API. False to return a slim version that excludes uncommon fields",
  		),
  },

• src/tools/epics.ts:13-27 (registration)

  Registers the "epics-get-by-id" tool on the CustomMcpServer with read access, description, input schema, and a handler that delegates to the getEpic method.

  server.addToolWithReadAccess(
  	"epics-get-by-id",
  	"Get a Shortcut epic by public ID",
  	{
  		epicPublicId: z.number().positive().describe("The public ID of the epic to get"),
  		full: z
  			.boolean()
  			.optional()
  			.default(false)
  			.describe(
  				"True to return all epic fields from the API. False to return a slim version that excludes uncommon fields",
  			),
  	},
  	async ({ epicPublicId, full }) => await tools.getEpic(epicPublicId, full),
  );