Implement Core MCP Tools (@aiswarm tools)

[mrlarson2007]

Implement Core MCP Tools

Implement the fundamental @aiswarm MCP tools that agents will use for coordination.

Parent Issue: #18 (Phase 1)

Tools to Implement

Agent Lifecycle

• @aiswarm register_agent - Register agent with coordination system
• @aiswarm update_heartbeat - Send heartbeat and get status updates
• @aiswarm get_agent_status - Check current agent status

Task Management

• @aiswarm wait_for_next_event - Block until coordination events occur
• @aiswarm claim_task - Claim ownership of available task
• @aiswarm report_progress - Report task progress with percentage
• @aiswarm report_completion - Mark task as completed
• @aiswarm check_for_tasks - Check available tasks for agent persona

Worktree Management

• @aiswarm create_worktree - Create new git worktree for agent
• @aiswarm list_worktrees - List available worktrees

Implementation Notes

• Use ModelContextProtocol.Server SDK
• Follow McpServerTool attribute pattern
• Integrate with existing ITaskCoordinationService
• Ensure proper error handling and validation

[mrlarson2007]

SIGNIFICANT PROGRESS UPDATE

Recently Completed Tools:

Agent Lifecycle (NEW):

• list_agents - List and filter agents by persona (issue 27 CLOSED)
• launch_agent - Launch new agents with persona/context (issue 29 CLOSED)
• kill_agent - Stop/terminate agents with lifecycle tracking (issue 30 CLOSED)

Task Management (PREVIOUSLY COMPLETED):

• create_task - Create tasks with agent assignment
• get_task_status - Get individual task details
• get_tasks_by_status - Filter tasks by status
• get_tasks_by_agent_id - Filter tasks by agent
• get_tasks_by_agent_id_and_status - Combined filtering (issue 26 CLOSED)

Remaining Core Tools:

• register_agent, update_heartbeat, get_agent_status
• wait_for_next_event, claim_task, report_progress, report_completion
• create_worktree, list_worktrees

Progress: 8/16 tools completed (50%)

Next priority: Agent coordination tools

[mrlarson2007]

DESIGN DECISION UPDATE

Based on recent development and usage analysis, we are making these important architectural decisions:

Remove update_heartbeat

• Rationale: Heartbeat functionality is implicitly handled by existing operations
• Implementation: get_next_task and task status updates (report_task_completion, report_task_failure) already serve as implicit heartbeats
• Benefit: Simpler API, no additional overhead, natural activity tracking

Replace wait_for_next_event with wait_for_agent_ready

• Rationale: Generic event waiting was too broad and complex for actual usage patterns
• New Focus: Agents need a simple way to wait until they are ready to start work
• Use Case: Agent starts up → waits for coordination system to be ready → begins task processing

Updated Progress Tracking

Agent Lifecycle:

• ✅ list_agents - COMPLETE
• ✅ launch_agent - COMPLETE
• ✅ kill_agent - COMPLETE
• ✅ register_agent - Handled by launch_agent
• ❌ get_agent_status - Still needed
• ❌ wait_for_agent_ready - NEW: Replace wait_for_next_event

Task Management: ✅ ALL COMPLETE (8/8 tools)

Updated Progress: 13/15 tools (87% complete)

This simplification makes the API more focused and easier to use while maintaining all necessary functionality.

[mrlarson2007]

FINAL STATUS UPDATE

MCP Tools Completion: 14/15 (93%)

Tools Implemented

Agent Lifecycle:

• ✅ list_agents
• ✅ launch_agent
• ✅ kill_agent
• ✅ register_agent (handled by launch_agent)

Task Management:

• ✅ create_task
• ✅ get_task_status
• ✅ get_tasks_by_status
• ✅ get_tasks_by_agent_id
• ✅ get_tasks_by_agent_id_and_status
• ✅ get_next_task
• ✅ report_task_completion
• ✅ report_task_failure

Memory System:

• ✅ save_memory
• ✅ read_memory

Final Tool Remaining

• ❌ wait_for_agent_ready (NEW: replaces wait_for_next_event)

Tools Removed

• ❌ get_agent_status (redundant with list_agents)
• ❌ update_heartbeat (handled implicitly by get_next_task)
• ❌ wait_for_next_event (replaced by wait_for_agent_ready)

Next Phase: Focus shifts to packaging, distribution, and operational concerns per updated roadmap.