Codebase MCP Server

# Feature Specification: Optimize list_tasks MCP Tool for Token Efficiency **Feature Branch**: `004-as-an-ai` **Created**: 2025-10-10 **Status**: Draft **Input**: User description: "As an AI coding assistant using the codebase-mcp server, I need the list_tasks MCP tool to return lightweight task summaries instead of full task details so that I can browse tasks efficiently without loading excessive token counts." ## Execution Flow (main) ``` 1. Parse user description from Input → User needs: lightweight task summaries for efficient browsing 2. Extract key concepts from description → Actors: AI coding assistants using MCP tools → Actions: list tasks, get task details → Data: task summaries (id, title, status, timestamps) vs full details → Constraints: <2000 tokens for 15 tasks, ~6x reduction from 12000+ tokens 3. For each unclear aspect: → Minimal clarifications needed - requirements are well-specified 4. Fill User Scenarios & Testing section → Clear user flow: list → scan → get details 5. Generate Functional Requirements → Each requirement is testable and measurable 6. Identify Key Entities (if data involved) → Task Summary entity, Full Task entity 7. Run Review Checklist → No implementation details included → Spec focuses on WHAT and WHY 8. Return: SUCCESS (spec ready for planning) ``` --- ## ⚡ Quick Guidelines - ✅ Focus on WHAT users need and WHY - ❌ Avoid HOW to implement (no tech stack, APIs, code structure) - 👥 Written for business stakeholders, not developers --- ## Clarifications ### Session 2025-10-10 - Q: What is the migration approach for the breaking change? → A: Immediate breaking change - all clients must update to handle new response format - Q: When list_tasks database queries fail or timeout, how should the system behave? → A: Return error response with specific error code and message (fail fast) - Q: What logging and monitoring should be captured for the list_tasks operation? → A: No logging required (internal tool, monitoring not needed) --- ## User Scenarios & Testing *(mandatory)* ### Primary User Story As an AI coding assistant using the codebase-mcp server, I want to quickly scan available tasks without loading excessive token counts. When I find a task of interest, I want to load its complete details separately. This two-tier browsing approach allows me to efficiently navigate task lists while conserving computational resources. ### Acceptance Scenarios 1. **Given** I have 15 tasks in the system, **When** I invoke list_tasks, **Then** the response loads less than 2,000 tokens and includes only task ID, title, status, created timestamp, and updated timestamp for each task 2. **Given** I receive a task summary list, **When** I identify a task I want to learn more about, **Then** I can invoke get_task with the task ID to retrieve complete details including description, notes, planning references, branches, and commits 3. **Given** I need full details for all tasks immediately, **When** I invoke list_tasks with an optional parameter, **Then** I can request full task details in the list response 4. **Given** filtering parameters (status, branch, limit), **When** I invoke list_tasks, **Then** the summary view respects all existing filtering capabilities 5. **Given** I call get_task for a specific task, **When** the task exists, **Then** I receive the complete task object unchanged from current behavior ### Edge Cases - What happens when a task has no description or notes? (Summary view should still display correctly) - How does system handle empty task lists? (Should return empty array with zero token overhead) - What happens when optional full details parameter is true? (Should return complete task objects, accepting higher token count) - How does performance scale with large task lists (100+ tasks)? (Should maintain <200ms p95 latency) - What happens when database query fails? (Return error response with specific error code and message - fail fast) - What happens when database query times out? (Return error response with timeout error code and message) ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST provide a list_tasks operation that returns task summaries by default, including only: task ID, title, status, created timestamp, and updated timestamp - **FR-002**: System MUST provide a get_task operation that returns complete task details including description, notes, planning references, branches, and commits - **FR-003**: System MUST reduce token count for listing 15 tasks from 12,000+ tokens to less than 2,000 tokens (approximately 6x reduction) - **FR-004**: System MUST support an optional parameter on list_tasks to request full task details when needed - **FR-005**: System MUST maintain existing list_tasks filtering capabilities (by status, by branch, result limit) - **FR-006**: System MUST preserve all existing get_task functionality without modification - **FR-007**: System MUST maintain query performance under 200ms p95 latency for list_tasks operations - **FR-008**: System MUST validate all response data with proper schema definitions - **FR-009**: System MUST update tool documentation to reflect the new summary/detail pattern - **FR-010**: System MUST maintain MCP protocol compliance for all tool responses ### Performance Requirements - **PR-001**: list_tasks with 15 tasks MUST load less than 2,000 tokens - **PR-002**: list_tasks query latency MUST remain under 200ms at p95 - **PR-003**: Token reduction MUST achieve approximately 6x improvement (12,000+ → <2,000) - **PR-004**: Performance optimization MUST NOT degrade get_task operation speed ### Data Requirements - **DR-001**: Task summary MUST include: id (UUID), title (string), status (enum), created_at (timestamp), updated_at (timestamp) - **DR-002**: Full task details MUST include all summary fields PLUS: description (string), notes (string), planning_references (array), branches (array), commits (array) - **DR-003**: All response schemas MUST be validated with proper type definitions ### Migration & Compatibility Requirements - **MR-001**: System MUST implement immediate breaking change to list_tasks response format (summary view becomes default) - **MR-002**: All MCP clients MUST update to handle new response format (no backward compatibility layer provided) - **MR-003**: Release notes MUST clearly document the breaking change and required client updates ### Error Handling & Reliability Requirements - **ER-001**: System MUST return specific error response when list_tasks database query fails (fail fast strategy) - **ER-002**: Error responses MUST include error code and descriptive error message - **ER-003**: System MUST return specific error response when list_tasks query times out - **ER-004**: System MUST return specific error response when get_task database query fails - **ER-005**: Error codes MUST be consistent and documented for client error handling ### Observability & Monitoring Requirements - **OM-001**: No logging or monitoring requirements for list_tasks or get_task operations (internal tool scope) - **OM-002**: System MAY rely on existing infrastructure-level logging if available, but no application-level logging is required ### Key Entities - **Task Summary**: Lightweight representation of a task for browsing purposes - Attributes: ID, title, status, created timestamp, updated timestamp - Purpose: Efficient task list scanning with minimal token usage - Relationship: Subset of Full Task entity - **Full Task**: Complete task representation with all metadata - Attributes: All Task Summary fields plus description, notes, planning references, git branches, git commits - Purpose: Detailed task information for decision-making and implementation - Relationship: Superset of Task Summary entity --- ## Review & Acceptance Checklist *GATE: Automated checks run during main() execution* ### Content Quality - [x] No implementation details (languages, frameworks, APIs) - [x] Focused on user value and business needs - [x] Written for non-technical stakeholders - [x] All mandatory sections completed ### Requirement Completeness - [x] No [NEEDS CLARIFICATION] markers remain - [x] Requirements are testable and unambiguous - [x] Success criteria are measurable (token count, latency targets) - [x] Scope is clearly bounded (list_tasks and get_task operations only) - [x] Dependencies and assumptions identified (breaking changes acceptable in early development) --- ## Execution Status *Updated by main() during processing* - [x] User description parsed - [x] Key concepts extracted (two-tier browsing, token efficiency, summary vs detail) - [x] Ambiguities marked (none - requirements well-specified) - [x] User scenarios defined - [x] Requirements generated (10 functional, 4 performance, 3 data requirements) - [x] Entities identified (Task Summary, Full Task) - [x] Review checklist passed --- ## Business Value ### Problem Statement AI coding assistants using the codebase-mcp server currently experience poor performance when browsing task lists. Loading 15 tasks consumes over 12,000 tokens, making simple browsing operations expensive and slow. This creates a poor user experience and wastes computational resources. ### Value Proposition By implementing a two-tier browsing pattern (summary list + detailed view), users can: - **Reduce computational cost by 6x** for task browsing operations - **Improve response times** by loading only necessary data - **Enable efficient task scanning** without sacrificing access to detailed information - **Follow established API design patterns** (list returns summaries, get returns details) ### Success Metrics - Token usage for 15-task list: <2,000 tokens (down from 12,000+) - Query latency: <200ms p95 for list operations - User satisfaction: Faster task browsing with no loss of functionality