Merge pull request #1 from qike-ms/feature/wiql-query-support

Add WIQL query support and improve documentation

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,110 @@
+# 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

README.md

@@ -71,6 +71,7 @@ Interact with these Azure DevOps services:
 - **wit_get_work_item_type**: Get a specific work item type.
 - **wit_get_query**: Get a query by its ID or path.
 - **wit_get_query_results_by_id**: Retrieve the results of a work item query given the query ID.
+- **wit_query_by_wiql**: Execute a WIQL query to retrieve work items.
 - **wit_update_work_items_batch**: Update work items in batch.
 - **wit_work_items_link**: Link work items together in batch.
 - **wit_work_item_unlink**: Unlink one or many links from a work item.
@@ -211,6 +212,28 @@ Open GitHub Copilot Chat and try a prompt like `List ADO projects`.
 > 💥 We strongly recommend creating a `.github\copilot-instructions.md` in your project. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
 > To start, just include "`This project uses Azure DevOps. Always check to see if the Azure DevOps MCP server has a tool relevant to the user's request`" in your copilot instructions file.
 
+#### 🤖 Claude Code
+
+To add the Azure DevOps MCP Server to Claude Code, use the following command:
+
+```bash
+claude mcp add mcp-ado 'npx -y @azure-devops/mcp ado_org_name' --scope user
+```
+
+For example:
+
+```bash
+claude mcp add mcp-ado 'npx -y @azure-devops/mcp msazure' --scope user
+```
+
+Replace `msazure` with your Azure DevOps organization name. You can also use `--scope project` to limit the server to a specific project.
+
+For development with a local installation:
+
+```bash
+claude mcp add mcp-ado 'npx -y ~/git/azure-devops-mcp msazure' --scope user
+```
+
 See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Claude Code, and Cursor.
 
 ## 📝 Troubleshooting

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",