search-iterations
Search and filter Shortcut iterations by ID, name, description, state, team, or date ranges to find specific project management cycles.
Instructions
Find Shortcut iterations.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Find only iterations with the specified public ID | |
| name | No | Find only iterations matching the specified name | |
| description | No | Find only iterations matching the specified description | |
| state | No | Find only iterations matching the specified state | |
| team | No | Find only iterations matching the specified team. This can be a team ID or mention name. | |
| created | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| updated | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| startDate | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| endDate | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). |
Input Schema (JSON Schema)
{
"properties": {
"created": {
"description": "The date in \"YYYY-MM-DD\" format, or one of the keywords: \"yesterday\", \"today\", \"tomorrow\", or a date range in the format \"YYYY-MM-DD..YYYY-MM-DD\". The date range can also be open ended by using \"*\" for one of the bounds. Examples: \"2023-01-01\", \"today\", \"2023-01-01..*\" (from Jan 1, 2023 to any future date), \"*.2023-01-31\" (any date up to Jan 31, 2023), \"today..*\" (from today onwards), \"*.yesterday\" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: \"today-1\" or \"tomorrow+1\").",
"pattern": "^(today|tomorrow|yesterday|\\d{4}-\\d{2}-\\d{2}|today\\.\\.\\*|\\*\\.\\.today|yesterday\\.\\.\\*|\\*\\.\\.yesterday|tomorrow\\.\\.\\*|\\*\\.\\.tomorrow|\\d{4}-\\d{2}-\\d{2}\\.\\.\\*|\\*\\.\\.\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}\\.\\.\\d{4}-\\d{2}-\\d{2})$",
"type": "string"
},
"description": {
"description": "Find only iterations matching the specified description",
"type": "string"
},
"endDate": {
"description": "The date in \"YYYY-MM-DD\" format, or one of the keywords: \"yesterday\", \"today\", \"tomorrow\", or a date range in the format \"YYYY-MM-DD..YYYY-MM-DD\". The date range can also be open ended by using \"*\" for one of the bounds. Examples: \"2023-01-01\", \"today\", \"2023-01-01..*\" (from Jan 1, 2023 to any future date), \"*.2023-01-31\" (any date up to Jan 31, 2023), \"today..*\" (from today onwards), \"*.yesterday\" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: \"today-1\" or \"tomorrow+1\").",
"pattern": "^(today|tomorrow|yesterday|\\d{4}-\\d{2}-\\d{2}|today\\.\\.\\*|\\*\\.\\.today|yesterday\\.\\.\\*|\\*\\.\\.yesterday|tomorrow\\.\\.\\*|\\*\\.\\.tomorrow|\\d{4}-\\d{2}-\\d{2}\\.\\.\\*|\\*\\.\\.\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}\\.\\.\\d{4}-\\d{2}-\\d{2})$",
"type": "string"
},
"id": {
"description": "Find only iterations with the specified public ID",
"type": "number"
},
"name": {
"description": "Find only iterations matching the specified name",
"type": "string"
},
"startDate": {
"description": "The date in \"YYYY-MM-DD\" format, or one of the keywords: \"yesterday\", \"today\", \"tomorrow\", or a date range in the format \"YYYY-MM-DD..YYYY-MM-DD\". The date range can also be open ended by using \"*\" for one of the bounds. Examples: \"2023-01-01\", \"today\", \"2023-01-01..*\" (from Jan 1, 2023 to any future date), \"*.2023-01-31\" (any date up to Jan 31, 2023), \"today..*\" (from today onwards), \"*.yesterday\" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: \"today-1\" or \"tomorrow+1\").",
"pattern": "^(today|tomorrow|yesterday|\\d{4}-\\d{2}-\\d{2}|today\\.\\.\\*|\\*\\.\\.today|yesterday\\.\\.\\*|\\*\\.\\.yesterday|tomorrow\\.\\.\\*|\\*\\.\\.tomorrow|\\d{4}-\\d{2}-\\d{2}\\.\\.\\*|\\*\\.\\.\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}\\.\\.\\d{4}-\\d{2}-\\d{2})$",
"type": "string"
},
"state": {
"description": "Find only iterations matching the specified state",
"enum": [
"started",
"unstarted",
"done"
],
"type": "string"
},
"team": {
"description": "Find only iterations matching the specified team. This can be a team ID or mention name.",
"type": "string"
},
"updated": {
"description": "The date in \"YYYY-MM-DD\" format, or one of the keywords: \"yesterday\", \"today\", \"tomorrow\", or a date range in the format \"YYYY-MM-DD..YYYY-MM-DD\". The date range can also be open ended by using \"*\" for one of the bounds. Examples: \"2023-01-01\", \"today\", \"2023-01-01..*\" (from Jan 1, 2023 to any future date), \"*.2023-01-31\" (any date up to Jan 31, 2023), \"today..*\" (from today onwards), \"*.yesterday\" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: \"today-1\" or \"tomorrow+1\").",
"pattern": "^(today|tomorrow|yesterday|\\d{4}-\\d{2}-\\d{2}|today\\.\\.\\*|\\*\\.\\.today|yesterday\\.\\.\\*|\\*\\.\\.yesterday|tomorrow\\.\\.\\*|\\*\\.\\.tomorrow|\\d{4}-\\d{2}-\\d{2}\\.\\.\\*|\\*\\.\\.\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}\\.\\.\\d{4}-\\d{2}-\\d{2})$",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/tools/iterations.ts:118-131 (handler)Executes the core logic of the 'search-iterations' tool by constructing a search query and retrieving matching iterations from the Shortcut API.async searchIterations(params: QueryParams) { const currentUser = await this.client.getCurrentUser(); const query = await buildSearchQuery(params, currentUser); const { iterations, total } = await this.client.searchIterations(query); if (!iterations) throw new Error(`Failed to search for iterations matching your query: "${query}".`); if (!iterations.length) return this.toResult(`Result: No iterations found.`); return this.toResult( `Result (first ${iterations.length} shown of ${total} total iterations found):`, await this.entitiesWithRelatedEntities(iterations, "iterations"), ); }
- src/tools/iterations.ts:42-64 (schema)Input schema using Zod for validating tool parameters such as id, name, description, state, team, and date fields.{ id: z.number().optional().describe("Find only iterations with the specified public ID"), name: z.string().optional().describe("Find only iterations matching the specified name"), description: z .string() .optional() .describe("Find only iterations matching the specified description"), state: z .enum(["started", "unstarted", "done"]) .optional() .describe("Find only iterations matching the specified state"), team: z .string() .optional() .describe( "Find only iterations matching the specified team. This can be a team ID or mention name.", ), created: date(), updated: date(), startDate: date(), endDate: date(), }, async (params) => await tools.searchIterations(params),
- src/tools/iterations.ts:39-66 (registration)Registers the 'search-iterations' MCP tool with the server, specifying name, description, input schema, and handler.server.tool( "search-iterations", "Find Shortcut iterations.", { id: z.number().optional().describe("Find only iterations with the specified public ID"), name: z.string().optional().describe("Find only iterations matching the specified name"), description: z .string() .optional() .describe("Find only iterations matching the specified description"), state: z .enum(["started", "unstarted", "done"]) .optional() .describe("Find only iterations matching the specified state"), team: z .string() .optional() .describe( "Find only iterations matching the specified team. This can be a team ID or mention name.", ), created: date(), updated: date(), startDate: date(), endDate: date(), }, async (params) => await tools.searchIterations(params), );
- src/tools/utils/search.ts:19-36 (helper)Utility function that constructs the search query string from input parameters, handling special keys like owner, booleans, numbers, and quoted strings; used by the handler.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; };