@om-surushe/efficient-ado

LLM-optimized Azure DevOps workflows for AI assistants

Efficient ADO is a Model Context Protocol (MCP) server that provides AI assistants with streamlined access to Azure DevOps. Built with agent-first design principles, it minimizes round trips, reduces token usage, and provides rich contextual responses.

Features

• 🎯 Agent-First Design - Composite tools reduce round trips
• ⚡ Token Efficient - Tiered responses (summary/standard/detailed)
• 🤖 LLM-Optimized - Rich context + suggested actions in every response
• 🚀 Fast - Built with TypeScript, optimized for performance
• 📦 Complete - 34 tools covering PRs, work items, repos, branches
• 🔄 Composite Workflows - Multi-step operations in single calls
• 🧠 Error Guidance - Errors tell agents HOW to fix issues

Installation

npm install @om-surushe/efficient-ado

Quick Start

Configuration

Create a .env file:

AZDO_ORG_URL=https://dev.azure.com/your-org
AZDO_PAT=your-personal-access-token
AZDO_PROJECT=your-project  # optional
AZDO_REPO=your-repo        # optional

PAT Requirements:

• Code (Read & Write)
• Pull Request Threads (Read & Write)
• Work Items (Read & Write)

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "efficient-ado": {
      "command": "npx",
      "args": ["@om-surushe/efficient-ado"],
      "env": {
        "AZDO_ORG_URL": "https://dev.azure.com/your-org",
        "AZDO_PAT": "your-pat-here",
        "AZDO_PROJECT": "your-project",
        "AZDO_REPO": "your-repo"
      }
    }
  }
}

Usage with OpenClaw / Cline / Other MCP Clients

Similar configuration - use stdio transport with environment variables.

Available Tools (34 Total)

Foundation

• setup_workspace - Configure credentials and verify connection

Pull Request Workflows

Discovery:

• list_prs - List PRs with filters (creator, reviewer, status)
• get_pr - Get PR details with reviewers and status
• start_review - COMPOSITE - Get PR + comments + reviewers in one call

Review & Approval:

• vote_on_pr - Approve (10), approve with suggestions (5), wait (-5), reject (-10)
• manage_reviewers - Add/remove reviewers
• quick_approve - COMPOSITE - Approve + merge if ready

Merge:

• check_merge_readiness - Verify all merge requirements
• complete_pr - Merge PR with completion options

Comments & Threads:

• list_comments - List all threads (general + inline)
• add_comment - Add general or inline comment
• reply_to_thread - Reply to existing thread
• update_thread_status - Mark thread as fixed/active/wontFix/closed
• address_comment - COMPOSITE - Reply + resolve in one call

Files & Diffs:

• get_pr_changes - List changed files with stats
• get_file_diff - Get file diff (side-by-side comparison)
• get_file_content - Get file content at PR commit

PR Lifecycle:

• create_pr - Create PR with work items, reviewers, auto-complete
• update_pr - Update title, description, draft status
• abandon_pr - Close PR without merging
• reactivate_pr - Reopen abandoned PR

Work Items

• get_work_item - Get work item by ID with relations
• list_my_work_items - List work items assigned to you
• create_work_item - Create new task/bug/story
• update_work_item - Update work item fields
• add_work_item_comment - Add discussion comment
• link_work_item - Link work items (parent/child/related)

Repos & Branches

• list_repositories - List repos in project
• list_branches - List branches in repo
• create_branch - Create new branch from source
• list_commits - List commits with filters
• get_commit - Get commit details
• compare_branches - Compare two branches

Daily Workflow

• get_my_work - COMPOSITE - Dashboard: my PRs + reviews + work items

Usage Examples

Daily Standup

> "What do I need to work on today?"

Agent uses: get_my_work()

Response includes:
- PRs you created (3 active, 1 draft)
- PRs needing your review (2 pending vote)
- Work items assigned to you (5 tasks, 2 bugs)

Code Review

> "Review PR #1805"

Agent uses: start_review(prId=1805)

Gets in one call:
- PR details (title, description, status, branches)
- All comment threads (23 general + 5 inline)
- Reviewers and their votes
- Changed files overview

Then:

> "Show me the changes to config.ts"

Agent uses: get_file_diff(prId=1805, path="config.ts")

Returns side-by-side diff with line numbers

Addressing Feedback

> "Reply 'Fixed indentation' and mark thread 12345 as resolved"

Agent uses: address_comment(
  prId=1805,
  threadId=12345,
  reply="Fixed indentation",
  status="fixed"
)

One call handles both reply and status update

Approving & Merging

> "Approve PR #1805 and merge if ready"

Agent uses: quick_approve(prId=1805)

One call:
1. Approves PR (vote=10)
2. Checks merge requirements
3. Merges if all policies pass
4. Or tells you what's blocking

Creating Work from Feedback

> "Create a bug for the memory leak in thread 12345"

Agent uses:
1. list_comments(prId=1805) to get thread details
2. create_work_item(
     type="Bug",
     title="Memory leak in cache handler",
     description="Details from PR review..."
   )
3. link_work_item(workItemId=123, prId=1805)

Three calls link bug to the PR discussion

Design Philosophy

Agent-First

Every tool response includes:

• Current state - What's happening now
• Statistics - Quick metrics
• Blockers - What's preventing progress (if any)
• Suggested actions - What to do next with exact tool names

Token Efficient

Responses have levels:

• Summary (~200 tokens) - Quick status check
• Standard (~800 tokens) - Most common use
• Detailed (~3000 tokens) - When agent needs everything

Error Messages That Help

Errors tell agents HOW to fix issues:

{
  "error": {
    "code": "MERGE_BLOCKED",
    "blockers": [
      {
        "reason": "Insufficient approvals (1/2)",
        "howToFix": "Call vote_on_pr(vote=10) to approve",
        "relatedTools": ["vote_on_pr"]
      }
    ]
  }
}

Development

git clone https://github.com/om-surushe/efficient-ado.git
cd efficient-ado
npm install
npm run build

Status

• [x] Phase 1: Foundation + setup
• [x] Phase 2: Pull request workflows (15 tools)
• [x] Phase 3: Work items (6 tools)
• [x] Phase 4: Repos & branches (6 tools)
• [x] Phase 5: PR creation & update (4 tools)
• [x] Phase 6: Composite workflows (2 tools)

Total: 34 tools complete and ready for use! 🎉

Future Enhancements

• [ ] Pipeline/build tools
• [ ] Team/project management
• [ ] Wiki/documentation tools
• [ ] Artifact management
• [ ] Test plan integration

License

MIT License - see LICENSE for details.

Author

Om Surushe

• GitHub: @om-surushe
• npm: @om-surushe

Related Packages

• @om-surushe/efficient-ticktick - LLM-optimized TickTick task management
• @om-surushe/efficient-search - LLM-optimized web search

---

Part of the Efficient MCP series - LLM-optimized tools for AI assistants.