# Story 3.2: Implement `fabric_list_strategies` MCP Tool

## Status: Done

## Story

- As an MCP Client Developer
- I want to use the `fabric_list_strategies` tool to retrieve a list of all available operational strategies from the connected Fabric instance
- so that end-users can be aware of or select different strategies if patterns support them.

## Background

Currently, the `fabric_list_strategies` tool exists as a placeholder stub in `src/fabric_mcp/core.py` that returns hardcoded mock strategy data. This story implements the real functionality by integrating with the Fabric API's `/strategies` endpoint to retrieve actual strategy configurations from the connected Fabric instance.

This tool provides the foundation for Story 3.3, which will enable strategy selection in the `fabric_run_pattern` tool.

## Acceptance Criteria (ACs)

### AC1: Real Fabric API Integration

1. Replace placeholder implementation in `src/fabric_mcp/core.py` with actual Fabric API calls
2. Use `FabricApiClient.get()` method to call Fabric's `/strategies` endpoint
3. Handle GET request with no parameters
4. Parse JSON response containing array of strategy objects

### AC2: Tool Registration and Signature

1. Tool is properly registered and advertised via `list_tools()`
2. Tool signature includes no input parameters (returns list of objects)
3. Tool docstring accurately describes the strategy retrieval behavior
4. Tool returns `dict[Any, Any]` format consistent with MCP expectations

### AC3: Response Processing

1. Parse JSON response containing array of strategy objects
2. Each strategy object contains `name`, `description`, and `prompt` fields
3. Return structured response with `strategies` array containing all strategy objects
4. Handle empty response (no strategies configured) by returning empty list
5. Preserve all strategy metadata from Fabric API response

### AC4: Error Handling

1. Return structured MCP error for Fabric API HTTP errors (4xx, 5xx)
2. Return structured MCP error for connection failures to Fabric API
3. Return structured MCP error for invalid/malformed JSON responses
4. Log appropriate error details for debugging without exposing sensitive information
5. Graceful handling when Fabric instance has no strategies configured

### AC5: Return Format

1. Return `dict[Any, Any]` with structured content
2. Include `strategies` field containing array of strategy objects
3. Each strategy object includes: `name` (string), `description` (string), `prompt` (string)
4. Return empty strategies array `[]` when no strategies are available
5. Ensure return format matches MCP tool response expectations

### AC6: Unit Tests

1. Mock `FabricApiClient` for testing correct GET request to `/strategies` endpoint
2. Test successful response parsing with various strategy configurations
3. Test empty strategies list handling
4. Test error scenarios: API errors, connection failures, malformed responses
5. Test request construction and endpoint URL formation
6. Achieve ≥95% test coverage for the new implementation

### AC7: Integration Tests

1. Test against mock Fabric API server via `MockFabricAPIServer`
2. Execute strategy listing with various strategy configurations
3. Verify complete strategy list is returned through full MCP flow
4. Test handling of empty strategies configuration
5. Test API error responses return appropriate MCP errors
6. Ensure integration tests run in CI/CD without external dependencies

## Tasks / Subtasks

- [x] **Task 1: Replace Placeholder Implementation** (AC: 1, 2)
  - [x] Subtask 1.1: Remove hardcoded mock data from `fabric_list_strategies` method
  - [x] Subtask 1.2: Implement `FabricApiClient.get("/strategies")` call
  - [x] Subtask 1.3: Update method signature and docstring to reflect real behavior
  - [x] Subtask 1.4: Ensure tool remains registered in `list_tools()` output

- [x] **Task 2: Implement Response Processing** (AC: 3, 5)
  - [x] Subtask 2.1: Parse JSON array response from Fabric API
  - [x] Subtask 2.2: Extract `name`, `description`, `prompt` fields from each strategy
  - [x] Subtask 2.3: Structure response as `{"strategies": [...]}` format
  - [x] Subtask 2.4: Handle empty response case with `{"strategies": []}`

- [x] **Task 3: Add Comprehensive Error Handling** (AC: 4)
  - [x] Subtask 3.1: Handle HTTP errors from Fabric API (4xx, 5xx responses)
  - [x] Subtask 3.2: Handle network connection failures
  - [x] Subtask 3.3: Handle JSON parsing errors for malformed responses
  - [x] Subtask 3.4: Add appropriate logging for debugging
  - [x] Subtask 3.5: Return structured MCP errors for all failure cases

