search-objectives
Find Shortcut objectives by filtering with criteria like ID, name, state, owner, team, or date ranges to locate specific project goals.
Instructions
Find Shortcut objectives.
Input 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"). |
Input Schema (JSON Schema)
{
"properties": {
"completed": {
"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"
},
"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 objectives matching the specified description",
"type": "string"
},
"hasOwner": {
"description": "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.",
"type": "boolean"
},
"id": {
"description": "Find objectives matching the specified id",
"type": "number"
},
"isArchived": {
"description": "Find only entities that are archived when true, or only entities that are not archived when false.",
"type": "boolean"
},
"isDone": {
"description": "Find only entities that are completed when true, or only entities that are not completed when false.",
"type": "boolean"
},
"isStarted": {
"description": "Find only entities that are started when true, or only entities that are not started when false.",
"type": "boolean"
},
"isUnstarted": {
"description": "Find only entities that are unstarted when true, or only entities that are not unstarted when false.",
"type": "boolean"
},
"name": {
"description": "Find objectives matching the specified name",
"type": "string"
},
"owner": {
"description": "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.",
"type": "string"
},
"requester": {
"description": "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.",
"type": "string"
},
"state": {
"description": "Find objectives matching the specified state",
"enum": [
"unstarted",
"started",
"done"
],
"type": "string"
},
"team": {
"description": "Find objectives matching the specified team. Should be a team 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/objectives.ts:56-69 (handler)Executes the 'search-objectives' tool: fetches current user, builds search query using buildSearchQuery helper, searches milestones (objectives) via client, and formats results.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:24-49 (schema)Input schema for 'search-objectives' tool using Zod validators for various query filters like id, name, state, owner, dates, etc.{ 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' MCP tool with name, description, input schema, and handler delegating to ObjectiveTools.searchObjectives method.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), );