azure-devops MCP Server

Instructions

Implementation Reference

• src/tools/workItems.ts:17-77 (handler)

  The handler function that implements the core logic for listing work items using Azure DevOps WIQL query, fetching details, and returning formatted response.

  export async function listWorkItems(rawParams: any) {
    // Parse arguments with defaults from environment variables
    const params = listWorkItemsSchema.parse({
      project: rawParams.project || DEFAULT_PROJECT,
      types: rawParams.types,
      states: rawParams.states,
      assignedTo: rawParams.assignedTo,
    });
  
    console.error("[API] Listing work items:", params);
  
    try {
      // Get the Work Item Tracking API client
      const witClient = await getWorkItemClient();
  
      // Build WIQL query
      let wiql = `SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType], [System.AssignedTo] FROM WorkItems WHERE [System.TeamProject] = '${params.project}'`;
  
      if (params.types && params.types.length > 0) {
        wiql += ` AND [System.WorkItemType] IN ('${params.types.join("','")}')`;
      }
  
      if (params.states && params.states.length > 0) {
        wiql += ` AND [System.State] IN ('${params.states.join("','")}')`;
      }
  
      if (params.assignedTo) {
        wiql += ` AND [System.AssignedTo] = '${params.assignedTo}'`;
      }
  
      // Execute the query
      const queryResult = await witClient.queryByWiql({ query: wiql });
  
      if (!queryResult.workItems) {
        return {
          content: [{ type: "text", text: JSON.stringify([], null, 2) }],
        };
      }
  
      // Get full work item details
      const workItems = await witClient.getWorkItems(
        queryResult.workItems.map(
          (wi: WorkItemInterfaces.WorkItemReference) => wi.id!
        ),
        undefined,
        undefined
      );
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(workItems, null, 2),
          },
        ],
      };
    } catch (error) {
      logError("Error listing work items", error);
      throw error;
    }
  }

• src/schemas/workItems.ts:6-13 (schema)

  Zod schema for validating input parameters to listWorkItems function, with project required and others optional.

  export const listWorkItemsSchema = z.object({
    project: z.string(),
    types: z.array(z.string()).optional(),
    states: z.array(z.string()).optional(),
    assignedTo: z.string().optional(),
  });
  
  export type ListWorkItemsParams = z.infer<typeof listWorkItemsSchema>;

• src/index.ts:69-70 (registration)

  Registration of the tool handler in the MCP server's CallToolRequestSchema switch statement.

  case "list_work_items":
    return await listWorkItems(request.params.arguments || {});

• src/tools/workItems.ts:219-246 (registration)

  Tool definition object exported in workItemTools array, used for MCP ListTools response defining the tool's name, description, and input schema.

  {
    name: "list_work_items",
    description: "List work items in a project",
    inputSchema: {
      type: "object",
      properties: {
        project: {
          type: "string",
          description: "Name of the Azure DevOps project",
        },
        types: {
          type: "array",
          items: { type: "string" },
          description: "Filter by work item types",
        },
        states: {
          type: "array",
          items: { type: "string" },
          description: "Filter by states",
        },
        assignedTo: {
          type: "string",
          description: "Filter by assigned user",
        },
      },
      required: ["project"],
    },
  },

• src/index.ts:50-63 (registration)

  MCP server handler for ListToolsRequestSchema that includes workItemTools in the tools list for registration.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        // Work Items
        ...workItemTools,
        // Pull Requests
        ...pullRequestTools,
        // Wiki
        ...wikiTools,
        // Projects
        ...projectTools,
      ],
    };
  });