get-epic
Retrieve Shortcut epic details by public ID using the MCP server. Optionally, fetch all fields for comprehensive data or a slim version for essential information.
Instructions
Get a Shortcut epic by public ID
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| epicPublicId | Yes | The public ID of the epic to get | |
| full | No | True to return all epic fields from the API. False to return a slim version that excludes uncommon fields |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"epicPublicId": {
"description": "The public ID of the epic to get",
"exclusiveMinimum": 0,
"type": "number"
},
"full": {
"default": false,
"description": "True to return all epic fields from the API. False to return a slim version that excludes uncommon fields",
"type": "boolean"
}
},
"required": [
"epicPublicId"
],
"type": "object"
}
Implementation Reference
- src/tools/epics.ts:109-118 (handler)Main handler function implementing the logic to retrieve a specific epic by its public ID, fetch it via the Shortcut client, handle errors, and format the response with related entities.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:13-27 (registration)Tool registration for 'epics-get-by-id' (likely invoked as 'get-epic' in MCP context), including description, input schema, and links to the getEpic handler.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), );
- src/tools/epics.ts:16-25 (schema)Zod schema defining input parameters: epicPublicId (required number) and full (optional boolean, defaults to 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/base.ts:601-623 (helper)Helper function used by getEpic to simplify and enrich the epic entity with related entities (users, teams, etc.). Called as this.entityWithRelatedEntities(epic, "epic", full).protected async entityWithRelatedEntities( entity: | Story | StorySearchResult | StorySlim | Epic | EpicSearchResult | Iteration | IterationSlim | Group | Workflow | ObjectiveSearchResult | Milestone, entityType = "entity", full = false, ) { const finalEntity = full ? entity : this.getSimplifiedEntity(entity, "simple"); const relatedEntities = await this.getRelatedEntities(entity, full ? "full" : "simple"); return { [entityType]: this.renameEntityProps(finalEntity as unknown as Record<string, unknown>), relatedEntities, }; }
- src/client/shortcut.ts:229-236 (helper)Client wrapper method that calls the underlying Shortcut API to fetch the raw epic data by public ID.async getEpic(epicPublicId: number) { const response = await this.client.getEpic(epicPublicId); const epic = response?.data ?? null; if (!epic) return null; return epic; }