ado-workflows-mcp 0.1.0__tar.gz

ado_workflows_mcp-0.1.0/.copilot/README.md

@@ -0,0 +1,13 @@
+# .copilot Directory
+
+This directory contains development notes, collaboration documents, and scripts used during development with GitHub Copilot. These files are excluded from git commits.
+
+## Purpose
+
+This folder is for:
+- Development notes and design discussions
+- Scripts and tools used during development
+- AI collaboration artifacts
+- Temporary documentation
+
+None of these files are needed for the extension to function or for others to contribute to the project.

ado_workflows_mcp-0.1.0/.envrc

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# Auto-activate uv virtual environment
+if ! has uv; then
+    echo "❌ uv is not installed. Please install it first:"
+    echo "   curl -LsSf https://astral.sh/uv/install.sh | sh"
+    exit 1
+fi
+
+# Create virtual environment if it doesn't exist
+if [[ ! -d ".venv" ]]; then
+    echo "📦 Creating virtual environment with uv..."
+    uv venv
+fi
+
+# Activate the virtual environment
+source .venv/bin/activate
+
+# Source .envrc.local if present (for user/machine-specific settings)
+if [[ -f ".envrc.local" ]]; then
+    echo "🔒 Sourcing .envrc.local..."
+    source .envrc.local
+fi
+
+# Sync dependencies (including dev dependencies)
+echo "🔄 Syncing dependencies..."
+uv sync --all-extras
+
+# Install pre-commit hooks if they don't exist
+if [[ -f ".pre-commit-config.yaml" ]] && ! uv run pre-commit --version >/dev/null 2>&1; then
+    echo "🪝 Installing pre-commit hooks..."
+    uv run pre-commit install
+fi
+
+echo "✅ Environment ready"

ado_workflows_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug Report
+about: Something isn't working as expected
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Who / What / Why
+
+- **WHO:** Who is affected? (e.g., developer using `uvx`, MCP client consumer)
+- **WHAT:** What behavior is broken or unexpected?
+- **WHY:** Why does it matter? What's the impact?
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include the full error message if applicable.
+
+## Environment
+
+- OS: [e.g., Ubuntu 24.04]
+- Python version: [e.g., 3.12.x]
+- MCP client: [e.g., VS Code Copilot, Claude Desktop]
+- Package version: [e.g., 0.1.0]
+
+## Additional Context
+
+Any other context — logs, error tracebacks, or MCP inspector output.

ado_workflows_mcp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Who / What / Why
+
+- **WHO:** Who needs this? (e.g., developer, MCP client, CI pipeline)
+- **WHAT:** What capability or behavior is needed?
+- **WHY:** Why does it matter? What problem does it solve?
+
+## Proposed Solution
+
+How do you think it should work?
+
+## Alternatives Considered
+
+Any other approaches you thought about and why they're less ideal.
+
+## Additional Context
+
+Anything else — related issues, MCP tool API sketches, or workflow examples.

ado_workflows_mcp-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+```instructions
+Before starting any task, read and follow the skill-compliance skill.
+```

ado_workflows_mcp-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## What
+
+Brief description of the change.
+
+## Why
+
+What problem does this solve or what behavior does it add?
+
+## How
+
+Key implementation details — what approach was taken and why.
+
+## Testing
+
+- [ ] All checks pass (`task check`)
+- [ ] New BDD tests added, fully specifying the new behavior
+- [ ] Existing tests unmodified (or explain why changes were needed)
+- [ ] Coverage maintained at target level
+
+## Notes
+
+Anything reviewers should pay attention to.

ado_workflows_mcp-0.1.0/.github/secret_scanning.yml

@@ -0,0 +1,2 @@
+paths-ignore:
+  - "tests/**"

ado_workflows_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint with ruff
+        if: matrix.python-version == '3.13'
+        run: uv run ruff check src/ tests/
+
+      - name: Type check with pyright
+        if: matrix.python-version == '3.13'
+        run: uv run pyright src/ tests/
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=ado_workflows_mcp --cov-report=term-missing --cov-report=json
+
+      - name: Extract coverage percentage
+        if: github.ref == 'refs/heads/main' && matrix.python-version == '3.13'
+        run: |
+          COVERAGE=$(python -c "import json; print(int(json.load(open('coverage.json'))['totals']['percent_covered']))")
+          echo "COVERAGE_PCT=$COVERAGE" >> $GITHUB_ENV
+
+      - name: Update coverage badge
+        if: github.ref == 'refs/heads/main' && matrix.python-version == '3.13'
+        uses: schneegans/dynamic-badges-action@v1.7.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: ${{ vars.COVERAGE_GIST_ID }}
+          filename: ado-workflows-mcp-coverage-badge.json
+          label: coverage
+          message: ${{ env.COVERAGE_PCT }}%
+          valColorRange: ${{ env.COVERAGE_PCT }}
+          minColorRange: 50
+          maxColorRange: 100

