azure-devops-work-items-mcp 1.0.0__tar.gz

azure_devops_work_items_mcp-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.DS_Store
+uv.lock

azure_devops_work_items_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Camylla Ribeiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

azure_devops_work_items_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: azure-devops-work-items-mcp
+Version: 1.0.0
+Summary: MCP server for Azure DevOps work items — read, list, create, and update, with WIQL-based filtering
+Project-URL: Repository, https://github.com/Camy-Ribeiro/azure-devops-work-items-mcp
+Author: Camylla Ribeiro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: azure-devops,mcp,model-context-protocol,work-items
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: requests>=2.31.0
+Description-Content-Type: text/markdown
+
+# azure-devops-work-items-mcp
+
+An MCP server for Azure DevOps work items: get, list/filter, create, and
+update. Filtering supports state, work item type, assignee, and area path
+directly, plus an open-ended `custom_filter` parameter that accepts a raw
+WIQL WHERE-clause fragment for anything else (sprint, priority, tags, date
+ranges, OR-logic).
+
+No organization, project, or credentials are built in — everything is
+supplied via environment variables at runtime.
+
+## Configuration
+
+Three environment variables are required:
+
+| Variable | Description |
+|---|---|
+| `AZURE_DEVOPS_ORG` | Your Azure DevOps organization name (the part after `dev.azure.com/` in your URL) |
+| `AZURE_DEVOPS_PROJECT` | The project name within that organization |
+| `AZURE_DEVOPS_PAT` | A Personal Access Token with **Work Items: Read & Write** scope, created at `https://dev.azure.com/<your-org>/_usersSettings/tokens` |
+
+## Usage with Claude Desktop (or any MCP client using `uvx`)
+
+Add this to your MCP client's config (for Claude Desktop:
+`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "azure-devops": {
+      "command": "uvx",
+      "args": ["azure-devops-work-items-mcp"],
+      "env": {
+        "AZURE_DEVOPS_ORG": "your-org-name",
+        "AZURE_DEVOPS_PROJECT": "your-project-name",
+        "AZURE_DEVOPS_PAT": "your-personal-access-token"
+      }
+    }
+  }
+}
+```
+
+Use the **full absolute path** to `uvx` (find it with `which uvx` on
+macOS/Linux or `where.exe uvx` on Windows) if your client can't find it on
+PATH — this is a known issue with some desktop apps not inheriting a full
+shell PATH.
+
+To pin to a specific version instead of always pulling the latest:
+`"args": ["azure-devops-work-items-mcp==1.0.0"]`.
+
+## Tools
+
+- `ado_get_work_item(work_item_id)`
+- `ado_list_work_items(state?, work_item_type?, assigned_to?, area_path?, custom_filter?, top?)`
+- `ado_create_work_item(work_item_type, title, description?, assigned_to?, area_path?, iteration_path?, tags?)`
+- `ado_update_work_item(work_item_id, title?, state?, description?, assigned_to?, area_path?, iteration_path?, tags?)`
+
+## License
+
+MIT

azure_devops_work_items_mcp-1.0.0/README.md

@@ -0,0 +1,60 @@
+# azure-devops-work-items-mcp
+
+An MCP server for Azure DevOps work items: get, list/filter, create, and
+update. Filtering supports state, work item type, assignee, and area path
+directly, plus an open-ended `custom_filter` parameter that accepts a raw
+WIQL WHERE-clause fragment for anything else (sprint, priority, tags, date
+ranges, OR-logic).
+
+No organization, project, or credentials are built in — everything is
+supplied via environment variables at runtime.
+
+## Configuration
+
+Three environment variables are required:
+
+| Variable | Description |
+|---|---|
+| `AZURE_DEVOPS_ORG` | Your Azure DevOps organization name (the part after `dev.azure.com/` in your URL) |
+| `AZURE_DEVOPS_PROJECT` | The project name within that organization |
+| `AZURE_DEVOPS_PAT` | A Personal Access Token with **Work Items: Read & Write** scope, created at `https://dev.azure.com/<your-org>/_usersSettings/tokens` |
+
+## Usage with Claude Desktop (or any MCP client using `uvx`)
+
+Add this to your MCP client's config (for Claude Desktop:
+`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "azure-devops": {
+      "command": "uvx",
+      "args": ["azure-devops-work-items-mcp"],
+      "env": {
+        "AZURE_DEVOPS_ORG": "your-org-name",
+        "AZURE_DEVOPS_PROJECT": "your-project-name",
+        "AZURE_DEVOPS_PAT": "your-personal-access-token"
+      }
+    }
+  }
+}
+```
+
+Use the **full absolute path** to `uvx` (find it with `which uvx` on
+macOS/Linux or `where.exe uvx` on Windows) if your client can't find it on
+PATH — this is a known issue with some desktop apps not inheriting a full
+shell PATH.
+
+To pin to a specific version instead of always pulling the latest:
+`"args": ["azure-devops-work-items-mcp==1.0.0"]`.
+
+## Tools
+
+- `ado_get_work_item(work_item_id)`
+- `ado_list_work_items(state?, work_item_type?, assigned_to?, area_path?, custom_filter?, top?)`
+- `ado_create_work_item(work_item_type, title, description?, assigned_to?, area_path?, iteration_path?, tags?)`
+- `ado_update_work_item(work_item_id, title?, state?, description?, assigned_to?, area_path?, iteration_path?, tags?)`
+
+## License
+
+MIT

