search-objectives
Search and filter Shortcut objectives by ID, name, description, state, owner, team, or date criteria to find specific project goals.
Instructions
Find Shortcut objectives.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Find objectives matching the specified id | |
| name | No | Find objectives matching the specified name | |
| description | No | Find objectives matching the specified description | |
| state | No | Find objectives matching the specified state | |
| owner | No | Find entities where the owner match the specified user. This must either be the user's mention name or the keyword "me" for the current user. | |
| requester | No | Find entities where the requester match the specified user. This must either be the user's mention name or the keyword "me" for the current user. | |
| team | No | Find objectives matching the specified team. Should be a team mention name. | |
| isUnstarted | No | Find only entities that are unstarted when true, or only entities that are not unstarted when false. | |
| isStarted | No | Find only entities that are started when true, or only entities that are not started when false. | |
| isDone | No | Find only entities that are completed when true, or only entities that are not completed when false. | |
| isArchived | No | Find only entities that are archived when true, or only entities that are not archived when false. | |
| hasOwner | No | Find only entities that have an owner when true, or only entities that do not have an owner when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| 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"). | |
| completed | 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"). |
Implementation Reference
- src/tools/objectives.ts:56-69 (handler)The main handler function for the 'search-objectives' tool. It builds a search query using buildSearchQuery, searches for milestones (objectives) via the Shortcut client, handles empty results, and formats the output using inherited methods.
async searchObjectives(params: QueryParams) { const currentUser = await this.client.getCurrentUser(); const query = await buildSearchQuery(params, currentUser); const { milestones, total } = await this.client.searchMilestones(query); 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 (first ${milestones.length} shown of ${total} total milestones found):`, await this.entitiesWithRelatedEntities(milestones, "objectives"), ); } - src/tools/objectives.ts:25-49 (schema)Zod input schema defining parameters for searching objectives, including filters for id, name, description, state, owner, team, status flags, and dates.
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(), }, - src/tools/objectives.ts:21-51 (registration)Registers the 'search-objectives' tool on the MCP server with description, input schema, and handler reference.
server.tool( "search-objectives", "Find Shortcut objectives.", { 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 (params) => await tools.searchObjectives(params), ); - src/server.ts:36-36 (registration)Invokes ObjectiveTools.create to register all objective-related tools, including 'search-objectives', on the main MCP server.
ObjectiveTools.create(client, server);