az-devops-cli-mcp 1.0.2__tar.gz

az_devops_cli_mcp-1.0.2/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `az-devops-cli-mcp` will be documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.0.0] — Initial Release
+
+### Added
+- 13 MCP tools covering Azure DevOps Boards and Repos
+- Work items: create, get, update, set_iteration, query, link, verify relations, comment
+- Repos/PRs: list, get, create, link to work item, list branches
+- stdio MCP transport — compatible with Claude Code and Codex CLI
+- TOON (Token-Oriented Object Notation) response format
+- Destructive command guard (delete/remove/destroy blocked by default)
+- Auto org detection from `az devops configure` or `AZURE_DEVOPS_ORG` env var
+- AG2 tools library interface via `from az_devops_cli_mcp import ALL_TOOLS`

az_devops_cli_mcp-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LytStore Team
+
+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.

az_devops_cli_mcp-1.0.2/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml

az_devops_cli_mcp-1.0.2/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: az-devops-cli-mcp
+Version: 1.0.2
+Summary: Azure DevOps CLI MCP server for Claude Code and Codex CLI — boards, work items, repos, PRs
+Author: LytStore Team
+License: MIT
+Project-URL: Homepage, https://github.com/PraiseSinkamba/az-devops-cli-mcp
+Project-URL: Repository, https://github.com/PraiseSinkamba/az-devops-cli-mcp
+Project-URL: Issues, https://github.com/PraiseSinkamba/az-devops-cli-mcp/issues
+Project-URL: Changelog, https://github.com/PraiseSinkamba/az-devops-cli-mcp/blob/main/CHANGELOG.md
+Keywords: azure,devops,mcp,claude,codex,boards,work-items
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: ag2
+Requires-Dist: pyautogen>=0.2.0; extra == "ag2"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# az-devops-cli-mcp
+
+Azure DevOps MCP tools for **Claude Code** and **Codex CLI** — boards, work items, repos, and PRs.
+
+[![PyPI version](https://img.shields.io/pypi/v/az-devops-cli-mcp)](https://pypi.org/project/az-devops-cli-mcp/)
+[![CI](https://github.com/PraiseSinkamba/az-devops-cli-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/PraiseSinkamba/az-devops-cli-mcp/actions)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/az-devops-cli-mcp)](https://pypi.org/project/az-devops-cli-mcp/)
+
+---
+
+## Install & Register
+
+```bash
+# 1. Install
+pip install az-devops-cli-mcp
+
+# 2. Login (once per machine)
+az login
+az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG
+
+# 3. Register with Claude Code
+claude mcp add az-devops-cli-mcp -- python -m az_devops_cli_mcp.server
+
+# 4. Register with Codex CLI
+codex mcp add az-devops-cli-mcp -- python -m az_devops_cli_mcp.server
+```
+
+Restart Claude Code or Codex CLI. All 13 tools are ready.
+
+---
+
+## How It Works
+
+The server runs as a **stdio process** — spawned on demand by the client, no ports or background services needed.
+
+```
+Claude Code / Codex CLI
+        |  spawns on demand
+        v
+python -m az_devops_cli_mcp.server   (stdin/stdout)
+        |
+        v
+      az CLI  (your az login session)
+```
+
+---
+
+## Available Tools (13 total)
+
+### Work Items
+| Tool | What it does |
+|---|---|
+| `create_work_item` | Create Task, Bug, User Story, Epic |
+| `get_work_item` | Get item by ID |
+| `update_work_item` | Update state, assignment, title |
+| `set_iteration` | Assign to sprint (required for Sprint board) |
+| `query_work_items` | WIQL query for bulk lookups |
+| `link_work_items` | Link items (Child, Parent, Related) |
+| `get_work_item_relations` | Verify hierarchy after linking |
+| `add_comment` | Add discussion comment / agent log |
+
+### Repos / PRs
+| Tool | What it does |
+|---|---|
+| `list_prs` | List PRs by status |
+| `get_pr` | Get PR details |
+| `create_pr` | Open a new PR |
+| `link_pr_to_work_item` | Trace PR to work item |
+| `list_branches` | List repo branches |
+
+---
+
+## AG2 Usage (optional)
+
+```python
+from autogen import ConversableAgent
+from az_devops_cli_mcp import ALL_TOOLS, WORK_ITEM_TOOLS, REPO_TOOLS
+
+agent = ConversableAgent(
+    name="devops_agent",
+    tools=ALL_TOOLS,
+    system_message="You manage Azure DevOps for LytStore..."
+)
+```
+
+---
+
+## Configuration
+
+| Method | How |
+|---|---|
+| `az devops configure` | Preferred — org set globally for your machine |
+| `AZURE_DEVOPS_ORG` env var | Per-session override |
+| `.env` file | `AZURE_DEVOPS_ORG=https://dev.azure.com/YOUR_ORG` |
+
+---
+
+## Safety
+
+Destructive commands (`delete`, `remove`, `destroy`) are blocked at the core layer.
+The agent returns an error and requires explicit user confirmation.
+
+---
+
+## Manual MCP Config (fallback)
+
+If `claude mcp add` / `codex mcp add` aren't available, add this to your config file manually.
+
+**Claude Code** — `~/.claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "az-devops-cli-mcp": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "az_devops_cli_mcp.server"]
+    }
+  }
+}
+```
+
+**Codex CLI** — `~/.codex/config.json`: same block.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/PraiseSinkamba/az-devops-cli-mcp
+cd az-devops-cli-mcp
+pip install -e ".[dev]"
+pytest tests/
+```

az_devops_cli_mcp-1.0.2/README.md

@@ -0,0 +1,133 @@
+# az-devops-cli-mcp
+
+Azure DevOps MCP tools for **Claude Code** and **Codex CLI** — boards, work items, repos, and PRs.
+
+[![PyPI version](https://img.shields.io/pypi/v/az-devops-cli-mcp)](https://pypi.org/project/az-devops-cli-mcp/)
+[![CI](https://github.com/PraiseSinkamba/az-devops-cli-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/PraiseSinkamba/az-devops-cli-mcp/actions)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/az-devops-cli-mcp)](https://pypi.org/project/az-devops-cli-mcp/)
+
+---
+
+## Install & Register
+
+```bash
+# 1. Install
+pip install az-devops-cli-mcp
+
+# 2. Login (once per machine)
+az login
+az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG
+
+# 3. Register with Claude Code
+claude mcp add az-devops-cli-mcp -- python -m az_devops_cli_mcp.server
+
+# 4. Register with Codex CLI
+codex mcp add az-devops-cli-mcp -- python -m az_devops_cli_mcp.server
+```
+
+Restart Claude Code or Codex CLI. All 13 tools are ready.
+
+---
+
+## How It Works
+
+The server runs as a **stdio process** — spawned on demand by the client, no ports or background services needed.
+
+```
+Claude Code / Codex CLI
+        |  spawns on demand
+        v
+python -m az_devops_cli_mcp.server   (stdin/stdout)
+        |
+        v
+      az CLI  (your az login session)
+```
+
+---
+
+## Available Tools (13 total)
+
+### Work Items
+| Tool | What it does |
+|---|---|
+| `create_work_item` | Create Task, Bug, User Story, Epic |
+| `get_work_item` | Get item by ID |
+| `update_work_item` | Update state, assignment, title |
+| `set_iteration` | Assign to sprint (required for Sprint board) |
+| `query_work_items` | WIQL query for bulk lookups |
+| `link_work_items` | Link items (Child, Parent, Related) |
+| `get_work_item_relations` | Verify hierarchy after linking |
+| `add_comment` | Add discussion comment / agent log |
+
+### Repos / PRs
+| Tool | What it does |
+|---|---|
+| `list_prs` | List PRs by status |
+| `get_pr` | Get PR details |
+| `create_pr` | Open a new PR |
+| `link_pr_to_work_item` | Trace PR to work item |
+| `list_branches` | List repo branches |
+
+---
+
+## AG2 Usage (optional)
+
+```python
+from autogen import ConversableAgent
+from az_devops_cli_mcp import ALL_TOOLS, WORK_ITEM_TOOLS, REPO_TOOLS
+
+agent = ConversableAgent(
+    name="devops_agent",
+    tools=ALL_TOOLS,
+    system_message="You manage Azure DevOps for LytStore..."
+)
+```
+
+---
+
+## Configuration
+
+| Method | How |
+|---|---|
+| `az devops configure` | Preferred — org set globally for your machine |
+| `AZURE_DEVOPS_ORG` env var | Per-session override |
+| `.env` file | `AZURE_DEVOPS_ORG=https://dev.azure.com/YOUR_ORG` |
+
+---
+
+## Safety
+
+Destructive commands (`delete`, `remove`, `destroy`) are blocked at the core layer.
+The agent returns an error and requires explicit user confirmation.
+
+---
+
+## Manual MCP Config (fallback)
+
+If `claude mcp add` / `codex mcp add` aren't available, add this to your config file manually.
+
+**Claude Code** — `~/.claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "az-devops-cli-mcp": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "az_devops_cli_mcp.server"]
+    }
+  }
+}
+```
+
+**Codex CLI** — `~/.codex/config.json`: same block.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/PraiseSinkamba/az-devops-cli-mcp
+cd az-devops-cli-mcp
+pip install -e ".[dev]"
+pytest tests/
+```

az_devops_cli_mcp-1.0.2/az_devops_cli_mcp/__init__.py

@@ -0,0 +1,54 @@
+"""
+az-devops-cli-mcp
+===============
+Azure DevOps CLI MCP server — boards, work items, repos, PRs.
+
+Usage in your agent:
+    from az_devops_cli_mcp import ALL_TOOLS, WORK_ITEM_TOOLS, REPO_TOOLS
+"""
+
+from az_devops_cli_mcp.tools.work_items import (
+    create_work_item,
+    get_work_item,
+    update_work_item,
+    set_iteration,
+    query_work_items,
+    link_work_items,
+    get_work_item_relations,
+    add_comment,
+)
+
+from az_devops_cli_mcp.tools.repos import (
+    list_prs,
+    get_pr,
+    create_pr,
+    link_pr_to_work_item,
+    list_branches,
+)
+
+WORK_ITEM_TOOLS = [
+    create_work_item,
+    get_work_item,
+    update_work_item,
+    set_iteration,
+    query_work_items,
+    link_work_items,
+    get_work_item_relations,
+    add_comment,
+]
+
+REPO_TOOLS = [
+    list_prs,
+    get_pr,
+    create_pr,
+    link_pr_to_work_item,
+    list_branches,
+]
+
+ALL_TOOLS = WORK_ITEM_TOOLS + REPO_TOOLS
+
+__all__ = [
+    "ALL_TOOLS",
+    "WORK_ITEM_TOOLS",
+    "REPO_TOOLS",
+]

az_devops_cli_mcp-1.0.2/az_devops_cli_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""
+Allows: python -m az_devops_cli_mcp.server
+and:    python -m az_devops_cli_mcp  (same thing)
+"""
+from az_devops_cli_mcp.server import run
+run()

az_devops_cli_mcp-1.0.2/az_devops_cli_mcp/config.py

@@ -0,0 +1,50 @@
+"""
+az_devops_cli_mcp.config
+======================
+Resolves the Azure DevOps org URL in this priority order:
+
+  1. AZURE_DEVOPS_ORG environment variable  (or .env file)
+  2. az devops configure --list             (whatever the user already set)
+
+This means each team member just runs:
+  az login
+  az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG
+
+...and the tools pick it up automatically.
+No hardcoded values, no shared secrets.
+"""
+
+import subprocess
+import os
+from dotenv import load_dotenv
+
+load_dotenv()  # load .env if present (optional, never required)
+
+
+def get_org() -> str:
+    """
+    Resolve the Azure DevOps org URL.
+    Raises RuntimeError if neither env var nor az defaults are set.
+    """
+    # 1. Env override
+    org = os.getenv("AZURE_DEVOPS_ORG", "").strip()
+    if org:
+        return org
+
+    # 2. Read from az devops configure --list
+    result = subprocess.run(
+        "az devops configure --list",
+        shell=True, capture_output=True, text=True
+    )
+    for line in result.stdout.splitlines():
+        if line.strip().startswith("organization"):
+            _, _, value = line.partition("=")
+            org = value.strip()
+            if org:
+                return org
+
+    raise RuntimeError(
+        "No Azure DevOps org configured.\n"
+        "Run: az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG\n"
+        "Or set AZURE_DEVOPS_ORG in your environment."
+    )

az_devops_cli_mcp-1.0.2/az_devops_cli_mcp/core.py

@@ -0,0 +1,76 @@
+"""
+az_devops_cli_mcp.core
+====================
+Shared helpers used by all tool modules.
+"""
+
+import json
+import subprocess
+from az_devops_cli_mcp.config import get_org
+
+BLOCKED_COMMANDS = ["delete", "remove", "destroy"]
+
+
+def az(args: str) -> dict | list:
+    """
+    Execute an az CLI command against the configured org.
+    Returns parsed JSON on success, {"error": "..."} on failure.
+    Blocks destructive commands until the user confirms.
+    """
+    if any(cmd in args.lower() for cmd in BLOCKED_COMMANDS):
+        return {
+            "error": (
+                f"Blocked: destructive command detected in '{args}'. "
+                "Confirm with user before proceeding."
+            )
+        }
+
+    try:
+        org = get_org()
+    except RuntimeError as e:
+        return {"error": str(e)}
+
+    result = subprocess.run(
+        f"az {args} --output json --org {org}",
+        shell=True,
+        capture_output=True,
+        text=True
+    )
+
+    if result.returncode != 0:
+        return {"error": result.stderr.strip()}
+
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return {"error": f"Failed to parse response: {result.stdout.strip()}"}
+
+
+def toon(data: dict | list, summary: str) -> str:
+    """
+    Token-Oriented Object Notation:
+      Flat dict/list  → key=value pipe-separated   (token-efficient)
+      Nested objects  → full JSON fallback
+      Error dict      → [ERROR] prefix
+    Always prepends a summary line.
+    """
+    if isinstance(data, dict) and "error" in data:
+        return f"[ERROR] {data['error']}"
+
+    def is_flat(obj: dict) -> bool:
+        return isinstance(obj, dict) and all(
+            not isinstance(v, (dict, list)) for v in obj.values()
+        )
+
+    if isinstance(data, dict) and is_flat(data):
+        body = " | ".join(f"{k}={v}" for k, v in data.items())
+
+    elif isinstance(data, list) and all(is_flat(i) for i in data):
+        body = "(none)" if not data else "\n".join(
+            " | ".join(f"{k}={v}" for k, v in item.items())
+            for item in data
+        )
+    else:
+        body = json.dumps(data, indent=2)
+
+    return f"[{summary}]\n{body}"