ado_workflows_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,110 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write    # create tags and GitHub Releases
+  id-token: write    # OIDC token for PyPI trusted publishing
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Skip release commits made by semantic-release itself
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+    outputs:
+      released: ${{ steps.tag.outputs.released }}
+      tag: ${{ steps.tag.outputs.tag }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # full history needed for commit analysis
+          fetch-tags: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install python-semantic-release
+        run: uv tool install python-semantic-release
+
+      - name: Run semantic-release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: semantic-release version --no-push --no-vcs-release --skip-build
+
+      - name: Push tag and create release
+        id: tag
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          NEW_TAG=$(git tag --points-at HEAD | grep '^v' | head -1)
+          if [ -n "$NEW_TAG" ]; then
+            echo "New version: $NEW_TAG"
+            git push origin "$NEW_TAG"
+            gh release create "$NEW_TAG" \
+              --title "$NEW_TAG" \
+              --generate-notes \
+              --latest
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "tag=$NEW_TAG" >> "$GITHUB_OUTPUT"
+          else
+            echo "No new version — no feat: or fix: commits since last tag"
+            echo "released=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  build:
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Type check
+        run: uv run pyright src/ tests/
+
+      - name: Test
+        run: uv run pytest --cov=ado_workflows_mcp --cov-report=term-missing
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi  # GitHub Environment for deployment protection
+    permissions:
+      id-token: write  # OIDC token for PyPI trusted publishing
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ado_workflows_mcp-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.json
+
+# Linting / type-checking caches
+.ruff_cache/
+.mypy_cache/
+
+# Environment
+.envrc.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Copilot work plans
+.copilot/*
+!.copilot/README.md

ado_workflows_mcp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright src/ tests/
+        language: system
+        types: [python]
+        pass_filenames: false

ado_workflows_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.1.0 (2026-03-09)
+
+- Initial Release

ado_workflows_mcp-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery and unwelcome sexual attention
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

ado_workflows_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing
+
+Thanks for your interest in contributing to ado-workflows-mcp. This document
+covers the development setup, coding standards, testing philosophy, and
+PR process.
+
+---
+
+## Development Setup
+
+```bash
+# Clone
+git clone https://github.com/grimlor/ado-workflows-mcp.git
+cd ado-workflows-mcp
+
+# Install with dev dependencies (creates .venv automatically)
+uv sync --extra dev
+
+# Optional: auto-activate venv
+direnv allow
+```
+
+## Running Checks
+
+All checks must pass before submitting a PR:
+
+```bash
+task check          # runs lint → type → test
+```
+
+Or individually:
+
+```bash
+task lint           # ruff check src/ tests/
+task format         # ruff format src/ tests/
+task type           # pyright type checking
+task test           # pytest -v
+task cov            # pytest with coverage report
+```
+
+## Code Style
+
+- **Python 3.12+** — use modern syntax (`X | Y` unions, `@dataclass`).
+- **`from __future__ import annotations`** at the top of every module.
+- **ruff** handles formatting and import sorting. Don't fight it.
+- **pyright** — all functions need type annotations. No `Any` unless
+  you have a good reason and document it.
+- **Line length:** 99 characters (configured in `pyproject.toml`).
+- **Quote style:** double quotes.
+
+## Testing Standards
+
+Tests are the living specification. Every test class documents a behavioral
+requirement, not a code structure.
+
+### Test Class Structure
+
+```python
+class TestYourFeature:
+    """
+    REQUIREMENT: One-sentence summary of the behavioral contract.
+
+    WHO: Who depends on this behavior (calling code, operator, AI agent)
+    WHAT: What the behavior is, including failure modes
+    WHY: What breaks if this contract is violated
+
+    MOCK BOUNDARY:
+        Mock:  ado_workflows SDK functions (library I/O edge)
+        Real:  tool functions, error construction, AIGuidance
+        Never: construct expected output and assert on the construction
+    """
+
+    def test_descriptive_name_of_scenario(self) -> None:
+        """
+        Given some precondition
+        When an action is taken
+        Then an observable outcome occurs
+        """
+        ...
+```
+
+### Key Principles
+
+1. **Mock I/O boundaries, not implementation.** Mock the `ado-workflows`
+   library functions — never mock internal helpers or dataclass construction.
+
+2. **Failure specs matter.** For every happy path, ask: what goes wrong?
+   Write specs for those failure modes. An unspecified failure is an
+   unhandled failure.
+
+3. **Missing spec = missing requirement.** If you find a bug, the first
+   step is always adding the test that should have caught it, then fixing
+   the code to pass that test.
+
+4. **Every assertion includes a diagnostic message.** Bare assertions are
+   not permitted.
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the tool layers,
+error propagation, and design decisions.
+
+## Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+feat: add repository context caching with session persistence
+
+- set_repository_context() validates and caches org/project/repo
+- get_repository_context_status() surfaces cached state for debugging
+- clear_repository_context() resets to force fresh discovery
+```
+
+Common prefixes: `feat:`, `fix:`, `test:`, `docs:`, `build:`, `refactor:`,
+`style:`, `ci:`, `chore:`.
+
+## Pull Requests
+
+1. **Branch from `main`.**
+2. **All checks must pass** — `task check` (lint + type + test).
+3. **Include tests** for any new behavior or bug fix.
+4. **One concern per PR** — don't mix a new feature with unrelated refactoring.
+5. **Describe what and why** in the PR description.
+
+## Reporting Issues
+
+When filing an issue:
+
+- **Bug:** Include the error message, what you expected, and steps to
+  reproduce. Include the Python version and how ado-workflows-mcp was
+  installed.
+- **Feature request:** Describe the problem you're trying to solve, not
+  just the solution you have in mind.

ado_workflows_mcp-0.1.0/LICENSE

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