Add support to run wiql queries in the work items tool.

modified:   src/tools/workitems.ts

Author: qike-ms

.gitignore

@@ -135,4 +135,9 @@ dist
 .yarn/unplugged
 .yarn/build-state.yml
 .yarn/install-state.gz
-.pnp.*
+.pnp.*
+
+# Claude code
+.mcp.json
+.claude/
+

CLAUDE.md

@@ -0,0 +1,95 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an Azure DevOps MCP (Model Context Protocol) Server that provides access to Azure DevOps services through standardized tools. The server enables AI agents to interact with Azure DevOps APIs for managing projects, work items, builds, releases, repositories, and more.
+
+## Development Commands
+
+### Building and Development
+- `npm run build` - Compile TypeScript to JavaScript in `dist/` directory
+- `npm run watch` - Watch mode for continuous compilation during development
+- `npm run prepare` - Runs build automatically (used by npm lifecycle)
+- `npm run clean` - Remove the `dist/` directory
+- `npm run validate-tools` - Validate tool names and TypeScript compilation
+
+### Code Quality
+- `npm run eslint` - Run ESLint linter
+- `npm run eslint-fix` - Run ESLint with automatic fixes
+- `npm run format` - Format code with Prettier
+- `npm run format-check` - Check code formatting without making changes
+
+### Testing
+- `npm test` - Run Jest test suite
+- Coverage thresholds are set to 40% for branches, functions, lines, and statements
+- Test files are located in `test/` directory and follow the pattern `**/?(*.)+(spec|test).[jt]s?(x)`
+
+### Running the Server
+- `npm start` - Start the MCP server (requires Azure DevOps organization name as argument)
+- `npm run inspect` - Run the server with MCP inspector for debugging
+
+### Local Development Setup
+For source installation (development mode):
+1. Clone repository and run `npm install`
+2. Configure `.vscode/mcp.json` with local command: `"mcp-server-azuredevops"`
+3. The server requires an Azure DevOps organization name as the first argument
+
+## Architecture
+
+### Core Components
+- **Entry Point**: `src/index.ts` - Main server initialization, Azure authentication, and MCP server setup
+- **Tool Configuration**: `src/tools.ts` - Aggregates all tool modules and configures them with the MCP server
+- **Authentication**: Uses `@azure/identity` with `DefaultAzureCredential` for Azure DevOps API access
+- **Client Setup**: Creates Azure DevOps WebApi clients with proper user agent and authentication
+
+### Tool Organization
+Tools are organized by Azure DevOps service area in `src/tools/`:
+- `core.ts` - Projects and teams management
+- `work.ts` - Iterations and team work management
+- `workitems.ts` - Work item CRUD operations and queries
+- `repos.ts` - Repository and pull request management
+- `builds.ts` - Build pipelines and execution
+- `releases.ts` - Release management
+- `testplans.ts` - Test planning and execution
+- `wiki.ts` - Wiki content management
+- `search.ts` - Search across code, wiki, and work items
+- `advsec.ts` - Advanced Security alerts management
+- `auth.ts` - Authentication utilities
+
+### Key Patterns
+- Each tool module follows the pattern: `configure[ServiceName]Tools(server, tokenProvider, connectionProvider, ...)`
+- All tools use Zod schemas for input validation and JSON schema generation
+- Authentication is handled centrally through token and connection providers
+- User agent composition includes package version and MCP client information
+
+### Environment Variables
+- `ADO_MCP_AZURE_TOKEN_CREDENTIALS` - Optional override for Azure token credentials
+- Falls back to `AZURE_TOKEN_CREDENTIALS = "dev"` for development
+
+### Project Structure
+- `src/` - TypeScript source code
+- `dist/` - Compiled JavaScript output (created by build)
+- `test/` - Jest test files with mocks in `test/mocks/`
+- `docs/` - Documentation files (FAQ, HOWTO, TROUBLESHOOTING)
+
+## Important Notes
+
+### Adding New Tools
+- Follow existing patterns in tool modules under `src/tools/`
+- Use Azure DevOps TypeScript clients when available, fall back to direct API calls only when necessary
+- Add tool configuration to `configureAllTools()` in `src/tools.ts`
+- Include comprehensive input validation with Zod schemas
+- Follow the established naming convention: `[service]_[action]_[object]`
+
+### Testing
+- Mock Azure DevOps API responses in `test/mocks/`
+- Test files mirror the source structure in `test/src/`
+- Use Jest with ts-jest preset for TypeScript support
+
+### Code Quality Standards
+- TypeScript with strict mode enabled
+- ESLint configuration with Prettier integration
+- All files must include Microsoft copyright headers
+- Follow existing code patterns for consistency

src/tools/workitems.ts

@@ -4,7 +4,7 @@
 import { AccessToken } from "@azure/identity";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebApi } from "azure-devops-node-api";
-import { WorkItemExpand, WorkItemRelation } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
+import { WorkItemExpand, WorkItemRelation, Wiql } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { QueryExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { z } from "zod";
 import { batchApiVersion, markdownCommentsApiVersion, getEnumKeys, safeEnumConvert } from "../utils.js";
@@ -25,6 +25,7 @@ const WORKITEM_TOOLS = {
   get_work_item_type: "wit_get_work_item_type",
   get_query: "wit_get_query",
   get_query_results_by_id: "wit_get_query_results_by_id",
+  query_by_wiql: "wit_query_by_wiql",
   update_work_items_batch: "wit_update_work_items_batch",
   work_items_link: "wit_work_items_link",
   work_item_unlink: "wit_work_item_unlink",
@@ -633,6 +634,26 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
     }
   );
 
+  server.tool(
+    WORKITEM_TOOLS.query_by_wiql,
+    "Execute a WIQL query to retrieve work items.",
+    {
+      wiql: z.string().describe("The WIQL query string to execute."),
+      top: z.number().optional().describe("The maximum number of results to return."),
+    },
+    async ({ wiql, top }) => {
+      const connection = await connectionProvider();
+      const workItemApi = await connection.getWorkItemTrackingApi();
+      
+      const wiqlObject: Wiql = { query: wiql };
+      const queryResult = await workItemApi.queryByWiql(wiqlObject, undefined, undefined, top);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(queryResult, null, 2) }],
+      };
+    }
+  );
+
   server.tool(
     WORKITEM_TOOLS.update_work_items_batch,
     "Update work items in batch",