create_cycle
Use this to initiate a new project cycle within Plane's project management system, specifying key details like start and end dates, issue tracking, and metadata through a structured API.
Instructions
Create a new cycle in a project
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cycle_data | Yes | The data for creating the cycle | |
| project_id | Yes | The uuid identifier of the project to create the cycle in |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"cycle_data": {
"additionalProperties": false,
"description": "The data for creating the cycle",
"properties": {
"archived_at": {
"format": "date-time",
"type": "string"
},
"backlog_issues": {
"type": "integer"
},
"cancelled_issues": {
"type": "integer"
},
"completed_estimates": {
"type": "number"
},
"completed_issues": {
"type": "integer"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"created_by": {
"format": "uuid",
"type": "string"
},
"deleted_at": {
"format": "date-time",
"type": "string"
},
"description": {
"type": "string"
},
"end_date": {
"description": "The end date of the cycle of format YYYY-MM-DD",
"format": "date",
"type": "string"
},
"external_id": {
"maxLength": 255,
"type": "string"
},
"external_source": {
"maxLength": 255,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"logo_props": {},
"name": {
"maxLength": 255,
"type": "string"
},
"owned_by": {
"format": "uuid",
"type": "string"
},
"progress_snapshot": {},
"project_id": {
"format": "uuid",
"type": "string"
},
"sort_order": {
"type": "number"
},
"start_date": {
"description": "The start date of the cycle of format YYYY-MM-DD",
"format": "date",
"type": "string"
},
"started_estimates": {
"type": "number"
},
"started_issues": {
"type": "integer"
},
"timezone": {},
"total_estimates": {
"type": "number"
},
"total_issues": {
"type": "integer"
},
"unstarted_issues": {
"type": "integer"
},
"updated_at": {
"format": "date-time",
"type": "string"
},
"updated_by": {
"format": "uuid",
"type": "string"
},
"version": {
"maximum": 2147483647,
"minimum": -2147483648,
"type": "integer"
},
"view_props": {},
"workspace": {
"format": "uuid",
"type": "string"
}
},
"required": [
"name",
"project_id"
],
"type": "object"
},
"project_id": {
"description": "The uuid identifier of the project to create the cycle in",
"type": "string"
}
},
"required": [
"project_id",
"cycle_data"
],
"type": "object"
}
Implementation Reference
- src/tools/cycles.ts:65-79 (handler)The main handler function that executes the create_cycle tool logic by posting cycle data to the Plane API endpoint and returning the JSON response.async ({ project_id, cycle_data }) => { const response = await makePlaneRequest( "POST", `workspaces/${process.env.PLANE_WORKSPACE_SLUG}/projects/${project_id}/cycles/`, cycle_data ); return { content: [ { type: "text", text: JSON.stringify(response, null, 2), }, ], }; }
- src/schemas.ts:3-35 (schema)Zod schema for Cycle type, imported as CycleSchema and used in create_cycle input validation with partial().required({name: true, project_id: true}).export const Cycle = z.object({ archived_at: z.string().datetime({ offset: true }).optional(), backlog_issues: z.number().int().readonly(), cancelled_issues: z.number().int().readonly(), completed_estimates: z.number().readonly(), completed_issues: z.number().int().readonly(), created_at: z.string().datetime({ offset: true }).readonly(), created_by: z.string().uuid().readonly(), deleted_at: z.string().datetime({ offset: true }).readonly(), description: z.string().optional(), end_date: z.string().date().optional().describe("The end date of the cycle of format YYYY-MM-DD"), external_id: z.string().max(255).optional(), external_source: z.string().max(255).optional(), id: z.string().uuid().readonly(), logo_props: z.any().optional(), name: z.string().max(255), owned_by: z.string().uuid().readonly(), progress_snapshot: z.any().optional(), project_id: z.string().uuid().readonly(), sort_order: z.number().optional(), start_date: z.string().date().optional().describe("The start date of the cycle of format YYYY-MM-DD"), started_estimates: z.number().readonly(), started_issues: z.number().int().readonly(), timezone: z.any().optional(), total_estimates: z.number().readonly(), total_issues: z.number().int().readonly(), unstarted_issues: z.number().int().readonly(), updated_at: z.string().datetime({ offset: true }).readonly(), updated_by: z.string().uuid().readonly(), version: z.number().int().gte(-2147483648).lte(2147483647).optional(), view_props: z.any().optional(), workspace: z.string().uuid().readonly(), });
- src/tools/cycles.ts:53-80 (registration)Direct registration of the create_cycle tool via server.tool() call within registerCycleTools, specifying name, description, input schema, and handler.server.tool( "create_cycle", "Create a new cycle in a project", { project_id: z.string().describe("The uuid identifier of the project to create the cycle in"), cycle_data: CycleSchema.partial() .required({ name: true, project_id: true, }) .describe("The data for creating the cycle"), }, async ({ project_id, cycle_data }) => { const response = await makePlaneRequest( "POST", `workspaces/${process.env.PLANE_WORKSPACE_SLUG}/projects/${project_id}/cycles/`, cycle_data ); return { content: [ { type: "text", text: JSON.stringify(response, null, 2), }, ], }; } );
- src/common/request-helper.ts:2-36 (helper)Utility function makePlaneRequest used by the create_cycle handler to perform HTTP requests to the Plane API.export async function makePlaneRequest<T>(method: string, path: string, body: any = null): Promise<T> { const hostUrl = process.env.PLANE_API_HOST_URL || "https://api.plane.so/"; const host = hostUrl.endsWith("/") ? hostUrl : `${hostUrl}/`; const url = `${host}api/v1/${path}`; const headers: Record<string, string> = { "X-API-Key": process.env.PLANE_API_KEY || "", }; // Only add Content-Type for non-GET requests if (method.toUpperCase() !== "GET") { headers["Content-Type"] = "application/json"; } try { const config: AxiosRequestConfig = { url, method, headers, }; // Only include body for non-GET requests if (method.toUpperCase() !== "GET" && body !== null) { config.data = body; } const response = await axios(config); return response.data; } catch (error) { if (axios.isAxiosError(error)) { throw new Error(`Request failed: ${error.message}`); } throw error; } }
- src/tools/index.ts:21-21 (registration)Invocation of registerCycleTools within registerTools, which includes the create_cycle tool registration.registerCycleTools(server);