get_work_item

Instructions

Implementation Reference

• src/features/work-items/get-work-item/feature.ts:18-111 (handler)

  Core handler function that fetches a work item by ID from Azure DevOps API, optionally expands fields, and enriches the result with all possible fields for the work item type.

  /**
   * Maps string-based expansion options to the WorkItemExpand enum
   */
  const expandMap: Record<string, WorkItemExpand> = {
    none: WorkItemExpand.None,
    relations: WorkItemExpand.Relations,
    fields: WorkItemExpand.Fields,
    links: WorkItemExpand.Links,
    all: WorkItemExpand.All,
  };
  
  /**
   * Get a work item by ID
   *
   * @param connection The Azure DevOps WebApi connection
   * @param workItemId The ID of the work item
   * @param expand Optional expansion options (defaults to 'all')
   * @returns The work item details
   * @throws {AzureDevOpsResourceNotFoundError} If the work item is not found
   */
  export async function getWorkItem(
    connection: WebApi,
    workItemId: number,
    expand: string = 'all',
  ): Promise<WorkItem> {
    try {
      const witApi = await connection.getWorkItemTrackingApi();
  
      const workItem = await witApi.getWorkItem(
        workItemId,
        undefined,
        undefined,
        expandMap[expand.toLowerCase()],
      );
  
      if (!workItem) {
        throw new AzureDevOpsResourceNotFoundError(
          `Work item '${workItemId}' not found`,
        );
      }
  
      // Extract project and work item type to get all possible fields
      const projectName = workItem.fields?.['System.TeamProject'];
      const workItemType = workItem.fields?.['System.WorkItemType'];
  
      if (!projectName || !workItemType) {
        // If we can't determine the project or type, return the original work item
        return workItem;
      }
  
      // Get all possible fields for this work item type
      const allFields =
        workItemTypeFieldsCache[projectName.toString()]?.[
          workItemType.toString()
        ] ??
        (await witApi.getWorkItemTypeFieldsWithReferences(
          projectName.toString(),
          workItemType.toString(),
          WorkItemTypeFieldsExpandLevel.All,
        ));
  
      workItemTypeFieldsCache[projectName.toString()] = {
        ...workItemTypeFieldsCache[projectName.toString()],
        [workItemType.toString()]: allFields,
      };
  
      // Create a new work item object with all fields
      const enhancedWorkItem = { ...workItem };
  
      // Initialize fields object if it doesn't exist
      if (!enhancedWorkItem.fields) {
        enhancedWorkItem.fields = {};
      }
  
      // Set null for all potential fields that don't have values
      for (const field of allFields) {
        if (
          field.referenceName &&
          !(field.referenceName in enhancedWorkItem.fields)
        ) {
          enhancedWorkItem.fields[field.referenceName] = field.defaultValue;
        }
      }
  
      return enhancedWorkItem;
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
      throw new Error(
        `Failed to get work item: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/work-items/schemas.ts:7-15 (schema)

  Zod schema defining input validation for get_work_item: workItemId (number) and expand (optional enum).

  export const GetWorkItemSchema = z.object({
    workItemId: z.number().describe('The ID of the work item'),
    expand: z
      .enum(['none', 'relations', 'fields', 'links', 'all'])
      .optional()
      .describe(
        'The level of detail to include in the response. Defaults to "all" if not specified.',
      ),
  });

• src/features/work-items/tool-definitions.ts:14-40 (registration)

  Tool registration definition for 'get_work_item', linking the name and description to the schema.

  export const workItemsTools: ToolDefinition[] = [
    {
      name: 'list_work_items',
      description: 'List work items in a project',
      inputSchema: zodToJsonSchema(ListWorkItemsSchema),
    },
    {
      name: 'get_work_item',
      description: 'Get details of a specific work item',
      inputSchema: zodToJsonSchema(GetWorkItemSchema),
    },
    {
      name: 'create_work_item',
      description: 'Create a new work item',
      inputSchema: zodToJsonSchema(CreateWorkItemSchema),
    },
    {
      name: 'update_work_item',
      description: 'Update an existing work item',
      inputSchema: zodToJsonSchema(UpdateWorkItemSchema),
    },
    {
      name: 'manage_work_item_link',
      description: 'Add or remove links between work items',
      inputSchema: zodToJsonSchema(ManageWorkItemLinkSchema),
    },
  ];

• src/features/work-items/index.ts:60-148 (registration)

  Request dispatch handler that routes 'get_work_item' calls to the getWorkItem function with parsed arguments.

  export const handleWorkItemsRequest: RequestHandler = async (
    connection: WebApi,
    request: CallToolRequest,
  ): Promise<CallToolResponse> => {
    switch (request.params.name) {
      case 'get_work_item': {
        const args = GetWorkItemSchema.parse(request.params.arguments);
        const result = await getWorkItem(
          connection,
          args.workItemId,
          args.expand,
        );
        return {
          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        };
      }
      case 'list_work_items': {
        const args = ListWorkItemsSchema.parse(request.params.arguments);
        const result = await listWorkItems(connection, {
          projectId: args.projectId ?? defaultProject,
          teamId: args.teamId,
          queryId: args.queryId,
          wiql: args.wiql,
          top: args.top,
          skip: args.skip,
        });
        return {
          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        };
      }
      case 'create_work_item': {
        const args = CreateWorkItemSchema.parse(request.params.arguments);
        const result = await createWorkItem(
          connection,
          args.projectId ?? defaultProject,
          args.workItemType,
          {
            title: args.title,
            description: args.description,
            assignedTo: args.assignedTo,
            areaPath: args.areaPath,
            iterationPath: args.iterationPath,
            priority: args.priority,
            parentId: args.parentId,
            additionalFields: args.additionalFields,
          },
        );
        return {
          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        };
      }
      case 'update_work_item': {
        const args = UpdateWorkItemSchema.parse(request.params.arguments);
        const result = await updateWorkItem(connection, args.workItemId, {
          title: args.title,
          description: args.description,
          assignedTo: args.assignedTo,
          areaPath: args.areaPath,
          iterationPath: args.iterationPath,
          priority: args.priority,
          state: args.state,
          additionalFields: args.additionalFields,
        });
        return {
          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        };
      }
      case 'manage_work_item_link': {
        const args = ManageWorkItemLinkSchema.parse(request.params.arguments);
        const result = await manageWorkItemLink(
          connection,
          args.projectId ?? defaultProject,
          {
            sourceWorkItemId: args.sourceWorkItemId,
            targetWorkItemId: args.targetWorkItemId,
            operation: args.operation,
            relationType: args.relationType,
            newRelationType: args.newRelationType,
            comment: args.comment,
          },
        );
        return {
          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        };
      }
      default:
        throw new Error(`Unknown work items tool: ${request.params.name}`);
    }
  };