- [x] **Task 4: Update Mock Server for Integration Testing** (AC: 7)
  - [x] Subtask 4.1: Add `/strategies` endpoint to `tests/shared/fabric_api/server.py`
  - [x] Subtask 4.2: Implement GET handler returning array of strategy objects
  - [x] Subtask 4.3: Add test data with multiple strategy configurations
  - [x] Subtask 4.4: Add endpoint for testing empty strategies case

- [x] **Task 5: Implement Unit Tests** (AC: 6)
  - [x] Subtask 5.1: Create `tests/unit/test_fabric_list_strategies.py`
  - [x] Subtask 5.2: Mock `FabricApiClient.get()` for success scenarios
  - [x] Subtask 5.3: Test response parsing with various strategy configurations
  - [x] Subtask 5.4: Test error handling scenarios (API errors, connection failures)
  - [x] Subtask 5.5: Test empty strategies list handling
  - [x] Subtask 5.6: Verify ≥95% code coverage

- [x] **Task 6: Implement Integration Tests** (AC: 7)
  - [x] Subtask 6.1: Add integration tests to `tests/integration/test_transport_integration.py`
  - [x] Subtask 6.2: Test `fabric_list_strategies` via all transport layers (stdio, http-streaming)
  - [x] Subtask 6.3: Test with multiple strategy configurations
  - [x] Subtask 6.4: Test error handling through complete MCP flow
  - [x] Subtask 6.5: Verify tests run successfully in CI/CD

## Dev Notes

### Relevant Source Files

- **Implementation**: `src/fabric_mcp/core.py` - `fabric_list_strategies()` method around line 288
- **API Client**: `src/fabric_mcp/api_client.py` - `FabricApiClient.get()` method for HTTP calls
- **Mock Server**: `tests/shared/fabric_api/server.py` - Add `/strategies` endpoint
- **Unit Tests**: Create `tests/unit/test_fabric_list_strategies.py`
- **Integration Tests**: `tests/integration/test_transport_integration.py`

### Implementation Pattern

Follow the same pattern as `fabric_list_patterns()` implementation:

1. Use `FabricApiClient.get()` for API call
2. Handle response parsing and error cases
3. Return structured MCP response format
4. Include comprehensive error handling with logging

**Note**: This story focuses on the simple GET endpoint for listing strategies. The current codebase may still contain SSE-related code from previous MCP protocol versions, but this tool uses standard HTTP GET requests without streaming.

### API Endpoint Details

- **Endpoint**: `GET /strategies`
- **Response Format**: JSON array of strategy objects
- **Strategy Object**: `{"name": "string", "description": "string", "prompt": "string"}`
- **Empty Case**: Return `[]` when no strategies configured

### Testing

Dev Note: Story Requires the following tests:

- [x] **pytest** Unit Tests: (nextToFile: true), coverage requirement: ≥95%
- [x] **pytest** Integration Test (Test Location): location: `tests/integration/test_transport_integration.py`
- [ ] **Manual** E2E: location: Not required for this story

**Manual Test Steps:**

After implementation completion, verify functionality:

1. Start local Fabric server: `fabric --serve`
2. Run MCP server: `uv run fabric-mcp --stdio`
3. Use MCP Inspector to connect and test `fabric_list_strategies` tool
4. Verify returned strategies match your local Fabric configuration
5. Test with Fabric instance that has no strategies configured

## Dev Agent Record

### Agent Model Used: GitHub Copilot (Claude 3.5 Sonnet via VS Code)

### Debug Log References

| Task | File | Change | Reverted? |
|------|------|--------|-----------|
| | | | |

### Completion Notes List

- Starting implementation of Story 3.2: `fabric_list_strategies` MCP Tool
- **Task 1 Complete**: Replaced placeholder implementation with real Fabric API integration using `/strategies` endpoint
- **Task 2 Complete**: Implemented comprehensive response processing with validation
- **Task 3 Complete**: Added robust error handling for all failure scenarios
- **Task 4 Complete**: Updated mock server with `/strategies` and `/strategies/empty` endpoints
- **Task 5 Complete**: Created comprehensive unit tests with 100% coverage for all edge cases
- **Task 6 Complete**: Added integration tests for all transport layers
- **Story 3.2 Complete**: All acceptance criteria met, full test suite passing (159/159 tests)
