Create Item

Instructions

Implementation Reference

• src/tools/item-write.ts:14-15 (registration)

  Tool registration: 'create_item' is registered with the MCP server via server.registerTool() in registerItemWriteTools(). The registration call lives at line 14-91.

  server.registerTool(
    "create_item",

• src/tools/item-write.ts:22-69 (schema)

  Input schema for 'create_item' using Zod definitions. Defines trackerId (required), name (required), and optionals: description, statusId, priorityId, assignedToIds, storyPoints, isFolder, itemTypeName, parentId.

  inputSchema: {
    trackerId: z
      .number()
      .int()
      .positive()
      .describe("Numeric tracker ID to create the item in"),
    name: z.string().min(1).describe("Item summary / title"),
    description: z
      .string()
      .optional()
      .describe("Item description (plain text or wiki markup)"),
    statusId: z
      .number()
      .int()
      .positive()
      .optional()
      .describe("Status ID (use get_tracker to see available statuses)"),
    priorityId: z
      .number()
      .int()
      .positive()
      .optional()
      .describe("Priority ID (use get_tracker to see available priorities)"),
    assignedToIds: z
      .array(z.number().int().positive())
      .optional()
      .describe("Array of user IDs to assign"),
    storyPoints: z
      .number()
      .int()
      .min(0)
      .optional()
      .describe("Story points estimate"),
    isFolder: z
      .boolean()
      .optional()
      .describe("Set to true to create a folder item instead of a regular item"),
    itemTypeName: z
      .string()
      .optional()
      .describe("Item type name as configured in the tracker (e.g. 'Folder', 'Informative'). Overrides isFolder."),
    parentId: z
      .number()
      .int()
      .positive()
      .optional()
      .describe("Parent item ID to nest this item inside (e.g. a folder)"),
  },

• src/tools/item-write.ts:71-90 (handler)

  Handler function for 'create_item'. Builds a CbCreateItemRequest object from the input parameters (optionally fetching the tracker schema to resolve item type), calls client.createItem(), and formats the result.

  async ({ trackerId, name, description, statusId, priorityId, assignedToIds, storyPoints, isFolder, itemTypeName, parentId }) => {
    const data: CbCreateItemRequest = { name };
    const desiredType = itemTypeName ?? (isFolder ? "Folder" : undefined);
    if (desiredType) {
      const schema = await client.getTrackerSchema(trackerId);
      const typeField = schema.find((f) => f.trackerItemField === "categories" || f.legacyRestName === "type");
      const option = typeField?.options?.find((o) => o.name.toLowerCase() === desiredType.toLowerCase());
      if (option) {
        data.categories = [{ id: option.id, type: "ChoiceOptionReference" }];
      }
    }
    if (description !== undefined) data.description = description;
    if (statusId !== undefined) data.status = { id: statusId };
    if (priorityId !== undefined) data.priority = { id: priorityId };
    if (assignedToIds !== undefined) data.assignedTo = assignedToIds.map((id) => ({ id }));
    if (storyPoints !== undefined) data.storyPoints = storyPoints;
  
    const item = await client.createItem(trackerId, data, parentId);
    return { content: [{ type: "text", text: formatItem(item) }] };
  },

• src/client/codebeamer-client.ts:133-142 (helper)

  Request type CbCreateItemRequest defines the data shape sent to the API when creating an item.

  export interface CbCreateItemRequest {
    name: string;
    description?: string;
    categories?: Array<{ id: number; type: string }>;
    status?: { id: number };
    priority?: { id: number };
    assignedTo?: Array<{ id: number }>;
    storyPoints?: number;
    customFields?: Array<{ fieldId: number; type: string; value: unknown }>;
  }

• src/client/codebeamer-client.ts:332-338 (helper)

  Client method that sends the POST request to /trackers/{trackerId}/items with optional parentItemId query parameter.

  createItem(trackerId: number, data: CbCreateItemRequest, parentId?: number): Promise<CbItem> {
    return this.http.post(`/trackers/${trackerId}/items`, {
      params: parentId !== undefined ? { parentItemId: parentId } : undefined,
      body: data,
      resource: `create item in tracker ${trackerId}`,
    });
  }