agile-project-mcp/docs/project-tools.md

API Tools Guide 🛠️

Welcome to your AI team's toolbox! Think of these as the commands your agents use to get work done. When you're running the server, check out /docs for the interactive API playground.

💬 Talk to Your Team Leaders

Want to chat with specific team members? These tools route your questions to the right agent:

client_ask_product_owner

Talk to: 👔 Product Owner Use when: You have new feature ideas or want to discuss priorities Example:

{
  "message": "I'd like to add social login to our app. What do you think?"
}

Response: "Great idea! Social login would improve user experience. Let me add this to our backlog as a 'Should have' feature..."

client_ask_scrum_master

Talk to: 🏃 Scrum Master Use when: Something's blocking progress or you want process updates Example:

{
  "message": "The team seems stuck on the payment integration. What's happening?"
}

Response: "I see Dev #2 is blocked on payment provider documentation. I'm creating a research task to unblock them..."

client_ask_business_analyst

Talk to: 📊 Business Analyst Use when: You need detailed requirements or acceptance criteria Example:

{
  "message": "What exactly should happen when a user forgets their password?"
}

Response: "Let me clarify the password reset flow with specific acceptance criteria..."

client_ask_project_manager

Talk to: 📋 Project Manager Use when: You want status updates or timeline information Example:

{
  "message": "How's the current sprint going? Are we on track?"
}

Response: "We're 60% through the sprint with 4 of 7 stories completed. We're on track to finish by Friday..."

📋 Priority Management (MoSCoW)

The Product Owner uses these to manage what gets built and when:

MoSCoW = Must/Should/Could/Won't Have

Example priority list:

Must have:
  - User login
  - Password reset
  - Basic profile page

Should have:
  - Social media login
  - Email notifications

Could have:
  - Dark mode
  - Profile customization

Won't have (this release):
  - Mobile app
  - Advanced analytics

Available Tools

• create_moscow_list - Start a new priority list
• get_moscow_list - See current priorities
• update_moscow_list - Change priorities as needed

📝 Story & Backlog Tools

These are the bread and butter of your agile workflow:

Creating Work Items

create_story - Birth of a new feature

{
  "title": "User can reset password",
  "description": "Allow users to reset forgotten passwords via email",
  "story_type": "feature"
}

Creates → STORY-001

create_bug - Report issues

{
  "title": "Log-in button not working on Safari",
  "description": "Users can't click log-in on Safari mobile",
  "severity": "high",
  "steps_to_reproduce": "1. Open Safari\n2. Go to log-in page\n3. Try to click log-in"
}

Managing Stories

add_acceptance_criteria - Define "done"

{
  "story_id": "STORY-001",
  "criteria": [
    "User receives reset email within 2 minutes",
    "Reset link expires after 24 hours",
    "User can set new password with link"
  ]
}

update_story_status - Progress updates

{
  "story_id": "STORY-001",
  "status": "Working on email integration, 70% complete"
}

mark_story_blocked - Flag problems

{
  "story_id": "STORY-001",
  "reason": "Email service API key not configured"
}

Research Tasks

When the team hits unknowns:

create_research_task → get_research_task → submit_research_findings

Example flow:

1. SM creates: "Research best email service for password resets"
2. Researcher investigates: "Comparing SendGrid, AWS SES, Mailgun..."
3. Findings submitted: "Recommend SendGrid for ease of use and pricing"

🏃 Sprint Management

Tools for organizing work into time-boxed iterations:

Sprint Lifecycle

1. create_sprint - Start a new sprint

{
  "name": "Sprint 5",
  "start_date": "2024-01-15",
  "end_date": "2024-01-29"
}

2. add_story_to_sprint - Fill the sprint

{
  "story_id": "STORY-001",
  "sprint_id": "SPRINT-5"
}

3. assign_story - Give work to agents

{
  "story_id": "STORY-001",
  "agent_role": "developer",
  "agent_id": "dev-1"
}

4. update_board_status - Track progress

{
  "story_id": "STORY-001",
  "from_column": "in-dev",
  "to_column": "in-qa"
}

Board Columns Flow

backlog → ready → in-dev → in-qa → done
                     ↓         ↓
                  blocked   failed-qa

🎯 Working with Artifacts

Agents attach their work outputs to stories:

add_artefact_to_story - Attach deliverables

{
  "story_id": "STORY-001",
  "artefact_type": "code_patch",
  "content": "diff --git a/auth.py...",
  "filename": "password-reset.patch"
}

Artifact types:

• code_patch - Code changes
• test_results - QA reports
• documentation - User guides
• research_findings - Investigation results

📚 Knowledge Base

Store and retrieve project wisdom:

add_knowledge_article - Document learnings

{
  "title": "Email Service Setup Guide",
  "content": "To configure SendGrid: 1. Get API key from...",
  "tags": ["email", "configuration", "setup"]
}

search_knowledge_base - Find answers

{
  "query": "email configuration"
}

Returns relevant articles ranked by relevance.

🎮 Pro Tips

For External Clients

1. Start conversations with team leaders using client_ask_* tools
2. Check get_board_status for real-time progress
3. Use get_sprint_plan to see what's being worked on

For Agent Workflows

1. Developers use get_next_task to find work
2. QA uses submit_for_review to pass/fail stories
3. Everyone uses add_comment_to_story for communication

Best Practices

• Keep story titles under 10 words
• Write acceptance criteria as testable statements
• Update story status at least every 30 minutes
• Attach artifacts immediately after creating them
• Use knowledge base for anything others might need to know

🚀 Quick Start Example

Here's a complete flow from idea to implementation:

1. You: "I want user authentication"
2. PO creates MoSCoW list with login as "Must have"
3. BA creates story "User can log in with email"
4. BA adds acceptance criteria
5. PM creates sprint and adds story
6. PM assigns to Developer
7. Dev codes, attaches patch, moves to QA
8. QA tests, approves, moves to done
9. You: See working log-in feature! 🎉

Remember: The full interactive API docs are always available at /docs when your server is running!