Metadata-Version: 2.4
Name: ado-team-activity-mcp
Version: 0.1.0
Summary: MCP server that surfaces Azure DevOps work-item activity for a configured team roster, so VS Code Copilot Chat can answer manager-style questions like 'what did Ashish work on last week?' or 'analyze the team's last 6 months'.
Author-email: Ashish <ashish301201@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ado,azure-devops,copilot,mcp,standup,team,vscode,wiql
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.11
Requires-Dist: azure-devops>=7.1.0b4
Requires-Dist: azure-identity>=1.15.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: msrest>=0.7.1
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pyyaml>=6.0.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

# ado-team-activity-mcp

A local **Model Context Protocol (MCP) server** that lets you ask **GitHub Copilot Chat in VS Code**
manager-style questions about Azure DevOps work-item activity for your team:

> "What did Ashish work on yesterday?"
> "Summarize Priya's last 7 days."
> "Give me a team standup for the last 3 days."
> "Analyze Abhishek's last 6 months."

The server resolves the teammate name against a config roster you provide, runs WIQL
queries against Azure DevOps, and returns structured work-item data (including comments).
Copilot Chat's model produces the natural-language summary.

**Read-only by design** — no work-item creation, edits, or comments are ever made.

---

## Architecture

```
Copilot Chat  ──(MCP tool call)──►  ado-team-activity-mcp (Python, stdio)
                                          │
                                          ▼
                              Azure DevOps REST (WIQL + Work Items + Comments)
                                          ▲
                                          │
                              DefaultAzureCredential (az login)
```

### Tools exposed

| Tool | Purpose |
|---|---|
| `list_team_members()` | Return the configured roster (for name disambiguation). |
| `get_teammate_activity(name, days=?, include_comments=True)` | All work-item activity for one teammate over the window. Comments included by default. |
| `get_team_activity(days=?, include_comments=True)` | Same, looped over the whole roster, in one round-trip. |
| `summarize_contributions(name, days=180, ...)` | Aggregated stats for long windows: by-month, gaps, ownership (User Stories / Bugs), active items, cadence. Use this for perf-review / trend / quarter / "last N months" questions. |
| `get_work_item(id)` | Drill into a specific item (fields + last 10 revisions + comments). |
| `get_work_item_comments(id)` | Comments-only fetch. |

Each item in activity responses carries an `activity_reasons` list — any of
`assigned_and_changed`, `changed_by`, `created_by`, `closed_by` — so the
chat model can group its summary cleanly.

---

## Install (recommended path — for end users)

You need **Python 3.11+**, **Azure CLI**, and **VS Code** with GitHub Copilot Chat.

### 1. Install the server

[pipx](https://pipx.pypa.io) is the cleanest option (isolated venv, exposes the command globally):

```powershell
pipx install ado-team-activity-mcp
```

If you don't have pipx:

```powershell
python -m pip install --user pipx
python -m pipx ensurepath
# restart your shell, then:
pipx install ado-team-activity-mcp
```

### 2. Sign in to Azure DevOps

```powershell
az login
```

If your ADO org lives in a non-default tenant, pass it explicitly:

```powershell
az login --tenant <tenant-id>
```

### 3. Create your config

Save this as `config.yaml` somewhere stable (e.g. `C:\Users\<you>\.ado-team-activity\config.yaml`):

```yaml
organization_url: https://dev.azure.com/your-org
project: YourProject
default_lookback_days: 1
team:
  - alias: ashish
    display_name: Ashish Kumar
    unique_name: ashish@contoso.com
  - alias: priya
    display_name: Priya Sharma
    unique_name: priya@contoso.com
```

How to find the values:

- **`organization_url`** — the root of your ADO URL: `https://dev.azure.com/<org>` (no trailing slash, no project segment).
- **`project`** — the project name (case-sensitive), the segment right after the org in the URL.
- **`unique_name`** — the user's ADO sign-in (UPN). Easiest way: open any work item assigned to that teammate, click the Assignee chip, and copy the email shown under their name.
- **`alias`** — short handle you'll type in Copilot Chat. Must be unique.

> Do NOT commit `config.yaml` to source control if it contains internal info. The roster is per-manager.

### 4. Register the server with VS Code

Open VS Code's user MCP configuration:

- **Command Palette** → **"MCP: Open User Configuration"**

Add this entry under `servers`:

```jsonc
{
  "servers": {
    "ado-team-activity": {
      "type": "stdio",
      "command": "ado-team-activity-mcp",
      "env": {
        "ADO_ACTIVITY_CONFIG": "C:/Users/<you>/.ado-team-activity/config.yaml"
      }
    }
  }
}
```

Replace the `ADO_ACTIVITY_CONFIG` path with wherever you saved your `config.yaml`. Use forward slashes on Windows.

### 5. Reload the VS Code window

Then open Copilot Chat in **Agent mode** and try the prompts below.

---

## Example prompts

Day-to-day:
- `What did Ashish work on yesterday?`
- `Anything blocked on the team in the last 3 days?`
- `Give me a standup for the team for today.`
- `Tell me more about work item 12345.`
- `What's the discussion on 1738?`

Performance / trend:
- `Analyze Vibhuti's last 6 months.`
- `Compare Ashish, Vibhuti, and Abhishek over the last quarter.`
- `Is Abhishek still active in this project?`

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `ado-team-activity-mcp: command not found` | Run `pipx ensurepath`, restart shell. Or use the absolute path printed by `pipx install`. |
| `Config file not found at '...'` | Set `ADO_ACTIVITY_CONFIG` to an absolute path in your `mcp.json`. Use forward slashes. |
| `DefaultAzureCredential failed to retrieve a token` | Run `az login` (with `--tenant` if needed) and retry. |
| Zero items returned for someone you know is active | `unique_name` doesn't match ADO's UPN. Confirm by opening a work item assigned to them and copying the email from the Assignee chip exactly. |
| Roster resolves the wrong person | Add a unique `alias` for the ambiguous teammate and use it in chat. |
| Tool not visible in Copilot Chat | Reload the VS Code window after editing the user-level MCP config. |

---

## Develop locally (contributors)

```powershell
git clone <repo-url>
cd ado-team-activity-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item config.example.yaml config.yaml   # then fill in
az login
python scripts\check_auth.py                # should print "All checks passed."
pytest                                       # roster unit tests
```

The workspace's [.vscode/mcp.json](.vscode/mcp.json) is already wired for development —
it runs the server out of the local `.venv` using `python -m ado_activity_mcp`. Reload
VS Code after the install and you're ready.

### Publish a new version (maintainer)

```powershell
# bump version in pyproject.toml first
pip install --upgrade build twine
python -m build
twine upload dist/*
```

You'll need a [PyPI account](https://pypi.org/account/register/) and an API token saved
in `~/.pypirc`.

---

## Privacy & security

- **Read-only** — the server calls only `query_by_wiql`, `get_work_items`, `get_work_item`,
  `get_revisions`, `get_comments`, and `get_projects`. No create/update/delete endpoints
  anywhere in the code.
- **No telemetry** — nothing is sent anywhere except Azure DevOps (and Entra ID for the token).
- **Credentials never touch the config file** — auth is `DefaultAzureCredential`. Your token
  lives only in memory and is refreshed via your existing `az login` session.
- **Roster is local to you** — every manager maintains their own `config.yaml`.

---

## License

MIT — see [LICENSE](LICENSE).