azure_devops_work_items_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "azure-devops-work-items-mcp"
+version = "1.0.0"
+description = "MCP server for Azure DevOps work items — read, list, create, and update, with WIQL-based filtering"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Camylla Ribeiro" }
+]
+keywords = ["mcp", "azure-devops", "work-items", "model-context-protocol"]
+dependencies = [
+    "mcp>=1.2.0",
+    "requests>=2.31.0",
+]
+
+[project.scripts]
+azure-devops-work-items-mcp = "azure_devops_work_items_mcp.server:main"
+
+[project.urls]
+Repository = "https://github.com/Camy-Ribeiro/azure-devops-work-items-mcp"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/azure_devops_work_items_mcp"]

azure_devops_work_items_mcp-1.0.0/src/azure_devops_work_items_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Azure DevOps work items MCP server."""
+
+__version__ = "1.0.0"

azure_devops_work_items_mcp-1.0.0/src/azure_devops_work_items_mcp/ado_client.py

@@ -0,0 +1,93 @@
+"""
+Thin wrapper around the Azure DevOps REST API (Work Items only).
+
+Auth: Personal Access Token via HTTP Basic (empty username, PAT as password).
+Docs: https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/
+"""
+
+import base64
+from typing import Optional
+
+import requests
+
+API_VERSION = "7.1"
+
+
+def _raise_with_body(resp: requests.Response) -> None:
+    """Like resp.raise_for_status(), but includes the response body in the
+    error message — Azure DevOps puts the actual reason (e.g. bad WIQL,
+    invalid field, permission issue) in the JSON body, which plain
+    raise_for_status() discards."""
+    if resp.ok:
+        return
+    try:
+        detail = resp.json()
+    except ValueError:
+        detail = resp.text
+    raise requests.HTTPError(
+        f"{resp.status_code} {resp.reason} for url {resp.url}\nBody: {detail}",
+        response=resp,
+    )
+
+
+class AdoClient:
+    def __init__(self, organization: str, project: str, pat: str):
+        self.organization = organization
+        self.project = project
+        self.base_url = f"https://dev.azure.com/{organization}/{project}/_apis"
+
+        token = base64.b64encode(f":{pat}".encode()).decode()
+        self.headers = {
+            "Authorization": f"Basic {token}",
+            "Content-Type": "application/json",
+        }
+        self.patch_headers = {
+            "Authorization": f"Basic {token}",
+            "Content-Type": "application/json-patch+json",
+        }
+
+    def get_work_item(self, work_item_id: int, expand: str = "all") -> dict:
+        url = f"{self.base_url}/wit/workitems/{work_item_id}"
+        params = {"api-version": API_VERSION, "$expand": expand}
+        resp = requests.get(url, headers=self.headers, params=params, timeout=30)
+        _raise_with_body(resp)
+        return resp.json()
+
+    def query_wiql(self, wiql: str) -> list:
+        url = f"{self.base_url}/wit/wiql"
+        params = {"api-version": API_VERSION}
+        resp = requests.post(
+            url, headers=self.headers, params=params, json={"query": wiql}, timeout=30
+        )
+        _raise_with_body(resp)
+        data = resp.json()
+        return [item["id"] for item in data.get("workItems", [])]
+
+    def get_work_items_batch(self, ids: list, fields: Optional[list] = None) -> list:
+        if not ids:
+            return []
+        url = f"{self.base_url}/wit/workitems"
+        params = {"api-version": API_VERSION, "ids": ",".join(str(i) for i in ids)}
+        if fields:
+            params["fields"] = ",".join(fields)
+        resp = requests.get(url, headers=self.headers, params=params, timeout=30)
+        _raise_with_body(resp)
+        return resp.json().get("value", [])
+
+    def create_work_item(self, work_item_type: str, patch_document: list) -> dict:
+        url = f"{self.base_url}/wit/workitems/${work_item_type}"
+        params = {"api-version": API_VERSION}
+        resp = requests.post(
+            url, headers=self.patch_headers, params=params, json=patch_document, timeout=30
+        )
+        _raise_with_body(resp)
+        return resp.json()
+
+    def update_work_item(self, work_item_id: int, patch_document: list) -> dict:
+        url = f"{self.base_url}/wit/workitems/{work_item_id}"
+        params = {"api-version": API_VERSION}
+        resp = requests.patch(
+            url, headers=self.patch_headers, params=params, json=patch_document, timeout=30
+        )
+        _raise_with_body(resp)
+        return resp.json()

azure_devops_work_items_mcp-1.0.0/src/azure_devops_work_items_mcp/server.py

@@ -0,0 +1,201 @@
+"""
+Azure DevOps MCP server — work items only (create, read, update, list).
+
+Fully generic: organization, project, and PAT are all supplied via
+environment variables (AZURE_DEVOPS_ORG, AZURE_DEVOPS_PROJECT,
+AZURE_DEVOPS_PAT). None of them are hardcoded or defaulted, so this
+package carries no reference to any specific organization or project.
+
+NOTE: all @mcp.tool() definitions live above the __main__ block on purpose —
+if a tool is defined after mcp.run() is called, FastMCP never registers it.
+"""
+
+import os
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from .ado_client import AdoClient
+
+REQUIRED_ENV_VARS = ("AZURE_DEVOPS_ORG", "AZURE_DEVOPS_PROJECT", "AZURE_DEVOPS_PAT")
+
+
+def _load_config() -> tuple[str, str, str]:
+    values = {name: os.environ.get(name, "") for name in REQUIRED_ENV_VARS}
+    missing = [name for name, value in values.items() if not value]
+    if missing:
+        raise RuntimeError(
+            "Missing required environment variable(s): "
+            f"{', '.join(missing)}. Set AZURE_DEVOPS_ORG (e.g. 'my-org'), "
+            "AZURE_DEVOPS_PROJECT (e.g. 'my-project'), and AZURE_DEVOPS_PAT "
+            "(a Personal Access Token with 'Work Items: Read & Write' scope) "
+            "in the env block of your MCP client's config."
+        )
+    return values["AZURE_DEVOPS_ORG"], values["AZURE_DEVOPS_PROJECT"], values["AZURE_DEVOPS_PAT"]
+
+
+ORGANIZATION, PROJECT, PAT = _load_config()
+client = AdoClient(organization=ORGANIZATION, project=PROJECT, pat=PAT)
+
+mcp = FastMCP("azure-devops-work-items")
+
+
+def _simplify(work_item: dict) -> dict:
+    fields = work_item.get("fields", {})
+    assigned_to = fields.get("System.AssignedTo") or {}
+    return {
+        "id": work_item.get("id"),
+        "url": (work_item.get("_links", {}).get("html", {}) or {}).get("href"),
+        "title": fields.get("System.Title"),
+        "type": fields.get("System.WorkItemType"),
+        "state": fields.get("System.State"),
+        "assigned_to": assigned_to.get("displayName"),
+        "area_path": fields.get("System.AreaPath"),
+        "iteration_path": fields.get("System.IterationPath"),
+        "tags": fields.get("System.Tags"),
+        "description": fields.get("System.Description"),
+        "created_date": fields.get("System.CreatedDate"),
+        "changed_date": fields.get("System.ChangedDate"),
+    }
+
+
+def _wiql_escape(value: str) -> str:
+    """Escape single quotes for safe interpolation into a WIQL string literal."""
+    return value.replace("'", "''")
+
+
+@mcp.tool()
+def ado_get_work_item(work_item_id: int) -> dict:
+    """Get a single Azure DevOps work item by its numeric ID."""
+    item = client.get_work_item(work_item_id)
+    return _simplify(item)
+
+
+@mcp.tool()
+def ado_list_work_items(
+    state: Optional[str] = None,
+    work_item_type: Optional[str] = None,
+    assigned_to: Optional[str] = None,
+    area_path: Optional[str] = None,
+    custom_filter: Optional[str] = None,
+    top: int = 50,
+) -> list:
+    """
+    List work items in the configured project (set via AZURE_DEVOPS_PROJECT),
+    optionally filtered by state (e.g. 'Active', 'New', 'Closed'), work
+    item type (e.g. 'Bug', 'Task', 'User Story', 'Epic'), assignee (display
+    name or email), or area_path (e.g. 'MyProject\\SubArea' — matches that
+    area and any sub-areas under it). Returns up to `top` items, most
+    recently changed first.
+
+    For anything not covered by the parameters above (sprint/iteration,
+    tags, priority, custom fields, date ranges, OR-logic, etc.), pass a raw
+    WIQL WHERE-clause fragment via `custom_filter` — it is ANDed together
+    with the other filters. Reference fields by their WIQL name in square
+    brackets. Examples:
+      - Sprint:        "[System.IterationPath] UNDER 'MyProject\\\\Sprint 24'"
+      - Priority:      "[Microsoft.VSTS.Common.Priority] = 1"
+      - Tags:          "[System.Tags] CONTAINS 'urgent'"
+      - Date range:    "[System.CreatedDate] >= '2026-06-01'"
+      - OR-logic:      "([System.Tags] CONTAINS 'urgent' OR [Microsoft.VSTS.Common.Priority] = 1)"
+    String literals inside custom_filter must use single quotes; escape a
+    literal single quote by doubling it ('').
+    """
+    conditions = [f"[System.TeamProject] = '{_wiql_escape(PROJECT)}'"]
+    if state:
+        conditions.append(f"[System.State] = '{_wiql_escape(state)}'")
+    if work_item_type:
+        conditions.append(f"[System.WorkItemType] = '{_wiql_escape(work_item_type)}'")
+    if assigned_to:
+        conditions.append(f"[System.AssignedTo] = '{_wiql_escape(assigned_to)}'")
+    if area_path:
+        conditions.append(f"[System.AreaPath] UNDER '{_wiql_escape(area_path)}'")
+    if custom_filter:
+        conditions.append(f"({custom_filter})")
+
+    wiql = (
+        "SELECT [System.Id] FROM WorkItems "
+        f"WHERE {' AND '.join(conditions)} "
+        "ORDER BY [System.ChangedDate] DESC"
+    )
+    ids = client.query_wiql(wiql)[:top]
+    items = client.get_work_items_batch(ids)
+    return [_simplify(item) for item in items]
+
+
+@mcp.tool()
+def ado_create_work_item(
+    work_item_type: str,
+    title: str,
+    description: Optional[str] = None,
+    assigned_to: Optional[str] = None,
+    area_path: Optional[str] = None,
+    iteration_path: Optional[str] = None,
+    tags: Optional[str] = None,
+) -> dict:
+    """
+    Create a new Azure DevOps work item in the configured project.
+    work_item_type is e.g. 'Bug', 'Task', 'User Story', 'Epic'.
+    area_path/iteration_path default to the project root if omitted.
+    tags is a semicolon-separated string, e.g. 'urgent;client-facing'.
+    """
+    patch = [{"op": "add", "path": "/fields/System.Title", "value": title}]
+    if description:
+        patch.append({"op": "add", "path": "/fields/System.Description", "value": description})
+    if assigned_to:
+        patch.append({"op": "add", "path": "/fields/System.AssignedTo", "value": assigned_to})
+    if area_path:
+        patch.append({"op": "add", "path": "/fields/System.AreaPath", "value": area_path})
+    if iteration_path:
+        patch.append(
+            {"op": "add", "path": "/fields/System.IterationPath", "value": iteration_path}
+        )
+    if tags:
+        patch.append({"op": "add", "path": "/fields/System.Tags", "value": tags})
+
+    item = client.create_work_item(work_item_type, patch)
+    return _simplify(item)
+
+
+@mcp.tool()
+def ado_update_work_item(
+    work_item_id: int,
+    title: Optional[str] = None,
+    state: Optional[str] = None,
+    description: Optional[str] = None,
+    assigned_to: Optional[str] = None,
+    area_path: Optional[str] = None,
+    iteration_path: Optional[str] = None,
+    tags: Optional[str] = None,
+) -> dict:
+    """
+    Update fields on an existing Azure DevOps work item. Only fields you
+    provide are changed; everything else is left as-is.
+    """
+    field_map = {
+        "System.Title": title,
+        "System.State": state,
+        "System.Description": description,
+        "System.AssignedTo": assigned_to,
+        "System.AreaPath": area_path,
+        "System.IterationPath": iteration_path,
+        "System.Tags": tags,
+    }
+    patch = [
+        {"op": "add", "path": f"/fields/{field}", "value": value}
+        for field, value in field_map.items()
+        if value is not None
+    ]
+    if not patch:
+        raise ValueError("Provide at least one field to update.")
+
+    item = client.update_work_item(work_item_id, patch)
+    return _simplify(item)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()